rspec-expectations 3.0.4 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: effc74da27b6c9c3e1848c1aa153d7cb9bb2741f
-  data.tar.gz: 273bbb72209bc00f42208e6afbd429e557989229
+  metadata.gz: 0d67d8e69dfda8789a69783ab55ae688851cd637
+  data.tar.gz: b7eeed6108dc7341331d64f62e1c057c08545c9c
 SHA512:
-  metadata.gz: ffda9a9a4e44c478f14a87750353a98ef006a7797d82d45cc86606e9a8ba3affffd45aa095195258808417afb6a8012a8c9698b21fc6f0f0c3051e6c72b9d956
-  data.tar.gz: da81d97b60f639f6bf33f6d4a14ec76f8f4e6113844753d4cc8829e09cd5c13beeec25a7bf40ed7c7039f43730289cf91ad5d54e77dfc53c0a9c7433382cc746
+  metadata.gz: 5b49a1de8f140c99b2bf9fda0af0382c6381f44dfb568626720297c5cd83a9eff033facefa2ff4f312c81c73e9257499bbee9cfe1010f527763d241c8155e2f5
+  data.tar.gz: c054e2dee14f838f498918c7b3964381c633fa7d8552242fc16d3d267300cc071aad83e6ef3eedbedda9a9de63553bc27d0d15099fe93c6221eb087b9e02748e

data/Changelog.md

