RSpec Expectations

Each matcher can be used with expect(..).to or expect(..).not_to to define positive and negative expectations respectively on an object. Most matchers can also be accessed using the (...).should and (...).should_not syntax; see using should syntax for why we recommend using expect.

Built-in Matchers

be

Object identity

expect(actual).to be(expected) # passes if actual.equal?(expected)

eq

Object equivalence

expect(actual).to eq(expected) # passes if actual == expected

eql

equal

Optional APIs for identity/equivalence

expect(actual).to eql(expected)   # passes if actual.eql?(expected)
expect(actual).to equal(expected) # passes if actual.equal?(expected)

NOTE: expect does not support == matcher.

be >

be >=

be <=

be <

be_between

match

be_within .. of

start_with

end_with

Comparisons

expect(actual).to be >  expected
expect(actual).to be >= expected
expect(actual).to be <= expected
expect(actual).to be <  expected
expect(actual).to be_between(minimum, maximum).inclusive
expect(actual).to be_between(minimum, maximum).exclusive
expect(actual).to match(/expression/)
expect(actual).to be_within(delta).of(expected)
expect(actual).to start_with expected
expect(actual).to end_with expected

NOTE: expect does not support =~ matcher.

be_instance_of

be_kind_of

respond_to

Types/classes/response

expect(actual).to be_instance_of(expected)
expect(actual).to be_kind_of(expected)
expect(actual).to respond_to(expected)

be_truthy

be true

be_falsey

be false

be_nil

exist

Truthiness and existentialism

expect(actual).to be_truthy    # passes if actual is truthy (not nil or false)
expect(actual).to be true      # passes if actual == true
expect(actual).to be_falsey    # passes if actual is falsy (nil or false)
expect(actual).to be false     # passes if actual == false
expect(actual).to be_nil       # passes if actual is nil
expect(actual).to exist        # passes if actual.exist? and/or actual.exists? are truthy
expect(actual).to exist(*args) # passes if actual.exist?(*args) and/or actual.exists?(*args) are truthy

raise_error

Expecting errors

expect { ... }.to raise_error
expect { ... }.to raise_error(ErrorClass)
expect { ... }.to raise_error("message")
expect { ... }.to raise_error(ErrorClass, "message")

throw_symbol

Expecting throws

expect { ... }.to throw_symbol
expect { ... }.to throw_symbol(:symbol)
expect { ... }.to throw_symbol(:symbol, 'value')

be_*

have_*

Predicate matchers

expect(actual).to be_xxx         # passes if actual.xxx?
expect(actual).to have_xxx(:arg) # passes if actual.has_xxx?(:arg)

Examples

expect([]).to      be_empty
expect(:a => 1).to have_key(:a)

include

match_array

contain_exactly

Collection membership

expect(actual).to include(expected)
expect(array).to match_array(expected_array)
# ...which is the same as:
expect(array).to contain_exactly(individual, elements)

Examples

expect([1, 2, 3]).to     include(1)
expect([1, 2, 3]).to     include(1, 2)
expect(:a => 'b').to     include(:a => 'b')
expect("this string").to include("is str")
expect([1, 2, 3]).to     contain_exactly(2, 1, 3)
expect([1, 2, 3]).to     match_array([3, 2, 1])

cover

Ranges (1.9 only)

expect(1..10).to cover(3)

change .. from .. to

change .. by

change .. by_at_least

change .. by_at_most

Change observation

expect { object.action }.to change(object, :value).from(old).to(new)
expect { object.action }.to change(object, :value).by(delta)
expect { object.action }.to change(object, :value).by_at_least(minimum_delta)
expect { object.action }.to change(object, :value).by_at_most(maximum_delta)

Examples

expect { a += 1 }.to change { a }.by(1)
expect { a += 3 }.to change { a }.from(2)
expect { a += 3 }.to change { a }.by_at_least(2)

satisfy

Satisfy

expect(actual).to satisfy { |value| value == expected }

output

Output capture

expect { actual }.to output("some output").to_stdout
expect { actual }.to output("some error").to_stderr

yield_control

yield_with_no_args

yield_with_args

yield_successive_args

Block expectation

expect { |b| object.action(&b) }.to yield_control
expect { |b| object.action(&b) }.to yield_with_no_args           # only matches no args
expect { |b| object.action(&b) }.to yield_with_args              # matches any args
expect { |b| object.action(&b) }.to yield_successive_args(*args) # matches args against multiple yields

Examples

expect { |b| User.transaction(&b) }.to yield_control
expect { |b| User.transaction(&b) }.to yield_with_no_args
expect { |b| 5.tap(&b)            }.not_to yield_with_no_args         # because it yields with `5`
expect { |b| 5.tap(&b)            }.to yield_with_args(5)             # because 5 == 5
expect { |b| 5.tap(&b)            }.to yield_with_args(Fixnum)        # because Fixnum === 5
expect { |b| [1, 2, 3].each(&b)   }.to yield_successive_args(1, 2, 3)