vendor/gems/rspec-1.1.2/lib/spec/expectations.rb

   1 require 'spec/matchers'
   2 require 'spec/expectations/errors'
   3 require 'spec/expectations/extensions'
   4 require 'spec/expectations/handler'
   5
   6 module Spec
   7
   8   # Spec::Expectations lets you set expectations on your objects.
   9   #
  10   #   result.should == 37
  11   #   team.should have(11).players_on_the_field
  12   #
  13   # == How Expectations work.
  14   #
  15   # Spec::Expectations adds two methods to Object:
  16   #
  17   #   should(matcher=nil)
  18   #   should_not(matcher=nil)
  19   #
  20   # Both methods take an optional Expression Matcher (See Spec::Matchers).
  21   #
  22   # When +should+ receives an Expression Matcher, it calls <tt>matches?(self)</tt>. If
  23   # it returns +true+, the spec passes and execution continues. If it returns
  24   # +false+, then the spec fails with the message returned by <tt>matcher.failure_message</tt>.
  25   #
  26   # Similarly, when +should_not+ receives a matcher, it calls <tt>matches?(self)</tt>. If
  27   # it returns +false+, the spec passes and execution continues. If it returns
  28   # +true+, then the spec fails with the message returned by <tt>matcher.negative_failure_message</tt>.
  29   #
  30   # RSpec ships with a standard set of useful matchers, and writing your own
  31   # matchers is quite simple. See Spec::Matchers for details.
  32   module Expectations
  33     class << self
  34       attr_accessor :differ
  35
  36       # raises a Spec::Expectations::ExpectationNotMetError with message
  37       #
  38       # When a differ has been assigned and fail_with is passed
  39       # <code>expected</code> and <code>target</code>, passes them
  40       # to the differ to append a diff message to the failure message.
  41       def fail_with(message, expected=nil, target=nil) # :nodoc:
  42         if Array === message && message.length == 3
  43           message, expected, target = message[0], message[1], message[2]
  44         end
  45         unless (differ.nil? || expected.nil? || target.nil?)
  46           if expected.is_a?(String)
  47             message << "\nDiff:" << self.differ.diff_as_string(target.to_s, expected)
  48           elsif !target.is_a?(Proc)
  49             message << "\nDiff:" << self.differ.diff_as_object(target, expected)
  50           end
  51         end
  52         Kernel::raise(Spec::Expectations::ExpectationNotMetError.new(message))
  53       end
  54     end
  55   end
  56 end