rspec-expectations 3.0.4 → 3.12.3

data/lib/rspec/matchers.rb

@@ -1,31 +1,24 @@
 require 'rspec/support'
+RSpec::Support.require_rspec_support 'matcher_definition'
 RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relative(f) }
 
 %w[
-  pretty
+  english_phrasing
   composable
   built_in
   generated_descriptions
   dsl
   matcher_delegator
   aliased_matcher
+  expecteds_for_multiple_diffs
 ].each { |file| RSpec::Support.require_rspec_matchers(file) }
 
 # RSpec's top level namespace. All of rspec-expectations is contained
 # 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
   #
@@ -43,14 +36,14 @@ module RSpec
   #     expect([]).to be_empty     # => [].empty?() | passes
   #     expect([]).not_to be_empty # => [].empty?() | fails
   #
-  # In addtion to prefixing the predicate matchers with "be_", you can also use "be_a_"
+  # In addition to prefixing the predicate matchers with "be_", you can also use "be_a_"
   # and "be_an_", making your specs read much more naturally:
   #
   #     expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
   #
-  #     expect(3).to be_a_kind_of(Fixnum)        # => 3.kind_of?(Numeric)     | passes
-  #     expect(3).to be_a_kind_of(Numeric)       # => 3.kind_of?(Numeric)     | passes
-  #     expect(3).to be_an_instance_of(Fixnum)   # => 3.instance_of?(Fixnum)  | passes
+  #     expect(3).to be_a_kind_of(Integer)          # => 3.kind_of?(Numeric)     | passes
+  #     expect(3).to be_a_kind_of(Numeric)          # => 3.kind_of?(Numeric)     | passes
+  #     expect(3).to be_an_instance_of(Integer)     # => 3.instance_of?(Integer) | passes
   #     expect(3).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
   #
   # RSpec will also create custom matchers for predicates like `has_key?`. To
@@ -69,6 +62,26 @@ module RSpec
   #     RSpec::Matchers.alias_matcher :a_user_who_is_an_admin, :be_an_admin
   #     expect(user_list).to include(a_user_who_is_an_admin)
   #
+  # ## Alias Matchers
+  #
+  # With {RSpec::Matchers.alias_matcher}, you can easily create an
+  # alternate name for a given matcher.
+  #
+  # The description will also change according to the new name:
+  #
+  #     RSpec::Matchers.alias_matcher :a_list_that_sums_to, :sum_to
+  #     sum_to(3).description # => "sum to 3"
+  #     a_list_that_sums_to(3).description # => "a list that sums to 3"
+  #
+  # or you can specify a custom description like this:
+  #
+  #     RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
+  #       description.sub("be sorted by", "a list sorted by")
+  #     end
+  #
+  #     be_sorted_by(:age).description # => "be sorted by age"
+  #     a_list_sorted_by(:age).description # => "a list sorted by age"
+  #
   # ## Custom Matchers
   #
   # When you find that none of the stock matchers provide a natural feeling
@@ -209,55 +222,88 @@ module RSpec
   # expressions, and also uses the noun-phrase wording in the matcher's `description`,
   # for readable failure messages. You can alias your custom matchers in similar fashion
   # using {RSpec::Matchers.alias_matcher}.
