vendor/plugins/rspec/lib/spec/matchers.rb

   1 require 'spec/matchers/be'
   2 require 'spec/matchers/be_close'
   3 require 'spec/matchers/change'
   4 require 'spec/matchers/eql'
   5 require 'spec/matchers/equal'
   6 require 'spec/matchers/has'
   7 require 'spec/matchers/have'
   8 require 'spec/matchers/include'
   9 require 'spec/matchers/match'
  10 require 'spec/matchers/raise_error'
  11 require 'spec/matchers/respond_to'
  12 require 'spec/matchers/satisfy'
  13 require 'spec/matchers/throw_symbol'
  14 require 'spec/matchers/operator_matcher'
  15
  16 module Spec
  17
  18   # RSpec ships with a number of useful Expression Matchers. An Expression Matcher
  19   # is any object that responds to the following methods:
  20   #
  21   #   matches?(actual)
  22   #   failure_message
  23   #   negative_failure_message #optional
  24   #   description #optional
  25   #
  26   # See Spec::Expectations to learn how to use these as Expectation Matchers.
  27   # See Spec::Mocks to learn how to use them as Mock Argument Constraints.
  28   #
  29   # == Predicates
  30   #
  31   # In addition to those Expression Matchers that are defined explicitly, RSpec will
  32   # create custom Matchers on the fly for any arbitrary predicate, giving your specs
  33   # a much more natural language feel.
  34   #
  35   # A Ruby predicate is a method that ends with a "?" and returns true or false.
  36   # Common examples are +empty?+, +nil?+, and +instance_of?+.
  37   #
  38   # All you need to do is write +should be_+ followed by the predicate without
  39   # the question mark, and RSpec will figure it out from there. For example:
  40   #
  41   #   [].should be_empty => [].empty? #passes
  42   #   [].should_not be_empty => [].empty? #fails
  43   #
  44   # In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
  45   # and "be_an_", making your specs read much more naturally:
  46   #
  47   #   "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
  48   #
  49   #   3.should be_a_kind_of(Fixnum) => 3.kind_of?(Numeric) #passes
  50   #   3.should be_a_kind_of(Numeric) => 3.kind_of?(Numeric) #passes
  51   #   3.should be_an_instance_of(Fixnum) => 3.instance_of?(Fixnum) #passes
  52   #   3.should_not be_instance_of(Numeric) => 3.instance_of?(Numeric) #fails
  53   #
  54   # RSpec will also create custom matchers for predicates like +has_key?+. To
  55   # use this feature, just state that the object should have_key(:key) and RSpec will
  56   # call has_key?(:key) on the target. For example:
  57   #
  58   #   {:a => "A"}.should have_key(:a) => {:a => "A"}.has_key?(:a) #passes
  59   #   {:a => "A"}.should have_key(:b) => {:a => "A"}.has_key?(:b) #fails
  60   #
  61   # You can use this feature to invoke any predicate that begins with "has_", whether it is
  62   # part of the Ruby libraries (like +Hash#has_key?+) or a method you wrote on your own class.
  63   #
  64   # == Custom Expectation Matchers
  65   #
  66   # When you find that none of the stock Expectation Matchers provide a natural
  67   # feeling expectation, you can very easily write your own.
  68   #
  69   # For example, imagine that you are writing a game in which players can
  70   # be in various zones on a virtual board. To specify that bob should
  71   # be in zone 4, you could say:
  72   #
  73   #   bob.current_zone.should eql(Zone.new("4"))
  74   #
  75   # But you might find it more expressive to say:
  76   #
  77   #   bob.should be_in_zone("4")
  78   #
  79   # and/or
  80   #
  81   #   bob.should_not be_in_zone("3")
  82   #
  83   # To do this, you would need to write a class like this:
  84   #
  85   #   class BeInZone
  86   #     def initialize(expected)
  87   #       @expected = expected
  88   #     end
  89   #     def matches?(target)
  90   #       @target = target
  91   #       @target.current_zone.eql?(Zone.new(@expected))
  92   #     end
  93   #     def failure_message
  94   #       "expected #{@target.inspect} to be in Zone #{@expected}"
  95   #     end
  96   #     def negative_failure_message
  97   #       "expected #{@target.inspect} not to be in Zone #{@expected}"
  98   #     end
  99   #   end
 100   #
 101   # ... and a method like this:
 102   #
 103   #   def be_in_zone(expected)
 104   #     BeInZone.new(expected)
 105   #   end
 106   #
 107   # And then expose the method to your specs. This is normally done
 108   # by including the method and the class in a module, which is then
 109   # included in your spec:
 110   #
 111   #   module CustomGameMatchers
 112   #     class BeInZone
 113   #       ...
 114   #     end
 115   #
 116   #     def be_in_zone(expected)
 117   #       ...
 118   #     end
 119   #   end
 120   #
 121   #   describe "Player behaviour" do
 122   #     include CustomGameMatchers
 123   #     ...
 124   #   end
 125   #
 126   # or you can include in globally in a spec_helper.rb file <tt>require</tt>d
 127   # from your spec file(s):
 128   #
 129   #   Spec::Runner.configure do |config|
 130   #     config.include(CustomGameMatchers)
 131   #   end
 132   #
 133   module Matchers
 134     module ModuleMethods
 135       def description_generated(callback)
 136         description_generated_callbacks << callback
 137       end
 138
 139       def unregister_description_generated(callback)
 140         description_generated_callbacks.delete(callback)
 141       end
 142
 143       def generated_description=(name)
 144         description_generated_callbacks.each do |callback|
 145           callback.call(name)
 146         end
 147       end
 148
 149       private
 150       def description_generated_callbacks
 151         @description_generated_callbacks ||= []
 152       end
 153     end
 154     extend ModuleMethods
 155
 156     def method_missing(sym, *args, &block) # :nodoc:
 157       return Matchers::Be.new(sym, *args) if sym.starts_with?("be_")
 158       return Matchers::Has.new(sym, *args) if sym.starts_with?("have_")
 159       super
 160     end
 161
 162     class MatcherError < StandardError
 163     end
 164
 165   end
 166 end