Module: RSpec::Expectations

Defined in:
lib/rspec/expectations.rb,
lib/rspec/expectations/errors.rb,
lib/rspec/expectations/syntax.rb,
lib/rspec/expectations/differ.rb,
lib/rspec/expectations/version.rb,
lib/rspec/expectations/handler.rb,
lib/rspec/expectations/fail_with.rb,
lib/rspec/expectations/deprecation.rb,
lib/rspec/expectations/extensions/object.rb,
lib/rspec/expectations/expectation_target.rb

Overview

RSpec::Expectations adds two instance methods to every object:

should(matcher=nil)
should_not(matcher=nil)

Both methods take an optional matcher object (See RSpec::Matchers). When should is invoked with a matcher, it turns around and calls matcher.matches?(self). For example, in the expression:

order.total.should eq(Money.new(5.55, :USD))

the should method invokes 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_for_should.

Given the expression:

order.entries.should_not include(entry)

the should_not method invokes the equivalent of include.matches?(order.entries), but it interprets false as success, and true as a failure, using the message generated by eq.failure_message_for_should_not.

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: DeprecatedConstants, Deprecation, Syntax Classes: Differ, ExpectationHandler, ExpectationNotMetError, ExpectationTarget, NegativeExpectationHandler, PositiveExpectationHandler

Constant Summary

KERNEL_METHOD_METHOD =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future. 

::Kernel.instance_method(:method)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Class Method Details

+ (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:

16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
 
# File 'lib/rspec/expectations/fail_with.rb', line 16
def fail_with(message, expected=nil, actual=nil)
  if !message
    raise ArgumentError, "Failure message is nil. Does your matcher define the " +
                         "appropriate failure_message_for_* method to return a string?"
  end
  if actual && expected
    if all_strings?(actual, expected)
      if any_multiline_strings?(actual, expected)
        message << "\nDiff:" << differ.diff_as_string(coerce_to_string(actual), coerce_to_string(expected))
      end
    elsif no_procs?(actual, expected) && no_numbers?(actual, expected)
      message << "\nDiff:" << differ.diff_as_object(actual, expected)
    end
  end
  raise(RSpec::Expectations::ExpectationNotMetError.new(message))
end

+ (Object) method_handle_for(object, method_name) 

60
61
62
 
# File 'lib/rspec/expectations.rb', line 60
def self.method_handle_for(object, method_name)
  KERNEL_METHOD_METHOD.bind(object).call(method_name)
end

Instance Method Details

- (Object) differ=(ignore)

Deprecated.

(no replacement)

23
24
25
 
# File 'lib/rspec/expectations/extensions/object.rb', line 23
def differ=(ignore)
  RSpec.deprecate("RSpec::Expectations.differ=(differ)")
end

- (Boolean) multiline?(string)

Returns:

  • (Boolean) 
69
70
71
 
# File 'lib/rspec/expectations/fail_with.rb', line 69
def multiline?(string)
  string.include?("\n".encode(string.encoding))
end