rspec-expectations 3.0.0.beta1 → 3.0.0.beta2

data/spec/rspec/matchers/built_in/eq_spec.rb

@@ -0,0 +1,156 @@
+require 'spec_helper'
+require 'date'
+require 'complex'
+
+module RSpec
+  module Matchers
+    describe "eq" do
+      it_behaves_like "an RSpec matcher", :valid_value => 1, :invalid_value => 2 do
+        let(:matcher) { eq(1) }
+      end
+
+      it "is diffable" do
+        expect(eq(1)).to be_diffable
+      end
+
+      it "matches when actual == expected" do
+        expect(1).to eq(1)
+      end
+
+      it "does not match when actual != expected" do
+        expect(1).not_to eq(2)
+      end
+
+      it "compares by sending == to actual (not expected)" do
+        called = false
+        actual = Class.new do
+          define_method :== do |other|
+            called = true
+          end
+        end.new
+
+        expect(actual).to eq :anything # to trigger the matches? method
+        expect(called).to be_truthy
+      end
+
+      it "describes itself" do
+        matcher = eq(1)
+        matcher.matches?(1)
+        expect(matcher.description).to eq "eq 1"
+      end
+
+      it "provides message, expected and actual on #failure_message" do
+        matcher = eq("1")
+        matcher.matches?(1)
+        expect(matcher.failure_message).to eq "\nexpected: \"1\"\n     got: 1\n\n(compared using ==)\n"
+      end
+
+      it "provides message, expected and actual on #negative_failure_message" do
+        matcher = eq(1)
+        matcher.matches?(1)
+        expect(matcher.failure_message_when_negated).to eq "\nexpected: value != 1\n     got: 1\n\n(compared using ==)\n"
+      end
+
+      it 'fails properly when the actual is an array of multiline strings' do
+        expect {
+          expect(["a\nb", "c\nd"]).to eq([])
+        }.to fail_matching("expected: []")
+      end
+
+      describe '#description' do
+        [
+            [nil, 'eq nil'],
+            [true, 'eq true'],
+            [false, 'eq false'],
+            [:symbol, 'eq :symbol'],
+            [1, 'eq 1'],
+            [1.2, 'eq 1.2'],
+            [Complex(1, 2), "eq #{Complex(1, 2).inspect}"],
+            ['foo', 'eq "foo"'],
+            [/regex/, 'eq /regex/'],
+            [['foo'], 'eq ["foo"]'],
+            [{:foo => :bar}, 'eq {:foo=>:bar}'],
+            [Class, 'eq Class'],
+            [RSpec, 'eq RSpec'],
+            [Date.new(2014, 1, 1), "eq #{Date.new(2014, 1, 1).inspect}"],
+            [Time.utc(2014, 1, 1), "eq #{Time.utc(2014, 1, 1).inspect}"],
+        ].each do |expected, expected_description|
+          context "with #{expected.inspect}" do
+            it "is \"#{expected_description}\"" do
+              expect(eq(expected).description).to eq expected_description
+            end
+          end
+        end
+
+        context 'with object' do
+          it 'matches with "^eq #<Object:0x[0-9a-f]*>$"' do
+            expect(eq(Object.new).description).to match(/^eq #<Object:0x[0-9a-f]*>$/)
+          end
+        end
+      end
+
+      context "Time Equality" do
+        RSpec::Matchers.define :a_string_with_differing_output do
+          match do |string|
+            time_strings = /expected: (.+)\n.*got: (.+)$/.match(string).captures
+            time_strings.uniq.count == 2
+          end
+        end
+
+        RSpec::Matchers.define :a_string_with_identical_output do
+          match do |string|
+            time_strings = /expected: value != (.+)\n.*got: (.+)$/.match(string).captures
+            time_strings.uniq.count == 1
+          end
+        end
+
+        context 'with Time objects' do
+          let(:time1) { Time.utc(1969, 12, 31, 19, 01, 40, 101) }
+          let(:time2) { Time.utc(1969, 12, 31, 19, 01, 40, 102) }
+
+          it 'produces different output for Times differing by milliseconds' do
+            expect {
+              expect(time1).to eq(time2)
+            }.to fail_with(a_string_with_differing_output)
+          end
+        end
+
+        context 'with DateTime objects' do
+          let(:date1) { DateTime.new(2000, 1, 1, 1, 1, Rational(1, 10)) }
+          let(:date2) { DateTime.new(2000, 1, 1, 1, 1, Rational(2, 10)) }
+
+          it 'produces different output for DateTimes differing by milliseconds' do
+            expect {
+              expect(date1).to eq(date2)
+            }.to fail_with(a_string_with_differing_output)
+          end
+
+          it 'does not not assume DateTime is defined since you need to require `date` to make it available' do
+            hide_const('DateTime')
+            expect {
+              expect(5).to eq(4)
+            }.to raise_error(RSpec::Expectations::ExpectationNotMetError)
+          end
+
+          it 'fails with identical output when the DateTimes are exactly the same' do
+            expect {
+              expect(date1).to_not eq(date1)
+            }.to fail_with(a_string_with_identical_output)
+          end
+
+          context 'when ActiveSupport is loaded' do
+            it "uses a custom format to ensure the output is different when DateTimes differ" do
+              stub_const("ActiveSupport", Module.new)
+              allow(date1).to receive(:inspect).and_return("Timestamp")
+              allow(date2).to receive(:inspect).and_return("Timestamp")
+
+              expect {
+                expect(date1).to eq(date2)
+              }.to fail_with(a_string_with_differing_output)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/spec/rspec/matchers/{eql_spec.rb → built_in/eql_spec.rb}

@@ -28,13 +28,13 @@ module RSpec
       it "provides message, expected and actual on #failure_message" do
         matcher = eql("1")
         matcher.matches?(1)
-        expect(matcher.failure_message_for_should).to eq "\nexpected: \"1\"\n     got: 1\n\n(compared using eql?)\n"
+        expect(matcher.failure_message).to eq "\nexpected: \"1\"\n     got: 1\n\n(compared using eql?)\n"
       end
 
       it "provides message, expected and actual on #negative_failure_message" do
         matcher = eql(1)
         matcher.matches?(1)
-        expect(matcher.failure_message_for_should_not).to eq "\nexpected: value != 1\n     got: 1\n\n(compared using eql?)\n"
+        expect(matcher.failure_message_when_negated).to eq "\nexpected: value != 1\n     got: 1\n\n(compared using eql?)\n"
       end
     end
   end

data/spec/rspec/matchers/built_in/equal_spec.rb

@@ -0,0 +1,106 @@
+require 'spec_helper'
+module RSpec
+  module Matchers
+    describe "equal" do
+      it_behaves_like "an RSpec matcher", :valid_value => :a, :invalid_value => :b do
+        let(:matcher) { equal(:a) }
+      end
+
+      def inspect_object(o)
+        "#<#{o.class}:#{o.object_id}> => #{o.inspect}"
+      end
+
+      it "matches when actual.equal?(expected)" do
+        expect(1).to equal(1)
+      end
+
+      it "does not match when !actual.equal?(expected)" do
+        expect("1").not_to equal("1")
+      end
+
+      it "describes itself" do
+        matcher = equal(1)
+        matcher.matches?(1)
+        expect(matcher.description).to eq "equal 1"
+      end
+
+      context "when the expected object is falsey in conditinal semantics" do
+        it "describes itself with the expected object" do
+          matcher = equal(nil)
+          matcher.matches?(nil)
+          expect(matcher.description).to eq "equal nil"
+        end
+      end
+
+      context "when the expected object's #equal? always returns true" do
+        let(:strange_string) do
+          string = "foo"
+
+          def string.equal?(other)
+            true
+          end
+
+          string
+        end
+
+        it "describes itself with the expected object" do
+          matcher = equal(strange_string)
+          matcher.matches?(strange_string)
+          expect(matcher.description).to eq 'equal "foo"'
+        end
+      end
+
+      it "prints a special message for `false`" do
+        expected, actual = false, "1"
+        expect {
+          expect(actual).to equal(expected)
+        }.to fail_with "\nexpected false\n     got #{inspect_object(actual)}\n"
+      end
+
+      it "prints a special message for `true`" do
+        expected, actual = true, "1"
+        expect {
+          expect(actual).to equal(expected)
+        }.to fail_with "\nexpected true\n     got #{inspect_object(actual)}\n"
+      end
+
+      it "prints a special message for `nil`" do
+        expected, actual = nil, "1"
+        expect {
+          expect(actual).to equal(expected)
+        }.to fail_with "\nexpected nil\n     got #{inspect_object(actual)}\n"
+      end
+
+      it "suggests the `eq` matcher on failure" do
+        expected, actual = "1", "1"
+        expect {
+          expect(actual).to equal(expected)
+        }.to fail_with <<-MESSAGE
+
+expected #{inspect_object(expected)}
+     got #{inspect_object(actual)}
+
+Compared using equal?, which compares object identity,
+but expected and actual are not the same object. Use
+`expect(actual).to eq(expected)` if you don't care about
+object identity in this example.
+
+MESSAGE
+      end
+
+      it "provides message on #negative_failure_message" do
+        expected = actual = "1"
+        matcher = equal(expected)
+        matcher.matches?(actual)
+        expect(matcher.failure_message_when_negated).to eq <<-MESSAGE
+
+expected not #{inspect_object(expected)}
+         got #{inspect_object(actual)}
+
+Compared using equal?, which compares object identity.
+
+MESSAGE
+      end
+    end
+  end
+end

data/spec/rspec/matchers/{exist_spec.rb → built_in/exist_spec.rb}

@@ -117,7 +117,7 @@ describe "exist matcher" do
 
   it 'passes any provided arguments to the call to #exist?' do
     object = double
-    object.should_receive(:exist?).with(:foo, :bar) { true }
+    expect(object).to receive(:exist?).with(:foo, :bar) { true }
 
     expect(object).to exist(:foo, :bar)
   end

data/spec/rspec/matchers/{has_spec.rb → built_in/has_spec.rb}

@@ -16,6 +16,34 @@ describe "expect(...).to have_sym(*args)" do
     }.to fail_with("expected #has_key?(:a) to return true, got false")
   end
 