-  module Matchers
+  #
+  # ## Negated Matchers
+  #
+  # Sometimes if you want to test for the opposite using a more descriptive name
+  # instead of using `not_to`, you can use {RSpec::Matchers.define_negated_matcher}:
+  #
+  #     RSpec::Matchers.define_negated_matcher :exclude, :include
+  #     include(1, 2).description # => "include 1 and 2"
+  #     exclude(1, 2).description # => "exclude 1 and 2"
+  #
+  # While the most obvious negated form may be to add a `not_` prefix,
+  # the failure messages you get with that form can be confusing (e.g.
+  # "expected [actual] to not [verb], but did not"). We've found it works
+  # best to find a more positive name for the negated form, such as
+  # `avoid_changing` rather than `not_change`.
+  #
+  module Matchers # rubocop:disable Metrics/ModuleLength
+    extend ::RSpec::Matchers::DSL
+
+    # @!macro [attach] alias_matcher
+    #   @!parse
+    #     alias $1 $2
+    # @!visibility private
+    # We define this override here so we can attach a YARD macro to it.
+    # It ensures that our docs list all the matcher aliases.
+    def self.alias_matcher(*args, &block)
+      super(*args, &block)
+    end
+
+    # @!method self.alias_matcher(new_name, old_name, options={}, &description_override)
+    #   Extended from {RSpec::Matchers::DSL#alias_matcher}.
+
+    # @!method self.define(name, &declarations)
+    #   Extended from {RSpec::Matchers::DSL#define}.
+
+    # @!method self.define_negated_matcher(negated_name, base_name, &description_override)
+    #   Extended from {RSpec::Matchers::DSL#define_negated_matcher}.
+
     # @method expect
     # Supports `expect(actual).to matcher` syntax by wrapping `actual` in an
     # `ExpectationTarget`.
     # @example
     #   expect(actual).to eq(expected)
     #   expect(actual).not_to eq(expected)
-    # @return [ExpectationTarget]
-    # @see ExpectationTarget#to
-    # @see ExpectationTarget#not_to
+    # @return [Expectations::ExpectationTarget]
+    # @see Expectations::ExpectationTarget#to
+    # @see Expectations::ExpectationTarget#not_to
 
-    # Defines a matcher alias. The returned matcher's `description` will be overriden
-    # to reflect the phrasing of the new name, which will be used in failure messages
-    # when passed as an argument to another matcher in a composed matcher expression.
-    #
-    # @param new_name [Symbol] the new name for the matcher
-    # @param old_name [Symbol] the original name for the matcher
-    # @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.alias_matcher :a_list_that_sums_to, :sum_to
-    #   sum_to(3).description # => "sum to 3"
-    #   a_list_that_sums_to(3).description # => "a list that sums to 3"
+    # Allows multiple expectations in the provided block to fail, and then
+    # aggregates them into a single exception, rather than aborting on the
+    # first expectation failure like normal. This allows you to see all
+    # failures from an entire set of expectations without splitting each
+    # off into its own example (which may slow things down if the example
+    # setup is expensive).
+    #
+    # @param label [String] label for this aggregation block, which will be
+    #   included in the aggregated exception message.
+    # @param metadata [Hash] additional metadata about this failure aggregation
+    #   block. If multiple expectations fail, it will be exposed from the
+    #   {Expectations::MultipleExpectationsNotMetError} exception. Mostly
+    #   intended for internal RSpec use but you can use it as well.
+    # @yield Block containing as many expectation as you want. The block is
+    #   simply yielded to, so you can trust that anything that works outside
+    #   the block should work within it.
+    # @raise [Expectations::MultipleExpectationsNotMetError] raised when
+    #   multiple expectations fail.
+    # @raise [Expectations::ExpectationNotMetError] raised when a single
+    #   expectation fails.
+    # @raise [Exception] other sorts of exceptions will be raised as normal.
     #
     # @example
-    #
-    #   RSpec::Matchers.alias_matcher :a_list_sorted_by, :be_sorted_by do |description|
-    #     description.sub("be sorted by", "a list sorted by")
+    #   aggregate_failures("verifying response") do
+    #     expect(response.status).to eq(200)
+    #     expect(response.headers).to include("Content-Type" => "text/plain")
+    #     expect(response.body).to include("Success")
     #   end
     #
-    #   be_sorted_by(:age).description # => "be sorted by age"
-    #   a_list_sorted_by(:age).description # => "a list sorted by age"
-    #
-    # @!macro [attach] alias_matcher
-    #   @!parse
-    #     alias $1 $2
-    def self.alias_matcher(new_name, old_name, &description_override)
-      description_override ||= lambda do |old_desc|
-        old_desc.gsub(Pretty.split_words(old_name), Pretty.split_words(new_name))
-      end
-
-      define_method(new_name) do |*args, &block|
-        matcher = __send__(old_name, *args, &block)
-        AliasedMatcher.new(matcher, description_override)
-      end
+    # @note The implementation of this feature uses a thread-local variable,
+    #   which means that if you have an expectation failure in another thread,
+    #   it'll abort like normal.
+    def aggregate_failures(label=nil, metadata={}, &block)
+      Expectations::FailureAggregator.new(label, metadata).aggregate(&block)
     end
 
     # Passes if actual is truthy (anything but false or nil)
