Bug Fixes:
- Rename private
LegacyMacherAdapter
constant toLegacyMatcherAdapter
to fix typo. (Abdelkader Boudih, #563)
Bug Fixes:
- Fix regression in
contain_exactly
(AKAmatch_array
) that caused it to wrongly pass when the expected array was empty. (Myron Marston, #581) - Provide a better error message when you use the
change(obj, :msg)
form of the change matcher but forget the message argument. (Alex Sunderland, #585)
Bug Fixes:
- Add a missing
require
that would cause therespond_to
matcher to fail when used in a project where the rest of RSpec (e.g. core and expecatations) weren't being used. (Myron Marston, #566) - Structs are no longer treated as arrays when diffed. (Jon Rowe, #576)
No code changes. Just taking it out of pre-release.
Breaking Changes for 3.0.0:
- Remove
matcher_execution_context
attribute from DSL-defined custom matchers. (Myron Marston) - Remove
RSpec::Matchers::Pretty#_pretty_print
. (Myron Marston) - Remove
RSpec::Matchers::Pretty#expected_to_sentence
. (Myron Marston) - Rename
RSpec::Matchers::Configuration
constant toRSpec::Expectations::Configuration
. (Myron Marston) - Prevent
have_xyz
predicate matchers using private methods. (Adrian Gonzalez) - Block matchers must now implement
supports_block_expectations?
. (Myron Marston) - Stop supporting
require 'rspec-expectations'
. Userequire 'rspec/expectations'
instead. (Myron Marston)
Bug Fixes:
- Fix
NoMethodError
triggered by beta2 whenYARD
was loaded in the test environment. (Myron Marston) - Fix
be_xyz
matcher to accept ado...end
block. (Myron Marston) - Fix composable matcher failure message generation logic
so that it does not blow up when given
$stdout
or$stderr
. (Myron Marston) - Fix
change
matcher to work properly withIO
objects. (Myron Marston) - Fix
exist
matcher so that it can be used in composed matcher expressions involving objects that do not implementexist?
orexists?
. (Daniel Fone) - Fix composable matcher match logic so that it clones matchers
before using them in order to work properly with matchers
that use internal memoization based on a given
actual
value. (Myron Marston) - Fix
be_xyz
andhas_xyz
predicate matchers so that they can be used in composed matcher expressions involving objects that do not implement the predicate method. (Daniel Fone)
Enhancements:
- Document the remaining public APIs. rspec-expectations now has 100% of the public API documented and will remain that way (as new undocumented methods will fail the build). (Myron Marston)
- Improve the formatting of BigDecimal objects in
eq
matcher failure messages. (Daniel Fone) - Improve the failure message for
be_xyz
predicate matchers so that it includes theinspect
output of the receiver. (Erik Michaels-Ober, Sam Phippen) - Add
all
matcher, to allow you to specify that a given matcher matches all elements in a collection:expect([1, 3, 5]).to all( be_odd )
. (Adam Farhi) - Add boolean aliases (
&
/|
) for compound operators (and
/or
). (Adam Farhi) - Give users a clear error when they wrongly use a value matcher
in a block expectation expression (e.g.
expect { 3 }.to eq(3)
) or vice versa. (Myron Marston)
Breaking Changes for 3.0.0:
- Remove deprecated support for accessing the
RSpec
constant usingRspec
orSpec
. (Myron Marston) - Remove deprecated
RSpec::Expectations.differ=
. (Myron Marston) - Remove support for deprecated
expect(...).should
. (Myron Marston) - Explicitly disallow
expect { }.not_to change { }
withby
,by_at_least
,by_at_most
orto
. These have never been supported but did not raise explicit errors. (Myron Marston) - Provide
===
rather than==
as an alias ofmatches?
for all matchers. The semantics of===
are closer to an RSpec matcher than==
. (Myron Marston) - Remove deprecated
RSpec::Matchers::OperatorMatcher
constant. (Myron Marston) - Make
RSpec::Expectations::ExpectationNotMetError
subclassException
rather thanStandardError
so they can bypass a barerescue
in end-user code (e.g. when an expectation is set from within a rspec-mocks stub implementation). (Myron Marston) - Remove Test::Unit and Minitest 4.x integration. (Myron Marston)
Enhancements:
- Simplify the failure message of the
be
matcher when matching against:true
,false
andnil
. (Sam Phippen) - Update matcher protocol and custom matcher DSL to better align
with the newer
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
- Improve generated descriptions from
change
matcher. (Myron Marston) - Add support for compound matcher expressions using
and
andor
. Simply chain them off of any existing matcher to create an expression likeexpect(alphabet).to start_with("a").and end_with("z")
. (Eloy Espinaco) - Add
contain_exactly
as a less ambiguous version ofmatch_array
. Note that it expects the expected array to be splatted as individual args:expect(array).to contain_exactly(1, 2)
is the same asexpect(array).to match_array([1, 2])
. (Myron Marston) - Update
contain_exactly
/match_array
so that it can match against other non-array collections (such as aSet
). (Myron Marston) - Update built-in matchers so that they can accept matchers as arguments to allow you to compose matchers in arbitrary ways. (Myron Marston)
- Add
RSpec::Matchers::Composable
mixin that can be used to make a custom matcher composable as well. Note that custom matchers defined viaRSpec::Matchers.define
already have this. (Myron Marston) - Define noun-phrase aliases for built-in matchers, which can be used when creating composed matcher expressions that read better and provide better failure messages. (Myron Marston)
- Add
RSpec::Matchers.alias_matcher
so users can define their own matcher aliases. Thedescription
of the matcher will reflect the alternate matcher name. (Myron Marston) - Add explicit
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) - Enhance the
be_between
matcher to allow forinclusive
orexclusive
comparison (e.g. inclusive of min/max or exclusive of min/max). (Pedro Gimenez) - Make failure message for
not_to be #{operator}
less confusing by only saying it's confusing when comparison operators are used. (Prathamesh Sonpatki) - Improve failure message of
eq
matcher whenTime
orDateTime
objects are used so that the full sub-second precision is included. (Thomas Holmes, Jeff Wallace) - Add
output
matcher for expecting that a block outputsto_stdout
orto_stderr
. (Luca Pette, Matthias Günther) - Forward a provided block on to the
has_xyz?
method call when thehave_xyz
matcher is used. (Damian Galarza) - Provide integration with Minitest 5.x. Require
rspec/expectations/minitest_integration
after loading minitest to use rspec-expectations with minitest. (Myron Marston)
Bug Fixes:
- Fix wrong matcher descriptions with falsey expected value (yujinakayama)
- Fix
expect { }.not_to change { }.from(x)
so that the matcher only passes if the starting value isx
. (Tyler Rick, Myron Marston) - Fix hash diffing, so that it colorizes properly and doesn't consider trailing commas when performing the diff. (Jared Norman)
- Fix built-in matchers to fail normally rather than raising
ArgumentError
when given an object of the wrong type to match against, so that they work well in composite matcher expressions likeexpect([1.51, "foo"]).to include(a_string_matching(/foo/), a_value_within(0.1).of(1.5))
. (Myron Marston)
Deprecations:
- Retain support for RSpec 2 matcher protocol (e.g. for matchers
in 3rd party extension gems like
shoulda
), but it will print a deprecation warning. (Myron Marston)
Breaking Changes for 3.0.0:
- Remove explicit support for 1.8.6. (Jon Rowe)
- Remove the deprecated
be_close
matcher, preferringbe_within
instead. (Sam Phippen) - Remove the deprecated
have
,have_at_least
andhave_at_most
matchers. You can continue using those matchers through https://github.com/rspec/rspec-collection_matchers, or you can rewrite your expectations with something likeexpect(your_object.size).to eq(num)
. (Hugo Baraúna) - Rename
be_true
andbe_false
tobe_truthy
andbe_falsey
. (Sam Phippen) - Make
expect { }.to_not raise_error(SomeSpecificClass, message)
,expect { }.to_not raise_error(SomeSpecificClass)
andexpect { }.to_not raise_error(message)
invalid, since they are prone to hiding failures. Instead, useexpect { }.to_not raise_error
(with no args). (Sam Phippen) - Within
RSpec::Matchers.define
blocks, helper methods made available either viadef self.helper
orextend HelperModule
are no longer available to thematch
block (or any of the others). Insteadinclude
your helper module and define the helper method as an instance method. (Myron Marston) - Force upgrading Diff::LCS for encoding compatability with diffs. (Jon Rowe)
Enhancements:
- Support
do..end
style block withraise_error
matcher. (Yuji Nakayama) - Rewrote custom matcher DSL to simplify its implementation and solve a few issues. (Myron Marston)
- Allow early
return
from within custom matcher DSL blocks. (Myron Marston) - The custom matcher DSL's
chain
can now accept a block. (Myron Marston) - Support setting an expectation on a
raise_error
matcher via a chainedwith_message
method call. (Sam Phippen)
Bug Fixes:
- Allow
include
andmatch
matchers to be used from within a DSL-defined custom matcher'smatch
block. (Myron Marston) - Correct encoding error message on diff failure (Jon Rowe)
Deprecations:
- Using the old
: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)
Enhancements:
- Special case deprecation message for
errors_on
withrspec-rails
to be more useful. (Aaron Kromer)
Deprecations:
- Deprecate
matcher_execution_context
attribute on DSL-defined custom matchers. (Myron Marston) - Deprecate
RSpec::Matchers::Pretty#_pretty_print
. (Myron Marston) - Deprecate
RSpec::Matchers::Pretty#expected_to_sentence
. (Myron Marston) - Deprecate
RSpec::Matchers::Configuration
in favor ofRSpec::Expectations::Configuration
. (Myron Marston) - Deprecate
be_xyz
predicate matcher on an object that doesn't respond toxyz?
orxyzs?
. (Daniel Fone) - Deprecate
have_xyz
matcher on an object that doesn't respond tohas_xyz?
. (Daniel Fone) - Deprecate
have_xyz
matcher on an object that has a private methodhas_xyz?
. (Jon Rowe) - Issue a deprecation warning when a block expectation expression is
used with a matcher that doesn't explicitly support block expectations
via
supports_block_expectations?
. (Myron Marston) - Deprecate
require 'rspec-expectations'
. Userequire 'rspec/expectations'
instead. (Myron Marston)
Deprecations:
- Deprecate chaining
by
,by_at_least
,by_at_most
orto
off ofexpect { }.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) - Change the semantics of
expect { }.not_to change { x }.from(y)
. In RSpec 2.x, this expectation would only fail ifx
started with the value ofy
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 aty
and it does not change. (Myron Marston) - Deprecate
matcher == value
as an alias formatcher.matches?(value)
, in favor ofmatcher === value
. (Myron Marston) - Deprecate
RSpec::Matchers::OperatorMatcher
in favor ofRSpec::Matchers::BuiltIn::OperatorMatcher
. (Myron Marston) - Deprecate auto-integration with Test::Unit and minitest.
Instead, include
RSpec::Matchers
in the appropriate test case base class yourself. (Myron Marston) - Deprecate treating
#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
- Deprecate
have
,have_at_least
andhave_at_most
. You can continue using those matchers through https://github.com/rspec/rspec-collection_matchers, or you can rewrite your expectations with something likeexpect(your_object.size).to eq(num)
. (Hugo Baraúna) - Deprecate
be_xyz
predicate matcher whenxyz?
is a private method. (Jon Rowe) - Deprecate
be_true
/be_false
in favour ofbe_truthy
/be_falsey
(for Ruby's conditional semantics) orbe true
/be false
(for exact equality). (Sam Phippen) - Deprecate calling helper methods from a custom matcher with the wrong
scope. (Myron Marston)
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.- RSpec 2.x allowed helper methods defined either way to be used for either purpose, but RSpec 3.0 will not.
Bug fixes
- Fix wrong matcher descriptions with falsey expected value (yujinakayama)
Bug fixes
- Make the
match
matcher produce a diff output. (Jon Rowe, Ben Moss) - Choose encoding for diff's more intelligently, and when all else fails fall back to default internal encoding with replacing characters. (Jon Rowe)
Bug fixes
- Fix operator matchers (
should
syntax) whenmethod
is redefined on target. (Brandon Turner) - Fix diffing of hashes with object based keys. (Jon Rowe)
- Fix operator matchers (
should
syntax) when operator is defined viamethod_missing
(Jon Rowe)
Bug fixes
- Fix
be_<predicate>
matcher to not support operator chaining like thebe
matcher does (e.g.be == 5
). This led to some odd behaviors sincebe_<predicate> == anything
returned aBeComparedTo
matcher and was thus always truthy. This was a consequence of the implementation (e.g. subclassing the basicBe
matcher) and was not intended behavior. (Myron Marston). - Fix
change
matcher to compare using==
in addition to===
. This is important for an expression like:expect {}.to change { a.class }.from(ClassA).to(ClassB)
becauseSomeClass === SomeClass
returns false. (Myron Marston)
Bug fixes
- Ensure diff output uses the same encoding as the encoding of
the string being diff'd to prevent
Encoding::UndefinedConversionError
errors (Jon Rowe).
Bug fixes
- Values that are not matchers use
#inspect
, rather than#description
for documentation output (Andy Lindeman, Sam Phippen). - Make
expect(a).to be_within(x).percent_of(y)
work with negative y (Katsuhiko Nishimra). - Make the
be_predicate
matcher work as expected used withexpect{...}.to change...
(Sam Phippen).
Enhancements
- Enhance
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). - Make the differ that is used when an expectation fails better handle arrays by splitting each element of the array onto its own line. (Sam Phippen)
- Accept duck-typed strings that respond to
:to_str
as expectation messages. (Toby Ovod-Everett)
Bug fixes
- Fix differ to not raise errors when dealing with differently-encoded strings (Jon Rowe).
- Fix
expect(something).to be_within(x).percent_of(y)
where x and y are both integers (Sam Phippen). - Fix
have
matcher to handle the fact that on ruby 2.0,Enumerator#size
may return nil (Kenta Murata). - Fix
expect { raise s }.to raise_error(s)
where s is an error instance on ruby 2.0 (Sam Phippen). - Fix
expect(object).to raise_error
passing. This now warns the user and fails the spec (tomykaira).
Deprecations
- Deprecate
expect { }.not_to raise_error(SpecificErrorClass)
orexpect { }.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)
Enhancements
- Add support for percent deltas to
be_within
matcher:expect(value).to be_within(10).percent_of(expected)
(Myron Marston). - Add support to
include
matcher to allow it to be given a list of matchers as the expecteds to match against (Luke Redpath).
Bug fixes
- Fix
change
matcher so that it dups strings in order to handle mutated strings (Myron Marston). - Fix
should be =~ /some regex/
/expect(...).to be =~ /some regex/
. Previously, these either failed with a confusingundefined method matches?' for false:FalseClass
error or were no-ops that didn't actually verify anything (Myron Marston). - Add compatibility for diff-lcs 1.2 and relax the version constraint (Peter Goldstein).
- Fix DSL-generated matchers to allow multiple instances of the same matcher in the same example to have different description and failure messages based on the expected value (Myron Marston).
- Prevent
undefined method #split for Array
error when dumping the diff of an array of multiline strings (Myron Marston). - Don't blow up when comparing strings that are in an encoding that is not ASCII compatible (Myron Marston).
- Remove confusing "Check the implementation of #==" message printed for empty diffs (Myron Marston).
Bug fixes
- Improve the failure message for an expression like
{}.should =~ {}
. (Myron Marston and Andy Lindeman) - Provide a
match_regex
alias so that custom matchers built using the matcher DSL can use it (sincematch
is a different method in that context). (Steven Harman)
Enhancements
- Colorize diffs if the
--color
option is configured. (Alex Coplan) - Include backtraces in unexpected errors handled by
raise_error
matcher (Myron Marston) - Print a warning when users accidentally pass a non-string argument as an expectation message (Sam Phippen)
=~
andmatch_array
matchers output a more useful error message when the actual value is not an array (or an object that responds to#to_ary
) (Sam Phippen)
Bug fixes
- Fix
include
matcher so thatexpect({}).to include(:a => nil)
fails as it should (Sam Phippen). - Fix
be_an_instance_of
matcher so thatClass#to_s
is used in the description rather thanClass#inspect
, since some classes (likeActiveRecord::Base
) define a long, verbose#inspect
. (Tom Stuart)
Bug fixes
-
Fix (and deprecate)
expect { }.should
syntax so that it works even though it was never a documented or intended syntax. It worked as a consequence of the implementation ofexpect
in RSpec 2.10 and earlier. (Myron Marston) -
Ensure #== is defined on built in matchers so that they can be composed. For example:
expect { user.emailed! }.to change { user.last_emailed_at }.to be_within(1.second).of(Time.zone.now)
Bug fixes
- Define
should
andshould_not
onObject
rather thanBasicObject
on MacRuby. On MacRuby,BasicObject
is defined but is not the root of the object hierarchy. (Gabriel Gilder)
Bug fixes
- Constrain
actual
inbe_within
matcher to values that respond to-
instead of requiring a specific type.Time
, for example, is a legit alternative.
Enhancements
- Expand
expect
syntax so that it supports expections on bare values in addition to blocks (Myron Marston). - Add configuration options to control available expectation syntaxes
(Myron Marston):
RSpec.configuration.expect_with(:rspec) { |c| c.syntax = :expect }
RSpec.configuration.expect_with(:rspec) { |c| c.syntax = :should }
RSpec.configuration.expect_with(:rspec) { |c| c.syntax = [:should, :expect] }
RSpec.configuration.add_should_and_should_not_to Delegator
Bug fixes
- Allow only
Numeric
values to be the "actual" in thebe_within
matcher. This prevents confusing error messages. (Su Zhang @zhangsu) - Define
should
andshould_not
onBasicObject
rather thanKernel
on 1.9. This makesshould
andshould_not
work properly withBasicObject
-subclassed proxy objects likeDelegator
. (Myron Marston)
Enhancements
- Add new
start_with
andend_with
matchers (Jeremy Wadsack) - Add new matchers for specifying yields (Myron Marston):
expect {...}.to yield_control
expect {...}.to yield_with_args(1, 2, 3)
expect {...}.to yield_with_no_args
expect {...}.to yield_successive_args(1, 2, 3)
match_unless_raises
takes multiple exception args
Bug fixes
- Fix
be_within
matcher to be inclusive of delta. - Fix message-specific specs to pass on Rubinius (John Firebaugh)
Bug fixes
- Provide a helpful message if the diff between two objects is empty.
- Fix bug diffing single strings with multiline strings.
- Fix for error with using custom matchers inside other custom matchers (mirasrael)
- Fix using execution context methods in nested DSL matchers (mirasrael)
Enhancements
- Move built-in matcher classes to RSpec::Matchers::BuiltIn to reduce pollution of RSpec::Matchers (which is included in every example).
- Autoload files with matcher classes to improve load time.
Bug fixes
- Align
respond_to?
andmethod_missing
in DSL-defined matchers. - Clear out user-defined instance variables between invocations of DSL-defined matchers.
- Dup the instance of a DSL generated matcher so its state is not changed by subsequent invocations.
- Treat expected args consistently across positive and negative expectations (thanks to Ralf Kistner for the heads up)
Enhancements
- Better diff output for Hash (Philippe Creux)
- Eliminate Ruby warnings (Olek Janiszewski)
No changes for this release. Just releasing with the other rspec gems.
Enhancements
- Use classes for the built-in matchers (they're faster).
- Eliminate Ruby warnings (Matijs van Zuijlen)
Enhancements
HaveMatcher
converts argument usingto_i
(Alex Bepple & Pat Maddox)- Improved failure message for the
have_xxx
matcher (Myron Marston) HaveMatcher
supportscount
(Matthew Bellantoni)- Change matcher dups
Enumerable
before the action, supporting customEnumerable
types likeCollectionProxy
in Rails (David Chelimsky)
Bug fixes
- Fix typo in
have(n).xyz
documentation (Jean Boussier) - fix
safe_sort
for ruby 1.9.2 (Kernel
now defines<=>
for Object) (Peter van Hardenberg)
Enhancements
change
matcher accepts regexps (Robert Davis)- better descriptions for
have_xxx
matchers (Magnus Bergmark) range.should cover(*values)
(Anders Furseth)
Bug fixes
- Removed non-ascii characters that were choking rcov (Geoffrey Byers)
- change matcher dups arrays and hashes so their before/after states can be compared correctly.
- Fix the order of inclusion of RSpec::Matchers in Test::Unit::TestCase and MiniTest::Unit::TestCase to prevent a SystemStackError (Myron Marston)
Enhancements
should exist
works withexist?
orexists?
(Myron Marston)expect { ... }.not_to do_something
(in addition toto_not
)
Documentation
- improved docs for raise_error matcher (James Almond)
No functional changes in this release, which was made to align with the rspec-core-2.4.0 release.
Enhancements
- improved RDoc for change matcher (Jo Liss)
Enhancements
- diff strings when include matcher fails (Mike Sassak)
Enhancements
be_within(delta).of(expected)
matcher (Myron Marston)- Lots of new Cucumber features (Myron Marston)
- Raise error if you try
should != expected
on Ruby-1.9 (Myron Marston) - Improved failure messages from
throw_symbol
(Myron Marston)
Bug fixes
- Eliminate hard dependency on
RSpec::Core
(Myron Marston) have_matcher
- use pluralize only when ActiveSupport inflections are indeed defined (Josep M Bach)- throw_symbol matcher no longer swallows exceptions (Myron Marston)
- fix matcher chaining to avoid name collisions (Myron Marston)
Enhancements
- Add match_for_should_not method to matcher DSL (Myron Marston)
Bug fixes
respond_to
matcher works correctly withshould_not
with multiple methods (Myron Marston)include
matcher works correctly withshould_not
with multiple values (Myron Marston)
Enhancements
require 'rspec/expectations'
in a T::U or MiniUnit suite (Josep M. Bach)
Bug fixes
- change by 0 passes/fails correctly (Len Smith)
- Add description to satisfy matcher
Enhancements
- diffing improvements
- diff multiline strings
- don't diff single line strings
- don't diff numbers (silly)
- diff regexp + multiline string
Bug fixes
* should[_not]
change now handles boolean values correctly