+  obj_with_block_method = Object.new
+  def obj_with_block_method.has_some_stuff?; yield; end
+
+  it 'forwards the given `{ }` block on to the `has_xyz?` method' do
+    expect(obj_with_block_method).to have_some_stuff { true }
+    expect(obj_with_block_method).to_not have_some_stuff { false }
+  end
+
+  it 'forwards the given `do..end` block on to the `has_xyz?` method' do
+    expect(obj_with_block_method).to have_some_stuff do
+      true
+    end
+
+    expect(obj_with_block_method).to_not have_some_stuff do
+      false
+    end
+  end
+
+  it 'favors a curly brace block over a do...end one since it binds to the matcher method' do
+    expect(obj_with_block_method).to have_some_stuff { true } do
+      false
+    end
+
+    expect(obj_with_block_method).not_to have_some_stuff { false } do
+      true
+    end
+  end
+
   it 'does not include any args in the failure message if no args were given to the matcher' do
     o = Object.new
     def o.has_some_stuff?; false; end
@@ -57,6 +85,17 @@ describe "expect(...).to have_sym(*args)" do
       expect(o).to have_sym(:foo)
     }.to raise_error("Funky exception")
   end
+
+  it 'allows composable aliases to be defined' do
+    RSpec::Matchers.alias_matcher :an_object_having_sym, :have_sym
+    o = Object.new
+    def o.has_sym?(sym); sym == :foo; end
+
+    expect(o).to an_object_having_sym(:foo)
+    expect(o).not_to an_object_having_sym(:bar)
+
+    expect(an_object_having_sym(:foo).description).to eq("an object having sym :foo")
+  end
 end
 
 describe "expect(...).not_to have_sym(*args)" do

