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

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