@@ -1,3 +1,34 @@
+### 3.1.0 / 2014-09-04
+[Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.0.4...v3.1.0)
+
+Enhancements:
+
+* Add `have_attributes` matcher, that passes if actual's attribute
+  values match the expected attributes hash:
+  `Person = Struct.new(:name, :age)`
+  `person = Person.new("Bob", 32)`
+  `expect(person).to have_attributes(:name => "Bob", :age => 32)`.
+  (Adam Farhi, #571)
+* Extended compound matcher support to block matchers, for cases like:
+  `expect { ... }.to change { x }.to(3).and change { y }.to(4)`. (Myron
+  Marston, #567)
+* Include chained methods in custom matcher description and failure message
+  when new `include_chain_clauses_in_custom_matcher_descriptions` config
+  option is enabled. (Dan Oved, #600)
+* Add `thrice` modifier to `yield_control` matcher as a synonym for
+  `exactly(3).times`. (Dennis Taylor, #615)
+* Add `RSpec::Matchers.define_negated_matcher`, which defines a negated
+  version of the named matcher. (Adam Farhi, Myron Marston, #618)
+* Document and support negation of `contain_exactly`/`match_array`.
+  (Jon Rowe, #626).
+
+Bug Fixes:
+
+* Rename private `LegacyMacherAdapter` constant to `LegacyMatcherAdapter`
+  to fix typo. (Abdelkader Boudih, #563)
+* Fix `all` matcher so that it fails properly (rather than raising a
+  `NoMethodError`) when matched against a non-enumerable. (Hao Su, #622)
+
 ### 3.0.4 / 2014-08-14
 [Full Changelog](http://github.com/rspec/rspec-expectations/compare/v3.0.3...v3.0.4)
 
@@ -162,7 +193,7 @@ Enhancements:
 * Define noun-phrase aliases for built-in matchers, which can be
   used when creating composed matcher expressions that read better
   and provide better failure messages. (Myron Marston)
-* Add `RSpec::Machers.alias_matcher` so users can define their own
+* Add `RSpec::Matchers.alias_matcher` so users can define their own
   matcher aliases. The `description` of the matcher will reflect the
   alternate matcher name. (Myron Marston)
 * Add explicit `be_between` matcher. `be_between` has worked for a

data/lib/rspec/expectations/configuration.rb

@@ -107,6 +107,18 @@ module RSpec
                                  end
       end
 
+      # Sets if custom matcher descriptions and failure messages
+      # should include clauses from methods defined using `chain`.
+      # @param value [Boolean]
+      attr_writer :include_chain_clauses_in_custom_matcher_descriptions
+
+      # Indicates whether or not custom matcher descriptions and failure messages
+      # should include clauses from methods defined using `chain`. It is
+      # false by default for backwards compatibility.
+      def include_chain_clauses_in_custom_matcher_descriptions?
+        @include_chain_clauses_in_custom_matcher_descriptions ||= false
+      end
+
       # @private
       def reset_syntaxes_to_default
         self.syntax = [:should, :expect]

data/lib/rspec/expectations/handler.rb

@@ -17,8 +17,8 @@ module RSpec
       #
       # @private
       def self.modern_matcher_from(matcher)
-        LegacyMacherAdapter::RSpec2.wrap(matcher) ||
-        LegacyMacherAdapter::RSpec1.wrap(matcher) || matcher
+        LegacyMatcherAdapter::RSpec2.wrap(matcher) ||
+        LegacyMatcherAdapter::RSpec1.wrap(matcher) || matcher
       end
 
       def self.setup(handler, matcher, message)
@@ -95,7 +95,7 @@ module RSpec
     # order to present the current protocol.
     #
     # @private
-    class LegacyMacherAdapter < Matchers::MatcherDelegator
+    class LegacyMatcherAdapter < Matchers::MatcherDelegator
       def initialize(matcher)
         super
         ::RSpec.warn_deprecation(<<-EOS.gsub(/^\s+\|/, ''), :type => "legacy_matcher")
@@ -157,5 +157,11 @@ module RSpec
         end
       end
     end
+
+    # RSpec 3.0 was released with the class name misspelled. For SemVer compatibility,
+    # we will provide this misspelled alias until 4.0.
+    # @deprecated Use LegacyMatcherAdapter instead.
+    # @private
+    LegacyMacherAdapter = LegacyMatcherAdapter
   end
 end

data/lib/rspec/expectations/version.rb

@@ -2,7 +2,7 @@ module RSpec
   module Expectations
     # @private
     module Version
-      STRING = '3.0.4'
+      STRING = '3.1.0'
     end
   end
 end

data/lib/rspec/matchers.rb

@@ -1,4 +1,5 @@
 require 'rspec/support'
+RSpec::Support.require_rspec_support 'matcher_definition'
 RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relative(f) }
 
 %w[
@@ -15,17 +16,8 @@ RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relat
 # in the `RSpec::Expectations` and `RSpec::Matchers` namespaces.
 module RSpec
   # RSpec::Matchers provides a number of useful matchers we use to define
-  # expectations. A matcher is any object that responds to the following:
-  #
-  #     matches?(actual)
-  #     failure_message
-  #
-  # These methods are also part of the matcher protocol, but are optional:
-  #
-  #     does_not_match?(actual)
-  #     failure_message_when_negated
-  #     description
-  #     supports_block_expectations?
+  # expectations. Any object that implements the [matcher protocol](Matchers/MatcherProtocol)
+  # can be used as a matcher.
   #
   # ## Predicates
   #
@@ -226,6 +218,8 @@ module RSpec
     #
     # @param new_name [Symbol] the new name for the matcher
     # @param old_name [Symbol] the original name for the matcher
+    # @param options  [Hash] options for the aliased matcher
+    # @option options [Class] :klass the ruby class to use as the decorator. (Not normally used).
     # @yield [String] optional block that, when given is used to define the overriden
     #   description. The yielded arg is the original description. If no block is
     #   provided, a default description override is used based on the old and
@@ -249,17 +243,38 @@ module RSpec
     # @!macro [attach] alias_matcher
     #   @!parse
     #     alias $1 $2
-    def self.alias_matcher(new_name, old_name, &description_override)
+    def self.alias_matcher(new_name, old_name, options={}, &description_override)
       description_override ||= lambda do |old_desc|
         old_desc.gsub(Pretty.split_words(old_name), Pretty.split_words(new_name))
       end
+      klass = options.fetch(:klass) { AliasedMatcher }
 
       define_method(new_name) do |*args, &block|
         matcher = __send__(old_name, *args, &block)
-        AliasedMatcher.new(matcher, description_override)
+        klass.new(matcher, description_override)
       end
     end
 
+    # Defines a negated matcher. The returned matcher's `description` and `failure_message`
+    # will be overriden to reflect the phrasing of the new name, and the match logic will
+    # be based on the original matcher but negated.
+    #
+    # @param negated_name [Symbol] the name for the negated matcher
+    # @param base_name [Symbol] the name of the original matcher that will be negated
+    # @yield [String] optional block that, when given is used to define the overriden
+    #   description. The yielded arg is the original description. If no block is
+    #   provided, a default description override is used based on the old and
+    #   new names.
+    #
+    # @example
+    #
+    #   RSpec::Matchers.define_negated_matcher :a_value_not_between, :a_value_between
+    #   a_value_between(3, 5).description # => "a value between 3 and 5"
+    #   a_value_not_between(3, 5).description # => "a value not between 3 and 5"
+    def self.define_negated_matcher(negated_name, base_name, &description_override)
+      alias_matcher(negated_name, base_name, :klass => AliasedNegatedMatcher, &description_override)
+    end
+
     # Passes if actual is truthy (anything but false or nil)
     def be_truthy
       BuiltIn::BeTruthy.new
@@ -303,7 +318,7 @@ module RSpec
     def be(*args)
       args.empty? ? Matchers::BuiltIn::Be.new : equal(*args)
     end
-    alias_matcher :a_value, :be
+    alias_matcher :a_value, :be, :klass => AliasedMatcherWithOperatorSupport
 
     # passes if target.kind_of?(klass)
     def be_a(klass)
@@ -382,11 +397,14 @@ module RSpec
     # You can chain any of the following off of the end to specify details
     # about the change:
     #
+    # * `from`
+    # * `to`
+    #
+    # or any one of:
+    #
     # * `by`
     # * `by_at_least`
     # * `by_at_most`
-    # * `from`
-    # * `to`
     #
     # @example
     #
@@ -455,9 +473,6 @@ module RSpec
     # @note This is also available using the `=~` operator with `should`,
     #       but `=~` is not supported with `expect`.
     #
-    # @note This matcher only supports positive expectations.
-    #       `expect(...).not_to contain_exactly(other_array)` is not supported.
-    #
     # @example
     #
     #   expect([1, 2, 3]).to contain_exactly(1, 2, 3)
@@ -560,6 +575,27 @@ module RSpec
     alias_matcher :an_object_existing, :exist
     alias_matcher :existing,           :exist
 
+    # Passes if actual's attribute values match the expected attributes hash.
+    # This works no matter how you define your attribute readers.
+    #
+    # @example
+    #
+    #   Person = Struct.new(:name, :age)
+    #   person = Person.new("Bob", 32)
+    #
+    #   expect(person).to have_attributes(:name => "Bob", :age => 32)
+    #   expect(person).to have_attributes(:name => a_string_starting_with("B"), :age => (a_value > 30) )
+    #
+    # @note It will fail if actual doesn't respond to any of the expected attributes.
+    #
+    # @example
+    #
+    #   expect(person).to have_attributes(:color => "red")
+    def have_attributes(expected)
+      BuiltIn::HaveAttributes.new(expected)
+    end
+    alias_matcher :an_object_having_attributes, :have_attributes
+
     # Passes if actual includes expected. This works for
     # collections and Strings. You can also pass in multiple args
     # and it will only pass if all args are found in collection.
@@ -906,13 +942,23 @@ module RSpec
     # @api private
     def self.is_a_matcher?(obj)
       return true  if ::RSpec::Matchers::BuiltIn::BaseMatcher === obj
-      return false if obj.respond_to?(:i_respond_to_everything_so_im_not_really_a_matcher)
+      begin
+        return false if obj.respond_to?(:i_respond_to_everything_so_im_not_really_a_matcher)
+      rescue NoMethodError
+        # Some objects, like BasicObject, don't implemented standard
+        # reflection methods.
+        return false
+      end
       return false unless obj.respond_to?(:matches?)
 
       obj.respond_to?(:failure_message) ||
       obj.respond_to?(:failure_message_for_should) # support legacy matchers
     end
 
+    ::RSpec::Support.register_matcher_definition do |obj|
+      is_a_matcher?(obj)
+    end
+
     # @api private
     def self.is_a_describable_matcher?(obj)
       is_a_matcher?(obj) && obj.respond_to?(:description)

data/lib/rspec/matchers/aliased_matcher.rb

@@ -29,13 +29,57 @@ module RSpec
 
       # Provides the description of the aliased matcher. Aliased matchers
       # are designed to behave identically to the original matcher except
-      # for this method. The description is different to reflect the aliased
-      # name.
+      # for the description and failure messages. The description is different
+      # to reflect the aliased name.
       #
       # @api private
       def description
         @description_block.call(super)
       end
+
+      # Provides the failure_message of the aliased matcher. Aliased matchers
+      # are designed to behave identically to the original matcher except
+      # for the description and failure messages. The failure_message is different
+      # to reflect the aliased name.
+      #
+      # @api private
+      def failure_message
+        @description_block.call(super)
+      end
+
+      # Provides the failure_message_when_negated of the aliased matcher. Aliased matchers
+      # are designed to behave identically to the original matcher except
+      # for the description and failure messages. The failure_message_when_negated is different
+      # to reflect the aliased name.
+      #
+      # @api private
+      def failure_message_when_negated
+        @description_block.call(super)
+      end
+    end
+
+    # Decorator used for matchers that have special implementations of
+    # operators like `==` and `===`.
+    # @private
+    class AliasedMatcherWithOperatorSupport < AliasedMatcher
+      # We undef these so that they get delegated via `method_missing`.
+      undef ==
+      undef ===
+    end
+
+    # @private
+    class AliasedNegatedMatcher < AliasedMatcher
+      def matches?(*args, &block)
+        if @base_matcher.respond_to?(:does_not_match?)
+          @base_matcher.does_not_match?(*args, &block)
+        else
+          !super
+        end
+      end
+
+      def does_not_match?(*args, &block)
+        @base_matcher.matches?(*args, &block)
+      end
     end
   end
 end

data/lib/rspec/matchers/built_in.rb

@@ -30,6 +30,7 @@ module RSpec
       autoload :Equal,                   'rspec/matchers/built_in/equal'
       autoload :Exist,                   'rspec/matchers/built_in/exist'
       autoload :Has,                     'rspec/matchers/built_in/has'
+      autoload :HaveAttributes,          'rspec/matchers/built_in/have_attributes'
       autoload :Include,                 'rspec/matchers/built_in/include'
       autoload :All,                     'rspec/matchers/built_in/all'
       autoload :Match,                   'rspec/matchers/built_in/match'

data/lib/rspec/matchers/built_in/all.rb

@@ -21,6 +21,10 @@ module RSpec
         # @api private
         # @return [String]
         def failure_message
+          unless enumerable?
+            return "#{improve_hash_formatting(super)}, but was not enumerable"
+          end
+
           all_messages = [improve_hash_formatting(super)]
           failed_objects.each do |index, matcher_failure_message|
             all_messages << failure_message_for_item(index, matcher_failure_message)
@@ -37,6 +41,8 @@ module RSpec
       private
 
         def match(_expected, _actual)
+          return false unless enumerable?
+
           index_failed_objects
           failed_objects.empty?
         end
@@ -69,6 +75,10 @@ module RSpec
           @matcher = @matcher.clone
           super
         end
+
+        def enumerable?
+          Enumerable === @actual
+        end
       end
     end
   end

data/lib/rspec/matchers/built_in/base_matcher.rb

@@ -95,6 +95,11 @@ module RSpec
           false
         end
 
+        # @api private
+        def expects_call_stack_jump?
+          false
+        end
+
       private
 
         def assert_ivars(*expected_ivars)

data/lib/rspec/matchers/built_in/be_within.rb

@@ -4,9 +4,7 @@ module RSpec
       # @api private
       # Provides the implementation for `be_within`.
       # Not intended to be instantiated directly.
-      class BeWithin
-        include Composable
-
+      class BeWithin < BaseMatcher
         def initialize(delta)
           @delta = delta
         end
@@ -55,11 +53,6 @@ module RSpec
           "be within #{@delta}#{@unit} of #{@expected}"
         end
 
-        # @private
-        def supports_block_expectations?
-          false
-        end
-
       private
 
         def numeric?

data/lib/rspec/matchers/built_in/change.rb

@@ -4,9 +4,7 @@ module RSpec
       # @api private
       # Provides the implementation for `change`.
       # Not intended to be instantiated directly.
-      class Change
-        include Composable
-
+      class Change < BaseMatcher
         # @api public
         # Specifies the delta of the expected change.
         def by(expected_delta)
@@ -104,9 +102,7 @@ module RSpec
 
       # Used to specify a relative change.
       # @api private
-      class ChangeRelatively
-        include Composable
-
+      class ChangeRelatively < BaseMatcher
         def initialize(change_details, expected_delta, relativity, &comparer)
           @change_details = change_details
           @expected_delta = expected_delta
@@ -152,8 +148,7 @@ module RSpec
 
       # @api private
       # Base class for specifying a change from and/or to specific values.
-      class SpecificValuesChange
-        include Composable
+      class SpecificValuesChange < BaseMatcher
         # @private
         MATCH_ANYTHING = ::Object.ancestors.last
 

data/lib/rspec/matchers/built_in/compound.rb

@@ -14,8 +14,10 @@ module RSpec
 
         # @private
         def does_not_match?(_actual)
-          raise NotImplementedError, "`expect(...).not_to " \
-            "matcher.#{conjunction} matcher` is not supported"
+          raise NotImplementedError, "`expect(...).not_to matcher.#{conjunction} matcher` " \
+            "is not supported, since it creates a bit of an ambiguity. Instead, define negated versions " \
+            "of whatever matchers you wish to negate with `RSpec::Matchers.define_negated_matcher` and " \
+            "use `expect(...).to matcher.#{conjunction} matcher`."
         end
 
         # @api private
@@ -24,6 +26,16 @@ module RSpec
           singleline_message(matcher_1.description, matcher_2.description)
         end
 
+        def supports_block_expectations?
+          matcher_supports_block_expectations?(matcher_1) &&
+          matcher_supports_block_expectations?(matcher_2)
+        end
+
+        def expects_call_stack_jump?
+          NestedEvaluator.matcher_expects_call_stack_jump?(matcher_1) ||
+          NestedEvaluator.matcher_expects_call_stack_jump?(matcher_2)
+        end
+
       private
 
         def initialize_copy(other)
@@ -32,6 +44,16 @@ module RSpec
           super
         end
 
+        def match(_expected, actual)
+          evaluator_klass = if supports_block_expectations? && Proc === actual
+                              NestedEvaluator
+                            else
+                              SequentialEvaluator
+                            end
+
+          @evaluator = evaluator_klass.new(actual, matcher_1, matcher_2)
+        end
+
         def indent_multiline_message(message)
           message.lines.map do |line|
             line =~ /\S/ ? '   ' + line : line
@@ -65,15 +87,133 @@ module RSpec
           [message_1, conjunction, message_2].join(' ')
         end
 
+        def matcher_1_matches?
+          @evaluator.matcher_matches?(matcher_1)
+        end
+
+        def matcher_2_matches?
+          @evaluator.matcher_matches?(matcher_2)
+        end
+
+        def matcher_supports_block_expectations?(matcher)
+          matcher.supports_block_expectations?
+        rescue NoMethodError
+          false
+        end
+
+        # For value expectations, we can evaluate the matchers sequentially.
+        class SequentialEvaluator
+          def initialize(actual, *)
+            @actual = actual
+          end
+
+          def matcher_matches?(matcher)
+            matcher.matches?(@actual)
+          end
+        end
+
+        # Normally, we evaluate the matching sequentially. For an expression like
+        # `expect(x).to foo.and bar`, this becomes:
+        #
+        #   expect(x).to foo
+        #   expect(x).to bar
+        #
+        # For block expectations, we need to nest them instead, so that
+        # `expect { x }.to foo.and bar` becomes:
+        #
+        #   expect {
+        #     expect { x }.to foo
+        #   }.to bar
+        #
+        # This is necessary so that the `expect` block is only executed once.
+        class NestedEvaluator
+          def initialize(actual, matcher_1, matcher_2)
+            @actual        = actual
+            @matcher_1     = matcher_1
+            @matcher_2     = matcher_2
+            @match_results = {}
+
+            inner, outer = order_block_matchers
+
+            @match_results[outer] = outer.matches?(Proc.new do |*args|
+              @match_results[inner] = inner.matches?(inner_matcher_block(args))
+            end)
+          end
+
+          def matcher_matches?(matcher)
+            @match_results.fetch(matcher)
+          end
+
+        private
+
+          # Some block matchers (such as `yield_xyz`) pass args to the `expect` block.
+          # When such a matcher is used as the outer matcher, we need to forward the
+          # the args on to the `expect` block.
+          def inner_matcher_block(outer_args)
+            return @actual if outer_args.empty?
+
+            Proc.new do |*inner_args|
+              unless inner_args.empty?
+                raise ArgumentError, "(#{@matcher_1.description}) and " \
+                  "(#{@matcher_2.description}) cannot be combined in a compound expectation " \
+                  "since both matchers pass arguments to the block."
+              end
+
+              @actual.call(*outer_args)
+            end
+          end
+
+          # For a matcher like `raise_error` or `throw_symbol`, where the block will jump
+          # up the call stack, we need to order things so that it is the inner matcher.
+          # For example, we need it to be this:
+          #
+          #   expect {
+          #     expect {
+          #       x += 1
+          #       raise "boom"
+          #     }.to raise_error("boom")
+          #   }.to change { x }.by(1)
+          #
+          # ...rather than:
+          #
+          #   expect {
+          #     expect {
+          #       x += 1
+          #       raise "boom"
+          #     }.to change { x }.by(1)
+          #   }.to raise_error("boom")
+          #
+          # In the latter case, the after-block logic in the `change` matcher would never
+          # get executed because the `raise "boom"` line would jump to the `rescue` in the
+          # `raise_error` logic, so only the former case will work properly.
+          #
+          # This method figures out which matcher should be the inner matcher and which
+          # should be the outer matcher.
+          def order_block_matchers
+            return @matcher_1, @matcher_2 unless self.class.matcher_expects_call_stack_jump?(@matcher_2)
+            return @matcher_2, @matcher_1 unless self.class.matcher_expects_call_stack_jump?(@matcher_1)
+
+            raise ArgumentError, "(#{@matcher_1.description}) and " \
+              "(#{@matcher_2.description}) cannot be combined in a compound expectation " \
+              "because they both expect a call stack jump."
+          end
+
+          def self.matcher_expects_call_stack_jump?(matcher)
+            matcher.expects_call_stack_jump?
+          rescue NoMethodError
+            false
+          end
+        end
+
         # @api public
         # Matcher used to represent a compound `and` expectation.
         class And < self
           # @api private
           # @return [String]
           def failure_message
-            if @matcher_1_matches
+            if matcher_1_matches?
               matcher_2.failure_message
-            elsif @matcher_2_matches
+            elsif matcher_2_matches?
               matcher_1.failure_message
             else
               compound_failure_message
@@ -82,11 +222,9 @@ module RSpec
 
         private
 
-          def match(_expected, actual)
-            @matcher_1_matches = matcher_1.matches?(actual)
-            @matcher_2_matches = matcher_2.matches?(actual)
-
-            @matcher_1_matches && @matcher_2_matches
+          def match(*)
+            super
+            matcher_1_matches? && matcher_2_matches?
           end
 
           def conjunction
@@ -105,8 +243,9 @@ module RSpec
 
         private
 
-          def match(_expected, actual)
-            matcher_1.matches?(actual) || matcher_2.matches?(actual)
+          def match(*)
+            super
+            matcher_1_matches? || matcher_2_matches?
           end
 
           def conjunction

data/lib/rspec/matchers/built_in/contain_exactly.rb

@@ -23,7 +23,7 @@ module RSpec
         # @api private
         # @return [String]
         def failure_message_when_negated
-          "`contain_exactly` does not support negation"
+          "expected #{actual.inspect} not to contain exactly#{to_sentence(surface_descriptions_in expected)}"
         end
 
         # @api private

data/lib/rspec/matchers/built_in/has.rb

@@ -4,9 +4,7 @@ module RSpec
       # @api private
       # Provides the implementation for `has_<predicate>`.
       # Not intended to be instantiated directly.
-      class Has
-        include Composable
-
+      class Has < BaseMatcher
         def initialize(method_name, *args, &block)
           @method_name, @args, @block = method_name, args, block
         end
@@ -43,11 +41,6 @@ module RSpec
           [method_description, args_description].compact.join(' ')
         end
 
-        # @private
-        def supports_block_expectations?
-          false
-        end
-
       private
 
         def predicate_accessible?
@@ -74,7 +67,11 @@ module RSpec
         end
 
         def predicate
-          @predicate ||= :"has_#{@method_name.to_s.match(Matchers::HAS_REGEX).captures.first}?"
+          # On 1.9, there appears to be a bug where String#match can return `false`
+          # rather than the match data object. Changing to Regex#match appears to
+          # work around this bug. For an example of this bug, see:
+          # https://travis-ci.org/rspec/rspec-expectations/jobs/27549635
+          @predicate ||= :"has_#{Matchers::HAS_REGEX.match(@method_name.to_s).captures.first}?"
         end
 
         def method_description

data/lib/rspec/matchers/built_in/have_attributes.rb

@@ -0,0 +1,84 @@
+module RSpec
+  module Matchers
+    module BuiltIn
+      # @api private
+      # Provides the implementation for `have_attributes`.
+      # Not intended to be instantiated directly.
+      class HaveAttributes < BaseMatcher
+        # @private
+        attr_reader :respond_to_failed
+
+        def initialize(expected)
+          @expected = expected
+          @respond_to_failed = false
+        end
+
+        # @api private
+        # @return [Boolean]
+        def matches?(actual)
+          @actual = actual
+          return false unless respond_to_attributes?
+          perform_match(:all?)
+        end
+
+        # @api private
+        # @return [Boolean]
+        def does_not_match?(actual)
+          @actual = actual
+          return false unless respond_to_attributes?
+          perform_match(:none?)
+        end
+
+        # @api private
+        # @return [String]
+        def description
+          described_items = surface_descriptions_in(expected)
+          improve_hash_formatting "have attributes #{described_items.inspect}"
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message
+          respond_to_failure_message_or { super }
+        end
+
+        # @api private
+        # @return [String]
+        def failure_message_when_negated
+          respond_to_failure_message_or { super }
+        end
+
+      private
+
+        def perform_match(predicate)
+          expected.__send__(predicate) do |attribute_key, attribute_value|
+            actual_has_attribute?(attribute_key, attribute_value)
+          end
+        end
+
+        def actual_has_attribute?(attribute_key, attribute_value)
+          actual_value = actual.__send__(attribute_key)
+          values_match?(attribute_value, actual_value)
+        end
+
+        def respond_to_attributes?
+          matches = respond_to_matcher.matches?(actual)
+          @respond_to_failed = !matches
+          matches
+        end
+
+        def respond_to_matcher
+          @respond_to_matcher ||= RespondTo.new(*expected.keys).with(0).arguments
+        end
+
+        def respond_to_failure_message_or
+          if respond_to_failed
+            respond_to_matcher.failure_message
+          else
+            improve_hash_formatting(yield)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rspec/matchers/built_in/output.rb

@@ -8,7 +8,9 @@ module RSpec
       # Not intended to be instantiated directly.
       class Output < BaseMatcher
         def initialize(expected)
-          @expected = expected
+          @expected        = expected
+          @actual          = ""
+          @block           = nil
           @stream_capturer = NullCapture
         end
 

data/lib/rspec/matchers/built_in/raise_error.rb

@@ -4,6 +4,7 @@ module RSpec
       # @api private
       # Provides the implementation for `raise_error`.
       # Not intended to be instantiated directly.
+      # rubocop:disable ClassLength
       class RaiseError
         include Composable
 
@@ -66,6 +67,10 @@ module RSpec
           true
         end
 
+        def expects_call_stack_jump?
+          true
+        end
+
         # @api private
         # @return [String]
         def failure_message
@@ -163,6 +168,7 @@ module RSpec
           raise "`expect { }.to raise_error(message).with_message(message)` is not valid. The matcher only allows the expected message to be specified once"
         end
       end
+      # rubocop:enable ClassLength
     end
   end
 end

data/lib/rspec/matchers/built_in/respond_to.rb

@@ -6,9 +6,7 @@ module RSpec
       # @api private
       # Provides the implementation for `respond_to`.
       # Not intended to be instantiated directly.
-      class RespondTo
-        include Composable
-
+      class RespondTo < BaseMatcher
         def initialize(*names)
           @names = names
           @expected_arity = nil
@@ -62,11 +60,6 @@ module RSpec
           "respond to #{pp_names}#{with_arity}"
         end
 
-        # @private
-        def supports_block_expectations?
-          false
-        end
-
       private
 
         def find_failing_method_names(actual, filter_method)
@@ -80,7 +73,7 @@ module RSpec
           return true unless @expected_arity
 
           signature = Support::MethodSignature.new(actual.method(name))
-          Support::MethodSignatureVerifier.new(signature, Array.new(@expected_arity)).valid?
+          Support::StrictSignatureVerifier.new(signature, Array.new(@expected_arity)).valid?
         end
 
         def with_arity

data/lib/rspec/matchers/built_in/satisfy.rb

@@ -4,9 +4,7 @@ module RSpec
       # @api private
       # Provides the implementation for `satisfy`.
       # Not intended to be instantiated directly.
-      class Satisfy
-        include Composable
-
+      class Satisfy < BaseMatcher
         def initialize(&block)
           @block = block
         end
@@ -35,11 +33,6 @@ module RSpec
         def description
           "satisfy block"
         end
-
-        # @private
-        def supports_block_expectations?
-          false
-        end
       end
     end
   end

data/lib/rspec/matchers/built_in/throw_symbol.rb

@@ -94,6 +94,10 @@ module RSpec
           true
         end
 
+        def expects_call_stack_jump?
+          true
+        end
+
       private
 
         def actual_result

data/lib/rspec/matchers/built_in/yield.rb

@@ -1,3 +1,5 @@
+RSpec::Support.require_rspec_support "method_signature_verifier"
+
 module RSpec
   module Matchers
     module BuiltIn
@@ -68,10 +70,22 @@ module RSpec
                 "are."
         end
 
-        def assert_valid_expect_block!
-          return if @block.arity == 1
-          raise "Your expect block must accept an argument to be used with this " \
-                "matcher. Pass the argument as a block on to the method you are testing."
+        if RUBY_VERSION.to_f > 1.8
+          def assert_valid_expect_block!
+            block_signature = RSpec::Support::BlockSignature.new(@block)
+            return if RSpec::Support::StrictSignatureVerifier.new(block_signature, [self]).valid?
+            raise "Your expect block must accept an argument to be used with this " \
+                  "matcher. Pass the argument as a block on to the method you are testing."
+          end
+        else
+          # On 1.8.7, `lambda { }.arity` and `lambda { |*a| }.arity` both return -1,
+          # so we can't distinguish between accepting no args and an arg splat.
+          # It's OK to skip, this, though; it just provides a nice error message
+          # when the user forgets to accept an arg in their block. They'll still get
+          # the `assert_used!` error message from above, which is sufficient.
+          def assert_valid_expect_block!
+            # nothing to do
+          end
         end
       end
 
@@ -92,12 +106,19 @@ module RSpec
         end
 
         # @api public
-        # Specifies that the method is expected to yield once.
+        # Specifies that the method is expected to yield twice.
         def twice
           exactly(2)
           self
         end
 
+        # @api public
+        # Specifies that the method is expected to yield thrice.
+        def thrice
+          exactly(3)
+          self
+        end
+
         # @api public
         # Specifies that the method is expected to yield the given number of times.
         def exactly(number)
@@ -167,6 +188,7 @@ module RSpec
                                    when Numeric then n
                                    when :once then 1
                                    when :twice then 2
+                                   when :thrice then 3
                                    end
         end
 
@@ -241,9 +263,7 @@ module RSpec
       # @api private
       # Provides the implementation for `yield_with_args`.
       # Not intended to be instantiated directly.
-      class YieldWithArgs
-        include Composable
-
+      class YieldWithArgs < BaseMatcher
         def initialize(*args)
           @expected = args
         end
@@ -330,9 +350,7 @@ module RSpec
       # @api private
       # Provides the implementation for `yield_successive_args`.
       # Not intended to be instantiated directly.
-      class YieldSuccessiveArgs
-        include Composable
-
+      class YieldSuccessiveArgs < BaseMatcher
         def initialize(*args)
           @expected = args
         end

data/lib/rspec/matchers/dsl.rb

@@ -160,7 +160,10 @@ module RSpec
         # Convenience for defining methods on this matcher to create a fluent
         # interface. The trick about fluent interfaces is that each method must
         # return self in order to chain methods together. `chain` handles that
-        # for you.
+        # for you. If the method is invoked and the
+        # `include_chain_clauses_in_custom_matcher_descriptions` config option
+        # hash been enabled, the chained method name and args will be added to the
+        # default description and failure message.
         #
         # @example
         #
@@ -178,6 +181,7 @@ module RSpec
         def chain(name, &definition)
           define_user_override(name, definition) do |*args, &block|
             super(*args, &block)
+            @chained_method_clauses.push([name, args])
             self
           end
         end
@@ -249,17 +253,17 @@ module RSpec
 
         # The default description.
         def description
-          "#{name_to_sentence}#{to_sentence expected}"
+          "#{name_to_sentence}#{to_sentence expected}#{chained_method_clause_sentences}"
         end
 
         # The default failure message for positive expectations.
         def failure_message
-          "expected #{actual.inspect} to #{name_to_sentence}#{to_sentence expected}"
+          "expected #{actual.inspect} to #{description}"
         end
 
         # The default failure message for negative expectations.
         def failure_message_when_negated
-          "expected #{actual.inspect} not to #{name_to_sentence}#{to_sentence expected}"
+          "expected #{actual.inspect} not to #{description}"
         end
 
         # Matchers do not support block expectations by default. You
@@ -267,6 +271,21 @@ module RSpec
         def supports_block_expectations?
           false
         end
+
+        # Most matchers do not expect call stack jumps.
+        def expects_call_stack_jump?
+          false
+        end
+
+      private
+
+        def chained_method_clause_sentences
+          return '' unless Expectations.configuration.include_chain_clauses_in_custom_matcher_descriptions?
+
+          @chained_method_clauses.map do |(method_name, method_args)|
+            " #{split_words(method_name)}#{to_sentence(method_args)}"
+          end.join
+        end
       end
 
       # The class used for custom matchers. The block passed to
@@ -304,6 +323,7 @@ module RSpec
           @actual   = nil
           @expected_as_array = expected
           @matcher_execution_context = matcher_execution_context
+          @chained_method_clauses = []
 
           class << self
             # See `Macros#define_user_override` above, for an explanation.

data/lib/rspec/matchers/matcher_delegator.rb

@@ -3,6 +3,7 @@ module RSpec
     # Provides the necessary plumbing to wrap a matcher with a decorator.
     # @private
     class MatcherDelegator
+      include Composable
       attr_reader :base_matcher
 
       def initialize(base_matcher)
@@ -27,10 +28,6 @@ module RSpec
         @base_matcher = @base_matcher.clone
         super
       end
-
-      # So `===` is delegated via `method_missing`.
-      undef ===
-      undef ==
     end
   end
 end

data/lib/rspec/matchers/matcher_protocol.rb

@@ -0,0 +1,99 @@
+module RSpec
+  module Matchers
+    # rspec-expectations can work with any matcher object that implements this protocol.
+    #
+    # @note This class is not loaded at runtime by rspec-expectations. It exists
+    #   purely to provide documentation for the matcher protocol.
+    class MatcherProtocol
+      # @!group Required Methods
+
+      # @method matches?
+      # @param actual [Object] The object being matched against.
+      # @yield For an expression like `expect(x).to matcher do...end`, the `do/end`
+      #   block binds to `to`. It passes that block, if there is one, on to this method.
+      # @return [Boolean] true if this matcher matches the provided object.
+
+      # @method failure_message
+      # This will only be called if {#matches?} returns false.
+      # @return [String] Explanation for the failure.
+
+      # @!endgroup
+
+      # @!group Optional Methods
+
+      # @method does_not_match?
+      # In a negative expectation such as `expect(x).not_to foo`, RSpec will
+      # call `foo.does_not_match?(x)` if this method is defined. If it's not
+      # defined it will fall back to using `!foo.matches?(x)`. This allows you
+      # to provide custom logic for the negative case.
+      #
+      # @param actual [Object] The object being matched against.
+      # @yield For an expression like `expect(x).not_to matcher do...end`, the `do/end`
+      #   block binds to `not_to`. It passes that block, if there is one, on to this method.
+      # @return [Boolean] true if this matcher does not match the provided object.
+
+      # @method failure_message_when_negated
+      # This will only be called when a negative match fails.
+      # @return [String] Explanation for the failure.
+      # @note This method is listed as optional because matchers do not have to
+      #   support negation. But if your matcher does support negation, this is a
+      #   required method -- otherwise, you'll get a `NoMethodError`.
+
+      # @method description
+      # The description is used for two things:
+      #
+      #   * When using RSpec's one-liner syntax
+      #     (e.g. `it { is_expected.to matcher }`), the description
+      #     is used to generate the example's doc string since you
+      #     have not provided one.
+      #   * In a composed matcher expression, the description is used
+      #     as part of the failure message (and description) of the outer
+      #     matcher.
+      #
+      # @return [String] Description of the matcher.
+
+      # @method supports_block_expectations?
+      # Indicates that this matcher can be used in a block expectation expression,
+      # such as `expect { foo }.to raise_error`. Generally speaking, this is
+      # only needed for matchers which operate on a side effect of a block, rather
+      # than on a particular object.
+      # @return [Boolean] true if this matcher can be used in block expressions.
+      # @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @method expects_call_stack_jump?
+      # Indicates that when this matcher is used in a block expectation
+      # expression, it expects the block to use a ruby construct that causes
+      # a call stack jump (such as raising an error or throwing a symbol).
+      #
+      # This is used internally for compound block expressions, as matchers
+      # which expect call stack jumps must be treated with care to work properly.
+      #
+      # @return [Boolean] true if the matcher expects a call stack jump
+      #
+      # @note This method is very rarely used or needed.
+      # @note If not defined, RSpec assumes a value of `false` for this method.
+
+      # @method diffable?
+      # @return [Boolean] true if `actual` and `expected` can be diffed.
+      # Indicates that this matcher provides `actual` and `expected` attributes,
+      # and that the values returned by these can be usefully diffed, which can
+      # be included in the output.
+
+      # @method actual
+      # @return [String, Object] If an object (rather than a string) is provided,
+      #   RSpec will use the `pp` library to convert it to multi-line output in
+      #   order to diff.
+      # The actual value for the purposes of a diff.
+      # @note This method is required if `diffable?` returns true.
+
+      # @method expected
+      # @return [String, Object] If an object (rather than a string) is provided,
+      #   RSpec will use the `pp` library to convert it to multi-line output in
+      #   order to diff.
+      # The expected value for the purposes of a diff.
+      # @note This method is required if `diffable?` returns true.
+
+      # @!endgroup
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rspec-expectations
 version: !ruby/object:Gem::Version
-  version: 3.0.4
+  version: 3.1.0
 platform: ruby
 authors:
 - Steven Baker
@@ -33,7 +33,7 @@ cert_chain:
   1yHC1AcSYpvi2dAbOiHT5iQF+krm4wse8KctXgTNnjMsHEoGKulJS2/sZl90jcCz
   muA=
   -----END CERTIFICATE-----
-date: 2014-08-14 00:00:00.000000000 Z
+date: 2014-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec-support
@@ -41,14 +41,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.1.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: diff-lcs
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +164,7 @@ files:
 - lib/rspec/matchers/built_in/equal.rb
 - lib/rspec/matchers/built_in/exist.rb
 - lib/rspec/matchers/built_in/has.rb
+- lib/rspec/matchers/built_in/have_attributes.rb
 - lib/rspec/matchers/built_in/include.rb
 - lib/rspec/matchers/built_in/match.rb
 - lib/rspec/matchers/built_in/operators.rb
@@ -178,6 +179,7 @@ files:
 - lib/rspec/matchers/dsl.rb
 - lib/rspec/matchers/generated_descriptions.rb
 - lib/rspec/matchers/matcher_delegator.rb
+- lib/rspec/matchers/matcher_protocol.rb
 - lib/rspec/matchers/pretty.rb
 homepage: http://github.com/rspec/rspec-expectations
 licenses:
@@ -203,6 +205,6 @@ rubyforge_project: rspec
 rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
-summary: rspec-expectations-3.0.4
+summary: rspec-expectations-3.1.0
 test_files: []
 has_rdoc: