rspec-expectations 2.6.0 → 2.7.0.rc1

data/lib/rspec/expectations/version.rb

@@ -1,7 +1,8 @@
-module RSpec # :nodoc:
-  module Expectations # :nodoc:
-    module Version # :nodoc:
-      STRING = '2.6.0'
+module RSpec
+  module Expectations
+    # @private
+    module Version
+      STRING = '2.7.0.rc1'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -1,16 +1,15 @@
 module RSpec
   # rspec-expecations provides a number of useful Matchers we use to compose
-  # expectations. A Matcher is any object that responds to the following
-  # methods:
+  # expectations. A Matcher is any object that responds to the following:
   #
-  #   matches?(actual)
-  #   failure_message_for_should
+  #  matches?(actual)
+  #  failure_message_for_should
   #
   # These methods are also part of the matcher protocol, but are optional:
   #
-  #   does_not_match?(actual)
-  #   failure_message_for_should_not
-  #   description #optional
+  #  does_not_match?(actual)
+  #  failure_message_for_should_not
+  #  description #optional
   #
   # == Predicates
   #
@@ -24,25 +23,25 @@ module RSpec
   # All you need to do is write +should be_+ followed by the predicate without
   # the question mark, and RSpec will figure it out from there. For example:
   #
-  #   [].should be_empty => [].empty? #passes
-  #   [].should_not be_empty => [].empty? #fails
+  #  [].should be_empty     # => [].empty?() | passes
+  #  [].should_not be_empty # => [].empty?() | fails
   #
   # In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
   # and "be_an_", making your specs read much more naturally:
   #
-  #   "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+  #  "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
   #
-  #   3.should be_a_kind_of(Fixnum) => 3.kind_of?(Numeric) #passes
-  #   3.should be_a_kind_of(Numeric) => 3.kind_of?(Numeric) #passes
-  #   3.should be_an_instance_of(Fixnum) => 3.instance_of?(Fixnum) #passes
-  #   3.should_not be_instance_of(Numeric) => 3.instance_of?(Numeric) #fails
+  #  3.should be_a_kind_of(Fixnum)        # => 3.kind_of?(Numeric)     | passes
+  #  3.should be_a_kind_of(Numeric)       # => 3.kind_of?(Numeric)     | passes
+  #  3.should be_an_instance_of(Fixnum)   # => 3.instance_of?(Fixnum)  | passes
+  #  3.should_not be_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
   #
   # RSpec will also create custom matchers for predicates like +has_key?+. To
   # use this feature, just state that the object should have_key(:key) and RSpec will
   # call has_key?(:key) on the target. For example:
   #
-  #   {:a => "A"}.should have_key(:a) => {:a => "A"}.has_key?(:a) #passes
-  #   {:a => "A"}.should have_key(:b) => {:a => "A"}.has_key?(:b) #fails
+  #  {:a => "A"}.should have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
+  #  {:a => "A"}.should have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
   #
   # You can use this feature to invoke any predicate that begins with "has_", whether it is
   # part of the Ruby libraries (like +Hash#has_key?+) or a method you wrote on your own class.
@@ -59,42 +58,45 @@ module RSpec
   # zones on a virtual board. To specify that bob should be in zone 4, you
   # could say:
   #
-  #   bob.current_zone.should eql(Zone.new("4"))
+  #  bob.current_zone.should eql(Zone.new("4"))
   #
   # But you might find it more expressive to say:
   #
-  #   bob.should be_in_zone("4")
+  #  bob.should be_in_zone("4")
   #
   # and/or
   #
-  #   bob.should_not be_in_zone("3")
+  #  bob.should_not be_in_zone("3")
   #
   # You can create such a matcher like so:
   #
-  #   RSpec::Matchers.define :be_in_zone do |zone|
-  #     match do |player|
-  #       player.in_zone?(zone)
-  #     end
-  #   end
+  #  RSpec::Matchers.define :be_in_zone do |zone|
+  #    match do |player|
+  #      player.in_zone?(zone)
+  #    end
+  #  end
   #
   # This will generate a <tt>be_in_zone</tt> method that returns a matcher
   # with logical default messages for failures. You can override the failure
   # messages and the generated description as follows:
   #