@@ -270,9 +316,9 @@ module RSpec
     def be_falsey
       BuiltIn::BeFalsey.new
     end
-    alias_matcher :be_falsy,       :be_falsey
+    alias_matcher :be_falsy, :be_falsey
     alias_matcher :a_falsey_value, :be_falsey
-    alias_matcher :a_falsy_value,  :be_falsey
+    alias_matcher :a_falsy_value, :be_falsey
 
     # Passes if actual is nil
     def be_nil
@@ -303,7 +349,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)
@@ -314,8 +360,7 @@ module RSpec
     # Passes if actual.instance_of?(expected)
     #
     # @example
-    #
-    #   expect(5).to     be_an_instance_of(Fixnum)
+    #   expect(5).to     be_an_instance_of(Integer)
     #   expect(5).not_to be_an_instance_of(Numeric)
     #   expect(5).not_to be_an_instance_of(Float)
     def be_an_instance_of(expected)
@@ -327,15 +372,14 @@ module RSpec
     # Passes if actual.kind_of?(expected)
     #
     # @example
-    #
-    #   expect(5).to     be_a_kind_of(Fixnum)
+    #   expect(5).to     be_a_kind_of(Integer)
     #   expect(5).to     be_a_kind_of(Numeric)
     #   expect(5).not_to be_a_kind_of(Float)
     def be_a_kind_of(expected)
       BuiltIn::BeAKindOf.new(expected)
     end
     alias_method :be_kind_of, :be_a_kind_of
-    alias_matcher :a_kind_of,  :be_a_kind_of
+    alias_matcher :a_kind_of, :be_a_kind_of
 
     # Passes if actual.between?(min, max). Works with any Comparable object,
     # including String, Symbol, Time, or Numeric (Fixnum, Bignum, Integer,
@@ -345,7 +389,6 @@ module RSpec
     # but you can make it `exclusive` by chaining that off the matcher.
     #
     # @example
-    #
     #   expect(5).to      be_between(1, 10)
     #   expect(11).not_to be_between(1, 10)
     #   expect(10).not_to be_between(1, 10).exclusive
@@ -357,14 +400,13 @@ module RSpec
     # Passes if actual == expected +/- delta
     #
     # @example
-    #
     #   expect(result).to     be_within(0.5).of(3.0)
     #   expect(result).not_to be_within(0.5).of(3.0)
     def be_within(delta)
       BuiltIn::BeWithin.new(delta)
     end
     alias_matcher :a_value_within, :be_within
-    alias_matcher :within,         :be_within
+    alias_matcher :within, :be_within
 
     # Applied to a proc, specifies that its execution will cause some value to
     # change.
@@ -382,14 +424,16 @@ 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
-    #
     #   expect {
     #     team.add_player(player)
     #   }.to change(roster, :count)
@@ -436,7 +480,10 @@ module RSpec
     # == Notes
     #
     # Evaluates `receiver.message` or `block` before and after it
-    # evaluates the block passed to `expect`.
+    # evaluates the block passed to `expect`. If the value is the same
+    # object, its before/after `hash` value is used to see if it has changed.
+    # Therefore, your object needs to properly implement `hash` to work correctly
+    # with this matcher.
     #
     # `expect( ... ).not_to change` supports the form that specifies `from`
     # (which specifies what you expect the starting, unchanged value to be)
@@ -445,8 +492,8 @@ module RSpec
     def change(receiver=nil, message=nil, &block)
       BuiltIn::Change.new(receiver, message, &block)
     end
