Module: RSpec::Expectations
- Defined in:
- lib/rspec/expectations.rb,
lib/rspec/expectations/syntax.rb,
lib/rspec/expectations/handler.rb,
lib/rspec/expectations/version.rb,
lib/rspec/expectations/fail_with.rb,
lib/rspec/expectations/configuration.rb,
lib/rspec/expectations/expectation_target.rb,
lib/rspec/expectations/failure_aggregator.rb,
lib/rspec/expectations/minitest_integration.rb,
lib/rspec/expectations/block_snippet_extractor.rb
Overview
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().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.
Defined Under Namespace
Modules: Syntax Classes: Configuration, ExpectationNotMetError, ExpectationTarget, MultipleExpectationsNotMetError
Class Method Summary collapse
-
.configuration ⇒ RSpec::Expectations::Configuration
The configuration object.
-
.fail_with(message, expected = nil, actual = nil) ⇒ Object
Raises an RSpec::Expectations::ExpectationNotMetError with message.
Class Method Details
.configuration ⇒ RSpec::Expectations::Configuration
The configuration object.
228 229 230 |
# File 'lib/rspec/expectations/configuration.rb', line 228 def self.configuration @configuration ||= Configuration.new end |
.fail_with(message, expected = nil, actual = nil) ⇒ Object
Raises an RSpec::Expectations::ExpectationNotMetError with message.
Adds a diff to the failure message when expected
and actual
are
both present.
27 28 29 30 31 32 33 34 35 36 |
# File 'lib/rspec/expectations/fail_with.rb', line 27 def fail_with(, expected=nil, actual=nil) unless raise ArgumentError, "Failure message is nil. Does your matcher define the " \ "appropriate failure_message[_when_negated] method to return a string?" end = ::RSpec::Matchers::MultiMatcherDiff.from(expected, actual).(, differ) RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new ) end |