Module: RSpec::Expectations

Defined in:
lib/rspec/expectations.rb,
lib/rspec/expectations/syntax.rb,
lib/rspec/expectations/version.rb,
lib/rspec/expectations/handler.rb,
lib/rspec/expectations/fail_with.rb,
lib/rspec/expectations/configuration.rb,
lib/rspec/expectations/expectation_target.rb,
lib/rspec/expectations/minitest_integration.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(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.

Defined Under Namespace

Modules: Syntax Classes: Configuration, ExpectationTarget

Constant Summary

ExpectationNotMetError =
Note:

We subclass Exception so that in a stub implementation if

Exception raised when an expectation fails.

the user sets an expectation, it can't be caught in their code by a bare rescue.

::Minitest::Assertion

Class Method Summary (collapse)

Class Method Details

+ (RSpec::Expectations::Configuration) configuration

The configuration object.

Returns:

128
129
130
 
# File 'lib/rspec/expectations/configuration.rb', line 128
def self.configuration
  @configuration ||= Configuration.new
end

+ (Object) fail_with(message, expected = nil, actual = nil)

Raises an RSpec::Expectations::ExpectationNotMetError with message. Adds a diff to the failure message when expected and actual are both present.

Parameters:

  • message (String)
  • expected (Object) (defaults to: nil)
  • actual (Object) (defaults to: nil)

Raises:

21
22
23
24
25
26
27
28
29
30
31
 
# File 'lib/rspec/expectations/fail_with.rb', line 21
def fail_with(message, expected=nil, actual=nil)
  unless message
    raise ArgumentError, "Failure message is nil. Does your matcher define the " \
                         "appropriate failure_message[_when_negated] method to return a string?"
  end
  diff = differ.diff(actual, expected)
  message = "#{message}\nDiff:#{diff}" unless diff.empty?
  raise RSpec::Expectations::ExpectationNotMetError, message
end