123456789_123456789_123456789_123456789_123456789_

Module: RSpec::Expectations

Overview

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](../RSpec/Matchers) for more information about the built-in matchers that ship with rspec-expectations, and how to write your own custom matchers.

Constant Summary

Class Method Summary

Class Method Details

.configuration ⇒ RSpec::Expectations::Configuration

The configuration object.

Returns:

[ GitHub ] 

  


# File 'rspec-expectations/lib/rspec/expectations/configuration.rb', line 223



def self.configuration
  @configuration ||= Configuration.new
end


  








  

    .differ  
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'rspec-expectations/lib/rspec/expectations/fail_with.rb', line 13



def differ
  RSpec::Support::Differ.new(
    :object_preparer => Differ::OBJECT_PREPARER,
    :color => RSpec::Matchers.configuration.color?
  )
end


  








  

    .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)
  
    • 





  [ GitHub ]


  

  


# File 'rspec-expectations/lib/rspec/expectations/fail_with.rb', line 27



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

  message = ::RSpec::Matchers::MultiMatcherDiff.from(expected, actual).message_with_diff(message, differ)

  RSpec::Support.notify_failure(RSpec::Expectations::ExpectationNotMetError.new message)
end