-    alias_matcher :a_block_changing,  :change
-    alias_matcher :changing,          :change
+    alias_matcher :a_block_changing, :change
+    alias_matcher :changing, :change
 
     # Passes if actual contains all of the expected regardless of order.
     # This works for collections. Pass in multiple args and it will only
@@ -455,11 +502,7 @@ 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)
     #   expect([1, 2, 3]).to contain_exactly(1, 3, 2)
     #
@@ -468,7 +511,7 @@ module RSpec
       BuiltIn::ContainExactly.new(items)
     end
     alias_matcher :a_collection_containing_exactly, :contain_exactly
-    alias_matcher :containing_exactly,              :contain_exactly
+    alias_matcher :containing_exactly, :contain_exactly
 
     # Passes if actual covers expected. This works for
     # Ranges. You can also pass in multiple args
@@ -486,7 +529,7 @@ module RSpec
       BuiltIn::Cover.new(*values)
     end
     alias_matcher :a_range_covering, :cover
-    alias_matcher :covering,         :cover
+    alias_matcher :covering, :cover
 
     # Matches if the actual value ends with the expected value(s). In the case
     # of a string, matches against the last `expected.length` characters of the
@@ -494,7 +537,6 @@ module RSpec
     # `expected.length` elements of the actual array.
     #
     # @example
-    #
     #   expect("this string").to   end_with "string"
     #   expect([0, 1, 2, 3, 4]).to end_with 4
     #   expect([0, 2, 3, 4, 4]).to end_with 3, 4
@@ -502,8 +544,8 @@ module RSpec
       BuiltIn::EndWith.new(*expected)
     end
     alias_matcher :a_collection_ending_with, :end_with
-    alias_matcher :a_string_ending_with,     :end_with
-    alias_matcher :ending_with,              :end_with
+    alias_matcher :a_string_ending_with, :end_with
+    alias_matcher :ending_with, :end_with
 
     # Passes if <tt>actual == expected</tt>.
     #
@@ -511,14 +553,13 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #
     #   expect(5).to     eq(5)
     #   expect(5).not_to eq(3)
     def eq(expected)
       BuiltIn::Eq.new(expected)
     end
     alias_matcher :an_object_eq_to, :eq
-    alias_matcher :eq_to,           :eq
+    alias_matcher :eq_to, :eq
 
     # Passes if `actual.eql?(expected)`
     #
@@ -526,14 +567,13 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #
     #   expect(5).to     eql(5)
     #   expect(5).not_to eql(3)
     def eql(expected)
       BuiltIn::Eql.new(expected)
     end
     alias_matcher :an_object_eql_to, :eql
-    alias_matcher :eql_to,           :eql
+    alias_matcher :eql_to, :eql
 
     # Passes if <tt>actual.equal?(expected)</tt> (object identity).
     #
@@ -541,14 +581,13 @@ module RSpec
     # information about equality in Ruby.
     #
     # @example
-    #
-    #   expect(5).to       equal(5)   # Fixnums are equal
+    #   expect(5).to       equal(5)   # Integers are equal
     #   expect("5").not_to equal("5") # Strings that look the same are not the same object
     def equal(expected)
       BuiltIn::Equal.new(expected)
     end
     alias_matcher :an_object_equal_to, :equal
-    alias_matcher :equal_to,           :equal
+    alias_matcher :equal_to, :equal
 
     # Passes if `actual.exist?` or `actual.exists?`
     #
@@ -558,33 +597,57 @@ module RSpec
       BuiltIn::Exist.new(*args)
     end
     alias_matcher :an_object_existing, :exist
-    alias_matcher :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
+    alias_matcher :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.
     #
     # @example
-    #
     #   expect([1,2,3]).to      include(3)
     #   expect([1,2,3]).to      include(2,3)
     #   expect([1,2,3]).to      include(2,3,4) # fails
     #   expect([1,2,3]).not_to  include(4)
     #   expect("spread").to     include("read")
     #   expect("spread").not_to include("red")
+    #   expect(:a => 1, :b => 2).to include(:a)
+    #   expect(:a => 1, :b => 2).to include(:a, :b)
+    #   expect(:a => 1, :b => 2).to include(:a => 1)
+    #   expect(:a => 1, :b => 2).to include(:b => 2, :a => 1)
+    #   expect(:a => 1, :b => 2).to include(:c) # fails
+    #   expect(:a => 1, :b => 2).not_to include(:a => 2)
     def include(*expected)
       BuiltIn::Include.new(*expected)
     end
     alias_matcher :a_collection_including, :include
-    alias_matcher :a_string_including,     :include
-    alias_matcher :a_hash_including,       :include
-    alias_matcher :including,              :include
+    alias_matcher :a_string_including, :include
+    alias_matcher :a_hash_including, :include
+    alias_matcher :including, :include
 
-    # Passes if actual all expected objects pass. This works for
-    # any enumerable object.
+    # Passes if the provided matcher passes when checked against all
+    # elements of the collection.
     #
     # @example
-    #
     #   expect([1, 3, 5]).to all be_odd
     #   expect([1, 3, 6]).to all be_odd # fails
     #
@@ -606,12 +669,10 @@ module RSpec
     # pair of elements.
     #
     # @example
-    #
     #   expect(email).to match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
     #   expect(email).to match("@example.com")
     #
     # @example
-    #
     #   hash = {
     #     :a => {
     #       :b => ["foo", 5],
@@ -623,7 +684,7 @@ module RSpec
     #     :a => {
     #       :b => a_collection_containing_exactly(
     #         a_string_starting_with("f"),
-    #         an_instance_of(Fixnum)
+    #         an_instance_of(Integer)
     #       ),
     #       :c => { :d => (a_value < 3) }
     #     }
@@ -636,17 +697,16 @@ module RSpec
     def match(expected)
       BuiltIn::Match.new(expected)
     end
-    alias_matcher :match_regex,        :match
+    alias_matcher :match_regex, :match
     alias_matcher :an_object_matching, :match
-    alias_matcher :a_string_matching,  :match
-    alias_matcher :matching,           :match
+    alias_matcher :a_string_matching, :match
+    alias_matcher :matching, :match
 
     # An alternate form of `contain_exactly` that accepts
     # the expected contents as a single array arg rather
-    # that splatted out as individual items.
+    # than splatted out as individual items.
     #
     # @example
-    #
     #   expect(results).to contain_exactly(1, 2)
     #   # is identical to:
     #   expect(results).to match_array([1, 2])
@@ -655,13 +715,19 @@ module RSpec
     def match_array(items)
       contain_exactly(*items)
     end
+    alias_matcher :an_array_matching, :match_array do |desc|
+      desc.sub("contain exactly", "an array containing exactly")
+    end
 
     # With no arg, passes if the block outputs `to_stdout` or `to_stderr`.
-    # With a string, passes if the blocks outputs that specific string `to_stdout` or `to_stderr`.
-    # With a regexp or matcher, passes if the blocks outputs a string `to_stdout` or `to_stderr` that matches.
+    # With a string, passes if the block outputs that specific string `to_stdout` or `to_stderr`.
+    # With a regexp or matcher, passes if the block outputs a string `to_stdout` or `to_stderr` that matches.
     #
-    # @example
+    # To capture output from any spawned subprocess as well, use `to_stdout_from_any_process` or
+    # `to_stderr_from_any_process`. Output from any process that inherits the main process's corresponding
+    # standard stream will be captured.
     #
+    # @example
     #   expect { print 'foo' }.to output.to_stdout
     #   expect { print 'foo' }.to output('foo').to_stdout
     #   expect { print 'foo' }.to output(/foo/).to_stdout
@@ -674,10 +740,15 @@ module RSpec
     #
     #   expect { do_something }.to_not output.to_stderr
     #
