Provides a readable API to express expected outcomes of a code example
Breaking Changes for 3.0.0:
RSpec constant using
Rspec or Spec. (Myron Marston)RSpec::Expectations.differ=. (Myron Marston)expect(...).should. (Myron Marston)expect { }.not_to change { } with by,
by_at_least, by_at_most or to. These have never been supported
but did not raise explicit errors. (Myron Marston)=== rather than == as an alias of matches? for
all matchers. The semantics of === are closer to an RSpec
matcher than ==. (Myron Marston)RSpec::Matchers::OperatorMatcher constant.
(Myron Marston)RSpec::Expectations::ExpectationNotMetError subclass
Exception rather than StandardError so they can bypass
a bare rescue in end-user code (e.g. when an expectation is
set from within a rspec-mocks stub implementation). (Myron Marston)Enhancements:
be matcher when matching against:
true, false and nil. (Sam Phippen)expect syntax. If you want your matchers to
maintain compatibility with multiple versions of RSpec, you can
alias the new names to the old. (Myron Marston)
failure_message_for_should => failure_message
failure_message_for_should_not => failure_message_when_negated
match_for_should => match
match_for_should_not => match_when_negated
change matcher. (Myron Marston)and and or.
Simply chain them off of any existing matcher to create an expression
like expect(alphabet).to start_with("a").and end_with("z").
(Eloy Espinaco)contain_exactly as a less ambiguous version of match_array.
Note that it expects the expected array to be splatted as
individual args: expect(array).to contain_exactly(1, 2) is
the same as expect(array).to match_array([1, 2]). (Myron Marston)contain_exactly/match_array so that it can match against
other non-array collections (such as a Set). (Myron Marston)RSpec::Matchers::Composable mixin that can be used to make
a custom matcher composable as well. Note that custom matchers
defined via RSpec::Matchers.define already have this. (Myron
Marston)RSpec::Machers.alias_matcher so users can define their own
matcher aliases. The description of the matcher will reflect the
alternate matcher name. (Myron Marston)be_between matcher. be_between has worked for a
long time as a dynamic predicate matcher, but the failure message
was suboptimal. The new matcher provides a much better failure
message. (Erik Michaels-Ober)be_between matcher to allow for inclusive or exclusive
comparison (e.g. inclusive of min/max or exclusive of min/max).
(Pedro Gimenez)not_to be #{operator} less confusing by
only saying it's confusing when comparison operators are used.
(Prathamesh Sonpatki)eq matcher when Time or DateTime
objects are used so that the full sub-second precision is included.
(Thomas Holmes, Jeff Wallace)output matcher for expecting that a block outputs to_stdout
or to_stderr. (Luca Pette, Matthias Günther)has_xyz? method call when
the have_xyz matcher is used. (Damian Galarza)rspec/expectations/minitest_integration after loading minitest
to use rspec-expectations with minitest. (Myron Marston)Bug Fixes:
expect { }.not_to change { }.from(x) so that the matcher only
passes if the starting value is x. (Tyler Rick, Myron Marston)ArgumentError when given an object of the wrong type to match
against, so that they work well in composite matcher expressions like
expect([1.51, "foo"]).to include(a_string_matching(/foo/), a_value_within(0.1).of(1.5)).
(Myron Marston)Deprecations:
shoulda), but it will print
a deprecation warning. (Myron Marston)Deprecations:
by, by_at_least, by_at_most or to off of
expect { }.not_to change { }. The docs have always said these are
not supported for the negative form but now they explicitly raise
errors in RSpec 3. (Myron Marston)expect { }.not_to change { x }.from(y).
In RSpec 2.x, this expectation would only fail if x started with
the value of y and changed. If it started with a different value
and changed, it would pass. In RSpec 3, it will pass only if the
value starts at y and it does not change. (Myron Marston)matcher == value as an alias for matcher.matches?(value),
in favor of matcher === value. (Myron Marston)RSpec::Matchers::OperatorMatcher in favor of
RSpec::Matchers::BuiltIn::OperatorMatcher. (Myron Marston)RSpec::Matchers in the appropriate test case
base class yourself. (Myron Marston)#expected on a DSL-generated custom matcher
as an array when only 1 argument is passed to the matcher method.
In RSpec 3 it will be the single value in order to make diffs
work properly. (Jon Rowe)Deprecations
have, have_at_least and have_at_most. You can continue using those
matchers through https://github.com/rspec/rspec-collection_matchers, or
you can rewrite your expectations with something like
expect(your_object.size).to eq(num). (Hugo Baraúna)be_xyz predicate matcher when xyz? is a private method.
(Jon Rowe)be_true/be_false in favour of be_truthy/be_falsey
(for Ruby's conditional semantics) or be true/be false
(for exact equality). (Sam Phippen)def self.foo / extend Helper can be used to add macro methods
(e.g. methods that call the custom matcher DSL methods), but should
not be used to define helper methods called from within the DSL
blocks.def foo / include Helper is the opposite: it's for helper methods
callable from within a DSL block, but not for defining macros.Breaking Changes for 3.0.0:
be_close matcher, preferring be_within instead.
(Sam Phippen)be_true and be_false to be_truthy and be_falsey. (Sam Phippen)expect { }.to_not raise_error(SomeSpecificClass, message),
expect { }.to_not raise_error(SomeSpecificClass) and
expect { }.to_not raise_error(message) invalid, since they are prone
to hiding failures. Instead, use expect { }.to_not raise_error (with no
args). (Sam Phippen)RSpec::Matchers.define blocks, helper methods made available
either via def self.helper or extend HelperModule are no longer
available to the match block (or any of the others). Instead
include your helper module and define the helper method as an
instance method. (Myron Marston)Enhancements:
do..end style block with raise_error matcher. (Yuji Nakayama)return from within custom matcher DSL blocks. (Myron
Marston)chain can now accept a block. (Myron
Marston)raise_error matcher via a chained
with_message method call. (Sam Phippen)Bug Fixes:
include and match matchers to be used from within a
DSL-defined custom matcher's match block. (Myron Marston)Deprecations:
:should syntax without explicitly configuring it is deprecated.
It will continue to work but will emit a deprecation warning in RSpec 3 if
you do not explicitly enable it. (Sam Phippen)Bug fixes
be_<predicate> matcher to not support operator chaining like the
be matcher does (e.g. be == 5). This led to some odd behaviors
since be_<predicate> == anything returned a BeComparedTo matcher
and was thus always truthy. This was a consequence of the implementation
(e.g. subclassing the basic Be matcher) and was not intended behavior.
(Myron Marston).change matcher to compare using == in addition to ===. This
is important for an expression like:
expect {}.to change { a.class }.from(ClassA).to(ClassB) because
SomeClass === SomeClass returns false. (Myron Marston)Bug fixes
#inspect, rather than #description for
documentation output (Andy Lindeman, Sam Phippen).expect(a).to be_within(x).percent_of(y) work with negative y
(Katsuhiko Nishimra).be_predicate matcher work as expected used with expect{...}.to change... (Sam Phippen).Enhancements
yield_control so that you can specify an exact or relative
number of times: expect { }.to yield_control.exactly(3).times,
expect { }.to yield_control.at_least(2).times, etc (Bartek
Borkowski).:to_str as expectation messages.
(Toby Ovod-Everett)Bug fixes
expect(something).to be_within(x).percent_of(y) where x and y are both
integers (Sam Phippen).have matcher to handle the fact that on ruby 2.0,
Enumerator#size may return nil (Kenta Murata).expect { raise s }.to raise_error(s) where s is an error instance
on ruby 2.0 (Sam Phippen).expect(object).to raise_error passing. This now warns the user and
fails the spec (tomykaira).Deprecations
expect { }.not_to raise_error(SpecificErrorClass) or
expect { }.not_to raise_error("some specific message"). Using
these was prone to hiding failures as they would allow any other
error to pass. (Sam Phippen and David Chelimsky)