rspec-matchers

# RSpec Matchers Matchers are the building blocks of RSpec expectations. They define what you're testing and how values should compare. ## Basic Syntax ```ruby expect(actual).to matcher(expected) expect(actual).not_to matcher(expected) # or to_not ``` ## Equality Matchers ### eq - Value Equality Tests value equality using `==`: ```ruby expect(5).to eq(5) expect("hello").to eq("hello") expect([1, 2, 3]).to eq([1, 2, 3]) ``` ### eql - Value and Type Equality Tests using `eql?` (same value and type): ```ruby expect(5).to eql(5) expect(5.0).not_to eql(5) # Different types ``` ### equal / be - Identity Tests object identity using `equal?`: ```ruby a = "hello" b = a expect(a).to equal(b) # Same object expect(a).to be(b) # Alias for equal c = "hello" expect(a).not_to equal(c) # Different objects, same value ``` ## Comparison Matchers ```ruby expect(10).to be > 5 expect(10).to be >= 10 expect(10).to be < 20 expect(10).to be <= 10 expect(10).to be_between(5, 15).inclusive expect(10).to be_between(5, 15).exclusive expect(10).to be_within(0.1).of(10.05) ``` ## Truthiness Matchers ```ruby expect(true).to be true expect(false).to be false expect(nil).to be nil expect(nil).to be_nil expect(1).to be_truthy # Truthy (not nil/false) expect(nil).to be_falsey # Falsey (nil or false) ``` ## Type Matchers ```ruby expect(user).to be_a(User) expect(user).to be_an(Admin) # Alias expect(user).to be_an_instance_of(User) expect(user).to be_a_kind_of(User) # Includes subclasses ``` ## Collection Matchers ### include ```ruby expect([1, 2, 3]).to include(2) expect([1, 2, 3]).to include(1, 3) expect("hello world").to include("world") expect({ a: 1, b: 2 }).to include(a: 1) expect({ a: 1, b: 2 }).to include(:a) ``` ### contain_exactly Matches array with exact elements, any order: ```ruby expect([1, 2, 3]).to contain_exactly(3, 2, 1) expect([1, 2, 3]).to match_array([3, 1, 2]) # Alias ``` ### start_with / end_with ```ruby expect([1, 2, 3]).to start_with(1) expect([1, 2, 3]).to start_with(1, 2) expect("hello").to start_with("he") expect("hello").to end_with("lo") ``` ### all Every element matches: ```ruby expect([1, 3, 5]).to all(be_odd) expect(users).to all(be_valid) expect(numbers).to all(be > 0) ``` ### have_attributes ```ruby expect(user).to have_attributes(name: "John", age: 30) expect(user).to have_attributes( name: a_string_starting_with("J"), age: a_value > 18 ) ``` ## Predicate Matchers Any method ending in `?` becomes a matcher with `be_`: ```ruby expect(user).to be_valid # calls user.valid? expect(list).to be_empty # calls list.empty? expect(user).to be_admin # calls user.admin? expect(order).to be_pending # calls order.pending? ``` For `has_*` methods, use `have_`: ```ruby expect(hash).to have_key(:name) # calls hash.has_key?(:name) expect(user).to have_permissions # calls user.has_permissions? ``` ## String Matchers ```ruby expect("hello world").to match(/world/) expect("hello world").to match("world") expect("hello").to start_with("he") expect("hello").to end_with("lo") expect("hello").to include("ell") ``` ## Change Matcher Test side effects: ```ruby expect { user.save }.to change(User, :count).by(1) expect { user.save }.to change(User, :count).from(0).to(1) expect { user.activate! }.to change(user, :active).from(false).to(true) # Block syntax for complex changes expect { order.complete! }.to change { order.reload.status }.to("completed") ``` ## Raise and Throw Matchers ```ruby expect { raise "error" }.to raise_error expect { raise "error" }.to raise_error("error") expect { raise ArgumentError }.to raise_error(ArgumentError) expect { raise ArgumentError, "bad arg" }.to raise_error(ArgumentError, "bad arg") expect { raise ArgumentError, "bad arg" }.to raise_error(ArgumentError, /bad/) # Throw expect { throw :done }.to throw_symbol expect { throw :done }.to throw_symbol(:done) expect { throw :done, 42 }.to throw_symbol(:done, 42) ``` ## Output Matchers ```ruby expect { puts "hello" }.to output("hello\n").to_stdout expect { warn "error" }.to output(/error/).to_stderr expect { print "hi" }.to output("hi").to_stdout ``` ## Compound Matchers Combine matchers with `and` / `or`: ```ruby expect(user.age).to be >= 18 and be < 65 expect(string).to start_with("Hello").and end_with("!") expect(result).to eq(1).or eq(2) # Using described_as for better failure messages expect(value).to(be > 0).and(be < 100).described_as("between 0 and 100") ``` ## Composable Matchers Use matchers as arguments to other matchers: ```ruby expect(users).to include( a_user_with(name: "John"), a_user_with(name: "Jane") ) expect([1, 2, 3]).to include(a_value > 2) expect(response).to have_attributes( status: a_value_between(200, 299), body: a_string_including("success") ) ``` ### Built-in Aliases ```ruby a_string_starting_with("hello") a_string_ending_with("world") a_string_including("test") a_string_matching(/pattern/) a_value_between(1, 10) a_value_within(0.1).of(5.0) a_hash_including(key: value) an_instance_of(User) a_kind_of(User) an_object_eq_to(expected) ``` ## Custom Matchers ### Simple Custom Matcher ```ruby RSpec::Matchers.define :be_a_multiple_of do |expected| match do |actual| actual % expected == 0 end end expect(9).to be_a_multiple_of(3) ``` ### With Failure Messages ```ruby RSpec::Matchers.define :be_valid_email do match do |actual| actual =~ /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i end failure_message do |actual| "expected #{actual.inspect} to be a valid email address" end failure_message_when_negated do |actual| "expected #{actual.inspect} not to be a valid email address" end end ``` ### With Chain Methods ```ruby RSpec::Matchers.define :have_errors_on do |attribute| match do |model| model.valid? @errors = model.errors[attribute] @errors.present? && (@message.nil? || @errors.include?(@message)) end chain :with_message do |message| @message = message end failure_message do |model| "expected #{model.class} to have errors on #{attribute}" end end expect(user).to have_errors_on(:email).with_message("is invalid") ``` ## Matcher Cheat Sheet | Matcher | Description | |---------|-------------| | `eq(x)` | Value equality (==) | | `eql(x)` | Value + type equality | | `equal(x)` / `be(x)` | Object identity | | `be_truthy` | Not nil/false | | `be_falsey` | Nil or false | | `be > x` | Comparison | | `include(x)` | Contains element | | `match(/x/)` | Regex match | | `raise_error(E)` | Raises exception | | `change { }` | Side effect | | `have_attributes(h)` | Object attributes | | `all(matcher)` | All elements match | | `contain_exactly(...)` | Exact elements, any order |