-    # @note This matcher works by temporarily replacing `$stdout` or `$stderr`,
-    #   so it's not able to intercept stream output that explicitly uses `STDOUT`/`STDERR`
+    #   expect { system('echo foo') }.to output("foo\n").to_stdout_from_any_process
+    #   expect { system('echo foo', out: :err) }.to output("foo\n").to_stderr_from_any_process
+    #
+    # @note `to_stdout` and `to_stderr` work by temporarily replacing `$stdout` or `$stderr`,
+    #   so they're not able to intercept stream output that explicitly uses `STDOUT`/`STDERR`
     #   or that uses a reference to `$stdout`/`$stderr` that was stored before the
-    #   matcher is used.
+    #   matcher was used.
+    # @note `to_stdout_from_any_process` and `to_stderr_from_any_process` use Tempfiles, and
+    #   are thus significantly (~30x) slower than `to_stdout` and `to_stderr`.
     def output(expected=nil)
       BuiltIn::Output.new(expected)
     end
@@ -685,29 +756,30 @@ module RSpec
 
     # With no args, matches if any error is raised.
     # With a named error, matches only if that specific error is raised.
-    # With a named error and messsage specified as a String, matches only if both match.
-    # With a named error and messsage specified as a Regexp, matches only if both match.
+    # With a named error and message specified as a String, matches only if both match.
+    # With a named error and message specified as a Regexp, matches only if both match.
     # Pass an optional block to perform extra verifications on the exception matched
     #
     # @example
-    #
     #   expect { do_something_risky }.to raise_error
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError)
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError) { |error| expect(error.data).to eq 42 }
+    #   expect { do_something_risky }.to raise_error { |error| expect(error.data).to eq 42 }
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError, "that was too risky")
     #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError, /oo ri/)
+    #   expect { do_something_risky }.to raise_error("that was too risky")
     #
     #   expect { do_something_risky }.not_to raise_error
-    def raise_error(error=Exception, message=nil, &block)
+    def raise_error(error=BuiltIn::RaiseError::UndefinedValue, message=nil, &block)
       BuiltIn::RaiseError.new(error, message, &block)
     end
-    alias_method :raise_exception,  :raise_error
+    alias_method :raise_exception, :raise_error
 
-    alias_matcher :a_block_raising,  :raise_error do |desc|
+    alias_matcher :a_block_raising, :raise_error do |desc|
       desc.sub("raise", "a block raising")
     end
 
-    alias_matcher :raising,        :raise_error do |desc|
+    alias_matcher :raising, :raise_error do |desc|
       desc.sub("raise", "raising")
     end
 
@@ -715,14 +787,13 @@ module RSpec
     # provided. Names can be Strings or Symbols.
     #
     # @example
-    #
     #   expect("string").to respond_to(:length)
     #
     def respond_to(*names)
       BuiltIn::RespondTo.new(*names)
     end
     alias_matcher :an_object_responding_to, :respond_to
-    alias_matcher :responding_to,           :respond_to
+    alias_matcher :responding_to, :respond_to
 
     # Passes if the submitted block returns true. Yields target to the
     # block.
@@ -734,14 +805,16 @@ module RSpec
     # If you do find yourself in such a situation, you could always write
     # a custom matcher, which would likely make your specs more expressive.
     #
-    # @example
+    # @param description [String] optional description to be used for this matcher.
     #
+    # @example
     #   expect(5).to satisfy { |n| n > 3 }
-    def satisfy(&block)
-      BuiltIn::Satisfy.new(&block)
+    #   expect(5).to satisfy("be greater than 3") { |n| n > 3 }
+    def satisfy(description=nil, &block)
+      BuiltIn::Satisfy.new(description, &block)
     end
     alias_matcher :an_object_satisfying, :satisfy
-    alias_matcher :satisfying,           :satisfy
+    alias_matcher :satisfying, :satisfy
 
     # Matches if the actual value starts with the expected value(s). In the
     # case of a string, matches against the first `expected.length` characters
@@ -749,7 +822,6 @@ module RSpec
     # `expected.length` elements of the actual array.
     #
     # @example
-    #
     #   expect("this string").to   start_with "this s"
     #   expect([0, 1, 2, 3, 4]).to start_with 0
     #   expect([0, 2, 3, 4, 4]).to start_with 0, 1