data/spec/rspec/matchers/{include_spec.rb → built_in/include_spec.rb}

@@ -69,13 +69,13 @@ describe "#include matcher" do
       it "fails if target does not include expected" do
         expect {
           expect({:key => 'value'}).to include(:other)
-        }.to fail_matching(%Q|expected {:key=>"value"} to include :other|)
+        }.to fail_matching(%Q|expected {:key => "value"} to include :other|)
       end
 
       it "fails if target doesn't have a key and we expect nil" do
         expect {
           expect({}).to include(:something => nil)
-        }.to fail_matching(%Q|expected {} to include {:something=>nil}|)
+        }.to fail_matching(%Q|expected {} to include {:something => nil}|)
       end
 
       it 'works even when an entry in the hash overrides #send' do
@@ -132,7 +132,7 @@ describe "#include matcher" do
       it 'fails if target is missing any item as a key' do
         expect {
           expect({:key => 'value'}).to include(:key, :other)
-        }.to fail_matching(%Q|expected {:key=>"value"} to include :key and :other|)
+        }.to fail_matching(%Q|expected {:key => "value"} to include :key and :other|)
       end
     end
   end
@@ -182,7 +182,7 @@ describe "#include matcher" do
       it "fails if target includes expected key" do
         expect {
           expect({:key => 'value'}).not_to include(:key)
-        }.to fail_matching(%Q|expected {:key=>"value"} not to include :key|)
+        }.to fail_matching(%Q|expected {:key => "value"} not to include :key|)
       end
     end
 