-  #   RSpec::Matchers.define :be_in_zone do |zone|
-  #     match do |player|
-  #       player.in_zone?(zone)
-  #     end
-  #     failure_message_for_should do |player|
-  #       # generate and return the appropriate string.
-  #     end
-  #     failure_message_for_should_not do |player|
-  #       # generate and return the appropriate string.
-  #     end
-  #     description do
-  #       # generate and return the appropriate string.
-  #     end
-  #   end
+  #  RSpec::Matchers.define :be_in_zone do |zone|
+  #    match do |player|
+  #      player.in_zone?(zone)
+  #    end
+  #
+  #    failure_message_for_should do |player|
+  #      # generate and return the appropriate string.
+  #    end
+  #
+  #    failure_message_for_should_not do |player|
+  #      # generate and return the appropriate string.
+  #    end
+  #
+  #    description do
+  #      # generate and return the appropriate string.
+  #    end
+  #  end
   #
   # Each of the message-generation methods has access to the block arguments
   # passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
@@ -106,54 +108,56 @@ module RSpec
   #
   # You could also write a custom matcher from scratch, as follows:
   #
-  #   class BeInZone
-  #     def initialize(expected)
-  #       @expected = expected
-  #     end
-  #     def matches?(target)
-  #       @target = target
-  #       @target.current_zone.eql?(Zone.new(@expected))
-  #     end
-  #     def failure_message_for_should
-  #       "expected #{@target.inspect} to be in Zone #{@expected}"
-  #     end
-  #     def failure_message_for_should_not
-  #       "expected #{@target.inspect} not to be in Zone #{@expected}"
-  #     end
-  #   end
+  #  class BeInZone
+  #    def initialize(expected)
+  #      @expected = expected
+  #    end
+  #
+  #    def matches?(target)
+  #      @target = target
+  #      @target.current_zone.eql?(Zone.new(@expected))
+  #    end
+  #
+  #    def failure_message_for_should
+  #      "expected #{@target.inspect} to be in Zone #{@expected}"
+  #    end
+  #
+  #    def failure_message_for_should_not
+  #      "expected #{@target.inspect} not to be in Zone #{@expected}"
+  #    end
+  #  end
   #
   # ... and a method like this:
   #
-  #   def be_in_zone(expected)
-  #     BeInZone.new(expected)
-  #   end
+  #  def be_in_zone(expected)
+  #    BeInZone.new(expected)
+  #  end
   #
   # And then expose the method to your specs. This is normally done
   # by including the method and the class in a module, which is then
   # included in your spec:
   #
-  #   module CustomGameMatchers
-  #     class BeInZone
-  #       ...
-  #     end
+  #  module CustomGameMatchers
+  #    class BeInZone
+  #      # ...
+  #    end
   #
-  #     def be_in_zone(expected)
-  #       ...
-  #     end
-  #   end
+  #    def be_in_zone(expected)
+  #      # ...
+  #    end
+  #  end
   #
-  #   describe "Player behaviour" do
-  #     include CustomGameMatchers
-  #     ...
-  #   end
+  #  describe "Player behaviour" do
+  #    include CustomGameMatchers
+  #    # ...
+  #  end
   #
   # or you can include in globally in a spec_helper.rb file <tt>require</tt>d
   # from your spec file(s):
   #
-  #   RSpec::Runner.configure do |config|
-  #     config.include(CustomGameMatchers)
-  #   end
-  #
+  #  RSpec::configure do |config|
+  #    config.include(CustomGameMatchers)
+  #  end
   module Matchers
     # Include Matchers for other test frameworks.
     # Note that MiniTest _must_ come before TU because on ruby 1.9,
@@ -170,7 +174,7 @@ module RSpec
   end
 end
 