@@ -757,8 +829,8 @@ module RSpec
       BuiltIn::StartWith.new(*expected)
     end
     alias_matcher :a_collection_starting_with, :start_with
-    alias_matcher :a_string_starting_with,     :start_with
-    alias_matcher :starting_with,              :start_with
+    alias_matcher :a_string_starting_with, :start_with
+    alias_matcher :starting_with, :start_with
 
     # Given no argument, matches if a proc throws any Symbol.
     #
@@ -768,7 +840,6 @@ module RSpec
     # specified Symbol with the specified arg.
     #
     # @example
-    #
     #   expect { do_something_risky }.to throw_symbol
     #   expect { do_something_risky }.to throw_symbol(:that_was_risky)
     #   expect { do_something_risky }.to throw_symbol(:that_was_risky, 'culprit')
@@ -784,7 +855,7 @@ module RSpec
       desc.sub("throw", "a block throwing")
     end
 
-    alias_matcher :throwing,        :throw_symbol do |desc|
+    alias_matcher :throwing, :throw_symbol do |desc|
       desc.sub("throw", "throwing")
     end
 
@@ -792,25 +863,21 @@ module RSpec
     # of whether or not arguments are yielded.
     #
     # @example
-    #
     #   expect { |b| 5.tap(&b) }.to yield_control
     #   expect { |b| "a".to_sym(&b) }.not_to yield_control
     #
     # @note Your expect block must accept a parameter and pass it on to
     #   the method-under-test as a block.
-    # @note This matcher is not designed for use with methods that yield
-    #   multiple times.
     def yield_control
       BuiltIn::YieldControl.new
     end
-    alias_matcher :a_block_yielding_control,  :yield_control
-    alias_matcher :yielding_control,          :yield_control
+    alias_matcher :a_block_yielding_control, :yield_control
+    alias_matcher :yielding_control, :yield_control
 
     # Passes if the method called in the expect block yields with
     # no arguments. Fails if it does not yield, or yields with arguments.
     #
     # @example
-    #
     #   expect { |b| User.transaction(&b) }.to yield_with_no_args
     #   expect { |b| 5.tap(&b) }.not_to yield_with_no_args # because it yields with `5`
     #   expect { |b| "a".to_sym(&b) }.not_to yield_with_no_args # because it does not yield
@@ -822,8 +889,8 @@ module RSpec
     def yield_with_no_args
       BuiltIn::YieldWithNoArgs.new
     end
-    alias_matcher :a_block_yielding_with_no_args,  :yield_with_no_args
-    alias_matcher :yielding_with_no_args,          :yield_with_no_args
+    alias_matcher :a_block_yielding_with_no_args, :yield_with_no_args
+    alias_matcher :yielding_with_no_args, :yield_with_no_args
 
     # Given no arguments, matches if the method called in the expect
     # block yields with arguments (regardless of what they are or how
@@ -837,10 +904,9 @@ module RSpec
     # operator, the matcher will pass.
     #
     # @example
-    #
     #   expect { |b| 5.tap(&b) }.to yield_with_args # because #tap yields an arg
     #   expect { |b| 5.tap(&b) }.to yield_with_args(5) # because 5 == 5
-    #   expect { |b| 5.tap(&b) }.to yield_with_args(Fixnum) # because Fixnum === 5
+    #   expect { |b| 5.tap(&b) }.to yield_with_args(Integer) # because Integer === 5
     #   expect { |b| File.open("f.txt", &b) }.to yield_with_args(/txt/) # because /txt/ === "f.txt"
     #
     #   expect { |b| User.transaction(&b) }.not_to yield_with_args # because it yields no args
@@ -853,8 +919,8 @@ module RSpec
     def yield_with_args(*args)
       BuiltIn::YieldWithArgs.new(*args)
     end