@@ -215,13 +215,13 @@ describe "#include matcher" do
       it "fails if the target includes all of the expected keys" do
         expect {
           expect({ :a => 1, :b => 2 }).not_to include(:a, :b)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>2}.inspect} not to include :a and :b|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 2} not to include :a and :b|)
       end
 
       it "fails if the target includes some (but not all) of the expected keys" do
         expect {
           expect({ :a => 1, :b => 2 }).not_to include(:d, :b)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>2}.inspect} not to include :d and :b|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 2} not to include :d and :b|)
       end
     end
 
@@ -257,13 +257,13 @@ describe "#include matcher" do
       it "fails if target has a different value for key" do
         expect {
           expect({:key => 'different'}).to include(:key => 'value')
-        }.to fail_matching(%Q|expected {:key=>"different"} to include {:key=>"value"}|)
+        }.to fail_matching(%Q|expected {:key => "different"} to include {:key => "value"}|)
       end
 
       it "fails if target has a different key" do
         expect {
           expect({:other => 'value'}).to include(:key => 'value')
-        }.to fail_matching(%Q|expected {:other=>"value"} to include {:key=>"value"}|)
+        }.to fail_matching(%Q|expected {:other => "value"} to include {:key => "value"}|)
       end
     end
 
@@ -271,7 +271,7 @@ describe "#include matcher" do
       it "fails if the target does not contain the given hash" do
         expect {
           expect(['a', 'b']).to include(:key => 'value')
-        }.to fail_matching(%q|expected ["a", "b"] to include {:key=>"value"}|)
+        }.to fail_matching(%q|expected ["a", "b"] to include {:key => "value"}|)
       end
 
       it "passes if the target contains the given hash" do
@@ -285,13 +285,13 @@ describe "#include matcher" do
       it "fails if target includes the key/value pair" do
         expect {
           expect({:key => 'value'}).not_to include(:key => 'value')
-        }.to fail_matching(%Q|expected {:key=>"value"} not to include {:key=>"value"}|)
+        }.to fail_matching(%Q|expected {:key => "value"} not to include {:key => "value"}|)
       end
 
       it "fails if target includes the key/value pair among others" do
         expect {
           expect({:key => 'value', :other => 'different'}).not_to include(:key => 'value')
-        }.to fail_matching(%Q|expected #{{:key=>"value", :other=>"different"}.inspect} not to include {:key=>"value"}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :key => "value", :other => "different"} not to include {:key => "value"}|)
       end
 
       it "passes if target has a different value for key" do
@@ -311,7 +311,7 @@ describe "#include matcher" do
       it "fails if the target contains the given hash" do
         expect {
           expect(['a', { :key => 'value' } ]).not_to include(:key => 'value')
-        }.to fail_matching(%Q|expected ["a", {:key=>"value"}] not to include {:key=>"value"}|)
+        }.to fail_matching(%Q|expected ["a", {:key => "value"}] not to include {:key => "value"}|)
       end
     end
   end
