module RSpec::Expectations
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](../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](../RSpec/Matchers) for more information about the built-in matchers that ship with rspec-expectations, and how to write your own custom matchers.
Constants
- KERNEL_METHOD_METHOD
@api private
Public Class Methods
@private
# File lib/rspec/expectations/fail_with.rb, line 5 def differ @differ ||= Differ.new end
Raises an RSpec::Expectations::ExpectationNotMetError with message. @param [String] message @param [Object] expected @param [Object] actual
Adds a diff to the failure message when `expected` and `actual` are both present.
# 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
# File lib/rspec/expectations.rb, line 60 def self.method_handle_for(object, method_name) KERNEL_METHOD_METHOD.bind(object).call(method_name) end
Private Class Methods
# File lib/rspec/expectations/fail_with.rb, line 41 def all_strings?(*args) args.flatten.all? {|a| String === a} end
# File lib/rspec/expectations/fail_with.rb, line 45 def any_multiline_strings?(*args) all_strings?(*args) && args.flatten.any? { |a| multiline?(a) } end
# File lib/rspec/expectations/fail_with.rb, line 53 def coerce_to_string(string_or_array) return string_or_array unless Array === string_or_array diffably_stringify(string_or_array).join("\n") end
# File lib/rspec/expectations/fail_with.rb, line 58 def diffably_stringify(array) array.map do |entry| if Array === entry entry.inspect else entry.to_s.gsub("\n", "\\n") end end end
# File lib/rspec/expectations/fail_with.rb, line 69 def multiline?(string) string.include?("\n".encode(string.encoding)) end
# File lib/rspec/expectations/fail_with.rb, line 49 def no_numbers?(*args) args.flatten.none? {|a| Numeric === a} end
# File lib/rspec/expectations/fail_with.rb, line 37 def no_procs?(*args) args.flatten.none? {|a| Proc === a} end
Public Instance Methods
@deprecated (no replacement)
# File lib/rspec/expectations/extensions/object.rb, line 23 def differ=(ignore) RSpec.deprecate("RSpec::Expectations.differ=(differ)") end