-    alias_matcher :a_block_yielding_with_args,  :yield_with_args
-    alias_matcher :yielding_with_args,          :yield_with_args
+    alias_matcher :a_block_yielding_with_args, :yield_with_args
+    alias_matcher :yielding_with_args, :yield_with_args
 
     # Designed for use with methods that repeatedly yield (such as
     # iterators). Passes if the method called in the expect block yields
@@ -865,7 +931,6 @@ module RSpec
     # operator, the matcher will pass.
     #
     # @example
-    #
     #   expect { |b| [1, 2, 3].each(&b) }.to yield_successive_args(1, 2, 3)
     #   expect { |b| { :a => 1, :b => 2 }.each(&b) }.to yield_successive_args([:a, 1], [:b, 2])
     #   expect { |b| [1, 2, 3].each(&b) }.not_to yield_successive_args(1, 2)
@@ -875,8 +940,8 @@ module RSpec
     def yield_successive_args(*args)
       BuiltIn::YieldSuccessiveArgs.new(*args)
     end
-    alias_matcher :a_block_yielding_successive_args,  :yield_successive_args
-    alias_matcher :yielding_successive_args,          :yield_successive_args
+    alias_matcher :a_block_yielding_successive_args, :yield_successive_args
+    alias_matcher :yielding_successive_args, :yield_successive_args
 
     # Delegates to {RSpec::Expectations.configuration}.
     # This is here because rspec-core's `expect_with` option
@@ -889,8 +954,9 @@ module RSpec
 
   private
 
-    BE_PREDICATE_REGEX = /^(be_(?:an?_)?)(.*)/
+    BE_PREDICATE_REGEX = /^(?:be_(?:an?_)?)(.*)/
     HAS_REGEX = /^(?:have_)(.*)/
+    DYNAMIC_MATCHER_REGEX = Regexp.union(BE_PREDICATE_REGEX, HAS_REGEX)
 
     def method_missing(method, *args, &block)
       case method.to_s
@@ -902,20 +968,77 @@ module RSpec
         super
       end
     end
+    ruby2_keywords :method_missing if respond_to?(:ruby2_keywords, true)
+
+    if RUBY_VERSION.to_f >= 1.9
+      def respond_to_missing?(method, *)
+        method =~ DYNAMIC_MATCHER_REGEX || super
+      end
+    else # for 1.8.7
+      # :nocov:
+      def respond_to?(method, *)
+        method = method.to_s
+        method =~ DYNAMIC_MATCHER_REGEX || super
+      end
+      public :respond_to?
+      # :nocov:
+    end
 
     # @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)
     end
+
+    class << self
+      private
+
+      if RSpec::Support::Ruby.mri? && RUBY_VERSION[0, 3] == '1.9'
+        # Note that `included` doesn't work for this because it is triggered
+        # _after_ `RSpec::Matchers` is an ancestor of the inclusion host, rather
+        # than _before_, like `append_features`. It's important we check this before
+        # in order to find the cases where it was already previously included.
+        # @api private
+        def append_features(mod)
+          return super if mod < self # `mod < self` indicates a re-inclusion.
+
+          subclasses = ObjectSpace.each_object(Class).select { |c| c < mod && c < self }
+          return super unless subclasses.any?
+
+          subclasses.reject! { |s| subclasses.any? { |s2| s < s2 } } # Filter to the root ancestor.
+          subclasses = subclasses.map { |s| "`#{s}`" }.join(", ")
+
+          RSpec.warning "`#{self}` has been included in a superclass (`#{mod}`) " \
+                        "after previously being included in subclasses (#{subclasses}), " \
+                        "which can trigger infinite recursion from `super` due to an MRI 1.9 bug " \
+                        "(https://redmine.ruby-lang.org/issues/3351). To work around this, " \
+                        "either upgrade to MRI 2.0+, include a dup of the module (e.g. " \
+                        "`include #{self}.dup`), or find a way to include `#{self}` in `#{mod}` " \
+                        "before it is included in subclasses (#{subclasses}). See " \
+                        "https://github.com/rspec/rspec-expectations/issues/814 for more info"
+
+          super
+        end
+      end
+    end
   end
 end