rspec-expectations 2.7.0 → 2.8.0.rc1

data/README.md

@@ -1,21 +1,129 @@
 # RSpec Expectations
 
-rspec-expectations adds `should` and `should_not` to every object and includes
-several standard matchers in RSpec::Matchers
+[RSpec::Expectations](../RSpec/Expectations) lets you express expected outcomes
+on an object in an example.
+
+    account.balance.should eq(Money.new(37.42, :USD))
 
 ## Install
 
-    gem install rspec               # for rspec-core, rspec-expectations, rspec-mocks
-    gem install rspec-expectations  # for rspec-expectations only
+If you want to use rspec-expectations with rspec, just install the rspec gem
+and RubyGems will also install rspec-expectations for you (along with
+rspec-core and rspec-mocks):
+
+    gem install rspec
+
+If you want to use rspec-expectations with another tool, like Test::Unit,
+Minitest, or Cucumber, you can install it directly:
+
+    gem install rspec-expectations
+
+## Basic usage
+
+Here's an example using rspec-core:
+
+    describe Order do
+      it "sums the prices of the items in its line items" do
+        order = Order.new
+        order.add_entry(LineItem.new(:item => Item.new(
+          :price => Money.new(1.11, :USD)
+        )
+        order.add_entry(LineItem.new(:item => Item.new(
+          :price => Money.new(2.22, :USD),
+          :quantity => 2
+        )
+        order.total.should eq(Money.new(5.55, :USD))
+      end
+    end
+
+The `describe` and `it` methods come from rspec-core.  The `Order`, `LineItem`,
+and `Item` classes would be from _your_ code. The last line of the example
+expresses an expected outcome. If `order.total == Money.new(5.55, :USD)`, then
+the example passes. If not, it fails with a message like:
+
+    expected: #<Money @value=5.55 @currency=:USD>
+         got: #<Money @value=1.11 @currency=:USD>
+
+## Built-in matchers
+
+### Equivalence
+
+    actual.should eq(expected)  # passes if actual == expected
+    actual.should == expected   # passes if actual == expected
+    actual.should eql(expected) # passes if actual.eql?(expected)
+
+### Identity
+
+    actual.should be(expected)    # passes if actual.equal?(expected)
+    actual.should equal(expected) # passes if actual.equal?(expected)
+    
+### Comparisons
+
+    actual.should be >  expected
+    actual.should be >= expected
+    actual.should be <= expected
+    actual.should be <  expected
+    actual.should be_within(delta).of(expected)
+
+### Regular expressions
+
+    actual.should =~ /expression/
+    actual.should match(/expression/)
+
+### Types/classes
+
+    actual.should be_an_instance_of(expected)
+    actual.should be_a_kind_of(expected)
+
+### Truthiness
+
+    actual.should be_true  # passes if actual is truthy (not nil or false)
+    actual.should be_false # passes if actual is falsy (nil or false)
+    actual.should be_nil   # passes if actual is nil
+
+### Expecting errors
+
+    expect { ... }.to raise_error
+    expect { ... }.to raise_error(ErrorClass)
+    expect { ... }.to raise_error("message")
+    expect { ... }.to raise_error(ErrorClass, "message")
+
+### Expecting throws
+
+    expect { ... }.to throw_symbol
+    expect { ... }.to throw_symbol(:symbol)
+    expect { ... }.to throw_symbol(:symbol, 'value')
+
+### Predicate matchers
+
+    actual.should be_xxx         # passes if actual.xxx?
+    actual.should have_xxx(:arg) # passes if actual.has_xxx?(:arg)
+
+See [RSpec::Matchers](../RSpec/Matchers) for more about predicate matchers.
+
+### Ranges (Ruby >= 1.9 only)
+
+    (1..10).should cover(3)
+
+### Collection membership
+
+    actual.should include(expected)
+
+#### Examples
 
-## Matchers
+    [1,2,3].should include(1)
+    [1,2,3].should include(1, 2)
+    {:a => 'b'}.should include(:a => 'b')
+    "this string".should include("is str")
 
-Matchers are objects used to compose expectations:
+## Learn more
 
-    result.should eq("this value")
+See [RSpec::Expectations](../RSpec/Expectations) for more information about
+`should` and `should_not` and how they work.
 
-In that example, `eq("this value")` returns a `Matcher` object that
-compares the actual `result` to the expected `"this value"`.
+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.
 
 ## Also see
 

data/lib/rspec/expectations.rb

@@ -8,30 +8,38 @@ require 'rspec/expectations/version'
 require 'rspec/expectations/differ'
 
 module RSpec
-  # RSpec::Expectations lets you set expectations on your objects.
+  # RSpec::Expectations adds two instance methods to every object:
   #
-  #   result.should == 37
-  #   team.should have(11).players_on_the_field
+  #     should(matcher=nil)
+  #     should_not(matcher=nil)
   #
-  # == How Expectations work.
+  # 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:
   #
-  # RSpec::Expectations adds two methods to Object:
+  #     order.total.should eq(Money.new(5.55, :USD))
   #
-  #   should(matcher=nil)
-  #   should_not(matcher=nil)
+  # 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`.
   #
-  # Both methods take an optional Expression Matcher (See RSpec::Matchers).
+  # Given the expression:
   #
-  # When +should+ receives an Expression Matcher, it calls <tt>matches?(self)</tt>. If
-  # it returns +true+, the spec passes and execution continues. If it returns
-  # +false+, then the spec fails with the message returned by <tt>matcher.failure_message</tt>.
+  #     order.entries.should_not include(entry)
   #
-  # Similarly, when +should_not+ receives a matcher, it calls <tt>matches?(self)</tt>. If
-  # it returns +false+, the spec passes and execution continues. If it returns
-  # +true+, then the spec fails with the message returned by <tt>matcher.negative_failure_message</tt>.
+  # 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 ships with a standard set of useful matchers, and writing your own
-  # matchers is quite simple. See RSpec::Matchers for details.
+  # 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.
   module Expectations
   end
 end

data/lib/rspec/expectations/handler.rb

@@ -16,7 +16,7 @@ module RSpec
                     matcher.failure_message
         
         if matcher.respond_to?(:diffable?) && matcher.diffable?
-          ::RSpec::Expectations.fail_with message, matcher.expected.first, matcher.actual
+          ::RSpec::Expectations.fail_with message, matcher.expected, matcher.actual
         else
           ::RSpec::Expectations.fail_with message
         end

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '2.7.0'
+      STRING = '2.8.0.rc1'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -1,102 +1,102 @@
 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:
+  # RSpec::Matchers provides a number of useful matchers we use to compose
+  # 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
   #
-  # == Predicates
+  # ## Predicates
   #
-  # In addition to those Expression Matchers that are defined explicitly, RSpec will
-  # create custom Matchers on the fly for any arbitrary predicate, giving your specs
-  # a much more natural language feel.
+  # In addition to matchers that are defined explicitly, RSpec will create
+  # custom matchers on the fly for any arbitrary predicate, giving your specs a
+  # much more natural language feel.
   #
   # A Ruby predicate is a method that ends with a "?" and returns true or false.
-  # Common examples are +empty?+, +nil?+, and +instance_of?+.
+  # Common examples are `empty?`, `nil?`, and `instance_of?`.
   #
-  # All you need to do is write +should be_+ followed by the predicate without
+  # 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
+  # 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.
+  # part of the Ruby libraries (like `Hash#has_key?`) or a method you wrote on your own class.
   #
-  # == Custom Matchers
+  # ## Custom Matchers
   #
-  # When you find that none of the stock Expectation Matchers provide a natural
-  # feeling expectation, you can very easily write your own using RSpec's matcher
-  # DSL or writing one from scratch.
+  # When you find that none of the stock matchers provide a natural feeling
+  # expectation, you can very easily write your own using RSpec's matcher DSL
+  # or writing one from scratch.
   #
-  # === Matcher DSL
+  # ### Matcher DSL
   #
   # Imagine that you are writing a game in which players can be in various
   # 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
+  #     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 do |player|
+  #         # generate and return the appropriate string.
+  #       end
   #
-  #    failure_message_for_should_not 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
+  #       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
@@ -104,67 +104,66 @@ module RSpec
   # <tt>failure_message_for_should_not</tt>) are passed the actual value (the
   # receiver of <tt>should</tt> or <tt>should_not</tt>).
   #
-  # === Custom Matcher from scratch
+  # ### Custom Matcher from scratch
   #
   # You could also write a custom matcher from scratch, as follows:
   #
-  #  class BeInZone
-  #    def initialize(expected)
-  #      @expected = expected
-  #    end
+  #     class BeInZone
+  #       def initialize(expected)
+  #         @expected = expected
+  #       end
   #
-  #    def matches?(target)
-  #      @target = target
-  #      @target.current_zone.eql?(Zone.new(@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
+  #         "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
+  #       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::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,
-    # T::U::TC is a subclass of MT::U::TC and a 1.9 bug can lead
-    # to infinite recursion from the `super` call in our method_missing
-    # hook.  See this gist for more info:
-    #   https://gist.github.com/845896
+    # Include Matchers for other test frameworks.  Note that MiniTest _must_
+    # come before TU because on ruby 1.9, T::U::TC is a subclass of MT::U::TC
+    # and a 1.9 bug can lead to infinite recursion from the `super` call in our
+    # method_missing hook.  See this gist for more info:
+    # https://gist.github.com/845896
     if defined?(MiniTest::Unit::TestCase)
       MiniTest::Unit::TestCase.send(:include, self)
     end
@@ -176,6 +175,7 @@ end
 
 require 'rspec/matchers/extensions/instance_eval_with_args'
 require 'rspec/matchers/pretty'
+require 'rspec/matchers/base_matcher'
 require 'rspec/matchers/matcher'
 require 'rspec/matchers/operator_matcher'
 require 'rspec/matchers/be'