@@ -329,25 +329,25 @@ describe "#include matcher" do
       it "fails if target has a different value for one of the keys" do
         expect {
           expect({:a => 1, :b => 2}).to include(:a => 2, :b => 2)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>2}.inspect} to include #{{:a=>2, :b=>2}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 2} to include #{hash_inspect :a => 2, :b => 2}|)
       end
 
       it "fails if target has a different value for both of the keys" do
         expect {
           expect({:a => 1, :b => 1}).to include(:a => 2, :b => 2)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>1}.inspect} to include #{{:a=>2, :b=>2}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 1} to include #{hash_inspect :a => 2, :b => 2}|)
       end
 
       it "fails if target lacks one of the keys" do
         expect {
           expect({:a => 1, :b => 1}).to include(:a => 1, :c => 1)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>1}.inspect} to include #{{:a=>1, :c=>1}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 1} to include #{hash_inspect :a => 1, :c => 1}|)
       end
 
       it "fails if target lacks both of the keys" do
         expect {
           expect({:a => 1, :b => 1}).to include(:c => 1, :d => 1)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>1}.inspect} to include #{{:c=>1, :d=>1}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 1} to include #{hash_inspect :c => 1, :d => 1}|)
       end
     end
 
@@ -355,7 +355,7 @@ describe "#include matcher" do
       it "fails if the target does not contain the given hash" do
         expect {
           expect(['a', 'b']).to include(:a => 1, :b => 1)
-        }.to fail_matching(%Q|expected ["a", "b"] to include #{{:a=>1, :b=>1}.inspect}|)
+        }.to fail_matching(%Q|expected ["a", "b"] to include #{hash_inspect :a => 1, :b => 1}|)
       end
 
       it "passes if the target contains the given hash" do
@@ -369,20 +369,20 @@ describe "#include matcher" do
       it "fails if target includes the key/value pairs" do
         expect {
           expect({:a => 1, :b => 2}).not_to include(:a => 1, :b => 2)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>2}.inspect} not to include #{{:a=>1, :b=>2}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 2} not to include #{hash_inspect :a => 1, :b => 2}|)
       end
 
       it "fails if target includes the key/value pairs among others" do
         hash = {:a => 1, :b => 2, :c => 3}
         expect {
           expect(hash).not_to include(:a => 1, :b => 2)
-        }.to fail_matching(%Q|expected #{hash.inspect} not to include #{{:a=>1, :b=>2}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 2, :c => 3} not to include #{hash_inspect :a => 1, :b => 2}|)
       end
 
       it "fails if target has a different value for one of the keys" do
         expect {
           expect({:a => 1, :b => 2}).not_to include(:a => 2, :b => 2)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>2}.inspect} not to include #{{:a=>2, :b=>2}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 2} not to include #{hash_inspect :a => 2, :b => 2}|)
       end
 
       it "passes if target has a different value for both of the keys" do