-require 'rspec/matchers/extensions/instance_exec'
+require 'rspec/matchers/extensions/instance_eval_with_args'
 require 'rspec/matchers/pretty'
 require 'rspec/matchers/matcher'
 require 'rspec/matchers/operator_matcher'

data/lib/rspec/matchers/be.rb

@@ -1,35 +1,36 @@
 require 'rspec/matchers/dsl'
 
-RSpec::Matchers.define :be_true do
-  match do |actual|
-    actual
-  end
-end
+module RSpec
+  module Matchers
 
-RSpec::Matchers.define :be_false do
-  match do |actual|
-    !actual
-  end
-end
+    # @method be_true
+    RSpec::Matchers.define :be_true do
+      match do |actual|
+        actual
+      end
+    end
 
-RSpec::Matchers.define :be_nil do
-  match do |actual|
-    actual.nil?
-  end
+    RSpec::Matchers.define :be_false do
+      match do |actual|
+        !actual
+      end
+    end
 
-  failure_message_for_should do |actual|
-    "expected: nil\n     got: #{actual.inspect}"
-  end
+    RSpec::Matchers.define :be_nil do
+      match do |actual|
+        actual.nil?
+      end
 
-  failure_message_for_should_not do
-    "expected: not nil\n     got: nil"
-  end
-end
+      failure_message_for_should do |actual|
+        "expected: nil\n     got: #{actual.inspect}"
+      end
 
-module RSpec
-  module Matchers
+      failure_message_for_should_not do
+        "expected: not nil\n     got: nil"
+      end
+    end
 
-    class Be #:nodoc:
+    class Be
       include RSpec::Matchers::Pretty
       
       def initialize(*args, &block)
@@ -177,36 +178,26 @@ it is a bit confusing.
 
     end
 
-    # :call-seq:
-    #   should be_true
-    #   should be_false
-    #   should be_nil
-    #   should be_[arbitrary_predicate](*args)
-    #   should_not be_nil
-    #   should_not be_[arbitrary_predicate](*args)
-    #
-    # Given true, false, or nil, will pass if actual value is
-    # true, false or nil (respectively). Given no args means
-    # the caller should satisfy an if condition (to be or not to be). 
-    #
-    # Predicates are any Ruby method that ends in a "?" and returns true or false.
-    # Given be_ followed by arbitrary_predicate (without the "?"), RSpec will match
-    # convert that into a query against the target object.
-    #
-    # The arbitrary_predicate feature will handle any predicate
-    # prefixed with "be_an_" (e.g. be_an_instance_of), "be_a_" (e.g. be_a_kind_of)
-    # or "be_" (e.g. be_empty), letting you choose the prefix that best suits the predicate.
+    # @example
+    #   actual.should be_true
+    #   actual.should be_false
+    #   actual.should be_nil
+    #   actual.should be_[arbitrary_predicate](*args)
+    #   actual.should_not be_nil
+    #   actual.should_not be_[arbitrary_predicate](*args)
     #
-    # == Examples 
+    # Given true, false, or nil, will pass if actual value is true, false or
+    # nil (respectively). Given no args means the caller should satisfy an if
+    # condition (to be or not to be). 
     #
-    #   target.should be_true
-    #   target.should be_false
-    #   target.should be_nil
-    #   target.should_not be_nil
+    # Predicates are any Ruby method that ends in a "?" and returns true or
+    # false.  Given be_ followed by arbitrary_predicate (without the "?"),
+    # RSpec will match convert that into a query against the target object.
     #
-    #   collection.should be_empty #passes if target.empty?
-    #   target.should_not be_empty #passes unless target.empty?
-    #   target.should_not be_old_enough(16) #passes unless target.old_enough?(16)
+    # The arbitrary_predicate feature will handle any predicate prefixed with
+    # "be_an_" (e.g. be_an_instance_of), "be_a_" (e.g. be_a_kind_of) or "be_"
+    # (e.g. be_empty), letting you choose the prefix that best suits the
+    # predicate.
     def be(*args)
       args.empty? ?
         Matchers::Be.new : equal(*args)

