Expectations & Matchers

## One matcher, one Ruby method RSpec's equality matchers do not define equality themselves. Each one calls a Ruby method on the **actual** value (the thing inside `expect(...)`) and passes if it returns truthy: | Matcher | Calls | Passes when | Typical use | |---|---|---|---| | `eq(expected)` | `actual == expected` | values are equal | almost every value check | | `eql(expected)` | `actual.eql?(expected)` | equal and, for numbers, same class | type-strict value checks | | `equal(expected)` | `actual.equal?(expected)` | same object | identity of an instance | | `be(expected)` | `actual.equal?(expected)` | same object | identity, reads well with `nil`, `true` | | `be` (no argument) | truthiness | actual is neither `nil` nor `false` | presence of any value | What `==`, `eql?` and `equal?` mean for a given class is Ruby's business; RSpec only chooses which one to call. That is why a custom class that defines `==` works with `eq` automatically. ## Checking an order total Suppose `order.total_cents` returns the Integer `1999`: ```ruby expect(order.total_cents).to eq(1999) # passes expect(order.total_cents).to eq(1999.0) # passes: 1999 == 1999.0 expect(order.total_cents).to eql(1999.0) # fails: Integer vs Float expect(order.total_cents).to eql(1999) # passes ``` `eql` is the matcher to use when the **type** is part of the contract, for example when a rounding change must not silently turn an Integer total into a Float. For most totals `eq` is right, and a Float total compared with `eq` against a decimal literal may fail on rounding; `be_within(0.01).of(19.99)` exists for that case. ## Checking object identity `equal` and single-argument `be` are the same check. They answer "is this the very object I already hold?": ```ruby expect(line_item.order).to be(order) # same instance expect(order.line_items).to equal(order.line_items) # true only if memoized expect([1, 2]).to equal([1, 2]) # fails: two arrays ``` Identity matters when code promises to return a cached or shared instance. For plain values it is usually the wrong question: two separately built arrays with the same contents are `==` but not `equal?`. Small Integers, Symbols, `nil`, `true` and `false` are single objects in Ruby, so `be(nil)` and `be(true)` behave as expected; `be_nil`, `be_truthy` and `be_falsey` read better for those. ## Bare be and truthiness With no argument, `be` becomes a truthiness matcher: - `expect(order.discount).to be` passes for `0`, `""` and `[]`, because Ruby treats every value except `nil` and `false` as truthy. - `be_truthy` and `be_falsey` state the same intent explicitly. - `be true` is different: it calls `equal?(true)` and fails for `1` or `"yes"`. Operators hang off bare `be` as well: `expect(order.total_cents).to be > 0` compares with `>`. ## Reading the failure Each equality failure prints the expected and actual values and names the comparison, for example `(compared using ==)` or `(compared using eql?)`. `eq` and `eql` also print a diff for multi-line strings and larger structures. Choosing the matcher that matches the intent pays off here: 1. A total that is off by one shows two numbers and `==`, which points at arithmetic. 2. An `eql` failure between `1999` and `1999.0` points at a type change. 3. An identity failure between two identical-looking objects points at a missing cache or a copy. ## Value objects `eq` is only as good as the class's `==`. Two practical consequences: - A `Data.define` value object, such as `Money = Data.define(:cents, :currency)`, defines `==` and `eql?` by its members, so `eq(Money.new(cents: 1999, currency: "EUR"))` works out of the box. - A plain class that never defined `==` inherits identity from `Object`, so `eq` on two separately built instances fails exactly like `equal`. The fix is to define equality on the class, or to compare attributes with `have_attributes`. ## Common mistakes - Using `equal` for strings or arrays and being surprised when equal contents fail. - Writing `expect(x).to be` intending "is true" and letting `0` or an empty string pass. - Expecting `eq` to be type-strict; it is only as strict as the class's `==`.