@@ -392,7 +392,7 @@ describe "#include matcher" do
       it "fails if target lacks one of the keys" do
         expect {
           expect({:a => 1, :b => 1}).not_to include(:a => 1, :c => 1)
-        }.to fail_matching(%Q|expected #{{:a=>1, :b=>1}.inspect} not to include #{{:a=>1, :c=>1}.inspect}|)
+        }.to fail_matching(%Q|expected #{hash_inspect :a => 1, :b => 1} not to include #{hash_inspect :a => 1, :c => 1}|)
       end
 
       it "passes if target lacks both of the keys" do
@@ -408,124 +408,133 @@ describe "#include matcher" do
       it "fails if the target contains the given hash" do
         expect {
           expect(['a', { :a => 1, :b => 2 } ]).not_to include(:a => 1, :b => 2)
-        }.to fail_matching(%Q|expected #{["a", {:a=>1, :b=>2}].inspect} not to include #{{:a=>1, :b=>2}.inspect}|)
+        }.to fail_matching(%Q|expected ["a", #{hash_inspect :a => 1, :b => 2}] not to include #{hash_inspect :a => 1, :b => 2}|)
       end
     end
   end
-end
-
-RSpec::Matchers.define :a_string_containing do |expected|
-  match do |actual|
-    actual.include?(expected)
-  end
 
-  description do
-    "a string containing '#{expected}'"
-  end
-end
+  describe "Composing matchers with `include`" do
+    RSpec::Matchers.define :a_string_containing do |expected|
+      match do |actual|
+        actual.include?(expected)
+      end
 
-describe "expect(...).to include(matcher)" do
-  context 'for an array target' do
-    it "passes if target includes an object that satisfies the matcher" do
-      expect(['foo', 'bar', 'baz']).to include(a_string_containing("ar"))
+      description do
+        "a string containing '#{expected}'"
+      end
     end
 
-    it "fails if target doesn't include object that satisfies the matcher" do
-      expect {
-        expect(['foo', 'bar', 'baz']).to include(a_string_containing("abc"))
-      }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} to include a string containing 'abc'|)
-    end
+    describe "expect(array).to include(matcher)" do
+      it "passes when the matcher matches one of the values" do
+        expect([10, 20, 30]).to include( a_value_within(5).of(24) )
+      end
 
-    it 'does not include a diff when the match fails' do
-      expect {
-        expect(['foo', 'bar', 'baz']).to include(a_string_containing("abc"))
-      }.to raise_error { |e|
-        expect(e.message).not_to match(/diff/i)
-      }
-    end
+      it 'provides a description' do
+        description = include( a_value_within(5).of(24) ).description
+        expect(description).to eq("include (a value within 5 of 24)")
+      end
 
-    it 'does not treat an object that only implements #matches? as a matcher' do
-      domain = Struct.new(:domain) do
-        def matches?(url)
-          URI(url).host == self.domain
-        end
+      it 'fails with a clear message when the matcher matches none of the values' do
+        expect {
+          expect([10, 30]).to include( a_value_within(5).of(24) )
+        }.to fail_with("expected [10, 30] to include (a value within 5 of 24)")
       end
 
-      expect([domain.new("rspec.info")]).to include(domain.new("rspec.info"))
+      it 'works with comparison matchers' do
+        expect {
+          expect([100, 200]).to include(a_value < 90)
+        }.to fail_with("expected [100, 200] to include (a value < 90)")
 
-      expect {
-        expect([domain.new("rspec.info")]).to include(domain.new("foo.com"))
-      }.to fail_matching("expected [#{domain.new("rspec.info").inspect}] to include")
-    end
+        expect([100, 200]).to include(a_value > 150)
+      end
 
-    it 'works with an old-style matcher that implements failure_message rather than failure_message_for_should' do
-      a_multiple_of = Class.new do
-        def initialize(expected)
-          @expected = expected
+      it 'does not treat an object that only implements #matches? as a matcher' do
+        domain = Struct.new(:domain) do
+          def matches?(url)
+            URI(url).host == self.domain
+          end
         end
 
-        def matches?(actual)
-          (actual % @expected).zero?
-        end
+        expect([domain.new("rspec.info")]).to include(domain.new("rspec.info"))
 
-        def failure_message
-          "expected a multiple of #{@expected}"
-        end
+        expect {
+          expect([domain.new("rspec.info")]).to include(domain.new("foo.com"))
+        }.to fail_matching("expected [#{domain.new("rspec.info").inspect}] to include")
       end
+    end
 
-      # Verify the matcher works normally
-      expect(10).to a_multiple_of.new(5)
+    describe "expect(array).to include(multiple, matcher, arguments)" do
+      it "passes if target includes items satisfying all matchers" do
+        expect(['foo', 'bar', 'baz']).to include(a_string_containing("ar"), a_string_containing('oo'))
+      end
 
-      expect {
-        expect(10).to a_multiple_of.new(7)
-      }.to fail_with("expected a multiple of 7")
+      it "fails if target does not include an item satisfying any one of the items" do
+        expect {
+          expect(['foo', 'bar', 'baz']).to include(a_string_containing("ar"), a_string_containing("abc"))
+        }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} to include (a string containing 'ar') and (a string containing 'abc')|)
+      end
+    end
 
-      expect([12, 13, 14]).to include(a_multiple_of.new(6))
+    describe "expect(hash).to include(key => matcher)" do
+      it "passes when the matcher matches" do
+        expect(:a => 12).to include(:a => a_value_within(3).of(10))
+      end
 
-      expect {
-        expect([12, 13, 14]).to include(a_multiple_of.new(10))
-      }.to fail_matching("expected [12, 13, 14] to include")
-    end
-  end
-end
+      it 'provides a description' do
+        description = include(:a => a_value_within(3).of(10)).description
+        expect(description).to eq("include {:a => (a value within 3 of 10)}")
+      end
 