data/lib/rspec/matchers/be_within.rb

@@ -16,7 +16,7 @@ module RSpec
         end
 
         match do |actual|
-          unless @_expected
+          unless defined?(@_expected)
             raise ArgumentError.new("You must set an expected value using #of: be_within(#{_delta_}).of(expected_value)")
           end
           (actual - @_expected).abs < _delta_

data/lib/rspec/matchers/change.rb

@@ -1,6 +1,6 @@
 module RSpec
   module Matchers
-    class Change #:nodoc:
+    class Change
       def initialize(receiver=nil, message=nil, &block)
         @message = message
         @value_proc = block || lambda {receiver.__send__(message)}
@@ -27,7 +27,7 @@ MESSAGE
       
       def evaluate_value_proc
         case val = @value_proc.call
-        when Array, Hash
+        when Enumerable
           val.dup
         else
           val
@@ -128,20 +128,12 @@ MESSAGE
       end
     end
     
-    # :call-seq:
-    #   should change(receiver, message)
-    #   should change(receiver, message).by(value)
-    #   should change(receiver, message).from(old).to(new)
-    #   should_not change(receiver, message)
-    #
-    #   should change {...}
-    #   should change {...}.by(value)
-    #   should change {...}.from(old).to(new)
-    #   should_not change {...}
-    #
     # Applied to a proc, specifies that its execution will cause some value to
     # change.
     #
+    # @param [Object] receiver
+    # @param [Symbol] message the message to send the receiver
+    #
     # You can either pass <tt>receiver</tt> and <tt>message</tt>, or a block,
     # but not both.
     #

data/lib/rspec/matchers/dsl.rb

@@ -1,7 +1,8 @@
 module RSpec
   module Matchers
     module DSL
-      # See RSpec::Matchers
+      # Defines a custom matcher.
+      # @see RSpec::Matchers
       def define(name, &declarations)
         define_method name do |*expected|
           $matcher_execution_context = self

data/lib/rspec/matchers/eq.rb

@@ -24,8 +24,8 @@ module RSpec
         failure_message_for_should do |actual|
           <<-MESSAGE
 
-expected #{_expected_.inspect}
-     got #{actual.inspect}
+expected: #{_expected_.inspect}
+     got: #{actual.inspect}
 
 (compared using ==)
 MESSAGE
@@ -41,7 +41,7 @@ MESSAGE
         end
 
         description do
-          "== #{_expected_}"
+          "eq #{_expected_}"
         end
       end
     end

data/lib/rspec/matchers/extensions/{instance_exec.rb → instance_eval_with_args.rb}

@@ -1,15 +1,23 @@
 module RSpec
   module Matchers
-    module InstanceExec
-      unless respond_to?(:instance_exec)
+    module Extensions
+      module InstanceEvalWithArgs
         # based on Bounded Spec InstanceExec (Mauricio Fernandez)
         # http://eigenclass.org/hiki/bounded+space+instance_exec
-        # - uses singleton_class of matcher instead of global
-        #   InstanceExecHelper module
-        # - this keeps it scoped to this class only, which is the
-        #   only place we need it
+        # - uses singleton_class instead of global InstanceExecHelper module
+        # - this keeps it scoped to classes/modules that include this module
         # - only necessary for ruby 1.8.6
-        def instance_exec(*args, &block)
+        def instance_eval_with_args(*args, &block)
+          return instance_exec(*args, &block) if respond_to?(:instance_exec)
+
+          # If there are no args and the block doesn't expect any, there's no
+          # need to fake instance_exec with our hack below.
+          # Notes:
+          #   * lambda { }.arity # => -1
+          #   * lambda { || }.arity # => 0
+          #   * lambda { |*a| }.arity # -1
+          return instance_eval(&block) if block.arity < 1 && args.empty?
+
           singleton_class = (class << self; self; end)
           begin
             orig_critical, Thread.critical = Thread.critical, true