Module: RSpec::Expectations

RSpec::Expectations provides a simple, readable API to express the expected outcomes in a code example. To express an expected outcome, wrap an object or block in expect, call to or to_not (aliased as not_to) and pass it a matcher object:

expect(order.total).to eq(Money.new(5.55, :USD))
expect(list).to include(user)
expect(message).not_to match(/foo/)
expect { do_something }.to raise_error

The last form (the block form) is needed to match against ruby constructs that are not objects, but can only be observed when executing a block of code. This includes raising errors, throwing symbols, yielding, and changing values.

When expect(...).to is invoked with a matcher, it turns around and calls matcher.matches?(<object wrapped by expect>). For example, in the expression:

expect(order.total).to eq(Money.new(5.55, :USD))

...eq(Money.new(5.55, :USD)) returns a matcher object, and it results in the equivalent of eq.matches?(order.total). If matches? returns true, the expectation is met and execution continues. If false, then the spec fails with the message returned by eq.failure_message.

Given the expression:

expect(order.entries).not_to include(entry)

...the not_to method (also available as to_not) invokes the equivalent of include.matches?(order.entries), but it interprets false as success, and true as a failure, using the message generated by include.failure_message_when_negated.

rspec-expectations ships with a standard set of useful matchers, and writing your own matchers is quite simple.

See RSpec::Matchers for more information about the built-in matchers that ship with rspec-expectations, and how to write your own custom matchers.