-describe "expect(...).to include(multiple, matcher, arguments)" do
-  context 'for an array target' do
-    it "passes if target includes items satisfying all matchers" do
-      expect(['foo', 'bar', 'baz']).to include(a_string_containing("ar"), a_string_containing('oo'))
+      it "fails with a clear message when the matcher does not match" do
+        expect {
+          expect(:a => 15).to include(:a => a_value_within(3).of(10))
+        }.to fail_matching("expected {:a => 15} to include {:a => (a value within 3 of 10)}")
+      end
     end
 
-    it "fails if target does not include an item satisfying any one of the items" do
-      expect {
-        expect(['foo', 'bar', 'baz']).to include(a_string_containing("ar"), a_string_containing("abc"))
-      }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} to include a string containing 'ar' and a string containing 'abc'|)
-    end
+    describe "expect(hash).to include(key_matcher)" do
+      it "passes when the matcher matches a key", :if => (RUBY_VERSION.to_f > 1.8) do
+        expect(:drink => "water", :food => "bread").to include(a_string_matching(/foo/))
+      end
 
-    it 'does not include a diff when the match fails' do
-      expect {
-        expect(['foo', 'bar', 'baz']).to include(a_string_containing("ar"), a_string_containing("abc"))
-      }.to raise_error { |e|
-        expect(e.message).not_to match(/diff/i)
-      }
+      it 'provides a description' do
+        description = include(a_string_matching(/foo/)).description
+        expect(description).to eq("include (a string matching /foo/)")
+      end
+
+      it 'fails with a clear message when the matcher does not match', :if => (RUBY_VERSION.to_f > 1.8) do
+        expect {
+          expect(:drink => "water", :food => "bread").to include(a_string_matching(/bar/))
+        }.to fail_matching('expected {:drink => "water", :food => "bread"} to include (a string matching /bar/)')
+      end
     end
-  end
-end
 
-describe "expect(...).not_to include(multiple, matcher, arguments)" do
-  it "passes if none of the target values satisfies any of the matchers" do
-    expect(['foo', 'bar', 'baz']).not_to include(a_string_containing("gh"), a_string_containing('de'))
-  end
+    describe "expect(array).not_to include(multiple, matcher, arguments)" do
+      it "passes if none of the target values satisfies any of the matchers" do
+        expect(['foo', 'bar', 'baz']).not_to include(a_string_containing("gh"), a_string_containing('de'))
+      end
 
-  it 'fails if all of the matchers are satisfied by one of the target values' do
-    expect {
-      expect(['foo', 'bar', 'baz']).not_to include(a_string_containing("ar"), a_string_containing('az'))
-    }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} not to include a string containing 'ar' and a string containing 'az'|)
+      it 'fails if all of the matchers are satisfied by one of the target values' do
+        expect {
+          expect(['foo', 'bar', 'baz']).not_to include(a_string_containing("ar"), a_string_containing('az'))
+        }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} not to include (a string containing 'ar') and (a string containing 'az')|)
+      end
+
+      it 'fails if the some (but not all) of the matchers are satisifed' do
+        expect {
+          expect(['foo', 'bar', 'baz']).not_to include(a_string_containing("ar"), a_string_containing('bz'))
+        }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} not to include (a string containing 'ar') and (a string containing 'bz')|)
+      end
+    end
   end
 
-  it 'fails if the some (but not all) of the matchers are satisifed' do
-    expect {
-      expect(['foo', 'bar', 'baz']).not_to include(a_string_containing("ar"), a_string_containing('bz'))
-    }.to fail_matching(%Q|expected #{['foo', 'bar', 'baz'].inspect} not to include a string containing 'ar' and a string containing 'bz'|)
+  include RSpec::Matchers::Pretty
+  # We have to use Hash#inspect in examples that have multi-entry
+  # hashes because the #inspect output on 1.8.7 is non-deterministic
+  # due to the fact that hashes are not ordered. So we can't simply
+  # put a literal string for what we expect because it varies.
+  def hash_inspect(hash)
+    improve_hash_formatting(hash.inspect)
   end
 end