rspec-expectations 2.13.0 → 3.0.0

data/lib/rspec/matchers.rb

@@ -1,15 +1,31 @@
+require 'rspec/support'
+RSpec::Support.define_optimized_require_for_rspec(:matchers) { |f| require_relative(f) }
+
+%w[
+  pretty
+  composable
+  built_in
+  generated_descriptions
+  dsl
+  matcher_delegator
+  aliased_matcher
+].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 compose
+  # 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_for_should
+  #     failure_message
   #
   # These methods are also part of the matcher protocol, but are optional:
   #
   #     does_not_match?(actual)
-  #     failure_message_for_should_not
+  #     failure_message_when_negated
   #     description
+  #     supports_block_expectations?
   #
   # ## Predicates
   #
@@ -20,32 +36,39 @@ module RSpec
   # A Ruby predicate is a method that ends with a "?" and returns true or false.
   # Common examples are `empty?`, `nil?`, and `instance_of?`.
   #
-  # All you need to do is write `should be_` followed by the predicate without
-  # the question mark, and RSpec will figure it out from there. For example:
+  # All you need to do is write `expect(..).to be_` followed by the predicate
+  # without the question mark, and RSpec will figure it out from there.
+  # For example:
   #
-  #     [].should be_empty     # => [].empty?() | passes
-  #     [].should_not be_empty # => [].empty?() | fails
+  #     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_"
   # and "be_an_", making your specs read much more naturally:
   #
-  #     "a string".should be_an_instance_of(String) =>"a string".instance_of?(String) #passes
+  #     expect("a string").to be_an_instance_of(String) # =>"a string".instance_of?(String) # passes
   #
-  #     3.should be_a_kind_of(Fixnum)        # => 3.kind_of?(Numeric)     | passes
-  #     3.should be_a_kind_of(Numeric)       # => 3.kind_of?(Numeric)     | passes
-  #     3.should be_an_instance_of(Fixnum)   # => 3.instance_of?(Fixnum)  | passes
-  #     3.should_not be_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
+  #     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).not_to be_an_instance_of(Numeric) # => 3.instance_of?(Numeric) | fails
   #
   # RSpec will also create custom matchers for predicates like `has_key?`. To
   # use this feature, just state that the object should have_key(:key) and RSpec will
   # call has_key?(:key) on the target. For example:
   #
-  #     {:a => "A"}.should have_key(:a) # => {:a => "A"}.has_key?(:a) | passes
-  #     {:a => "A"}.should have_key(:b) # => {:a => "A"}.has_key?(:b) | fails
+  #     expect(:a => "A").to have_key(:a)
+  #     expect(:a => "A").to have_key(:b) # fails
   #
   # You can use this feature to invoke any predicate that begins with "has_", whether it is
   # part of the Ruby libraries (like `Hash#has_key?`) or a method you wrote on your own class.
   #
+  # Note that RSpec does not provide composable aliases for these dynamic predicate
+  # matchers. You can easily define your own aliases, though:
+  #
+  #     RSpec::Matchers.alias_matcher :a_user_who_is_an_admin, :be_an_admin
+  #     expect(user_list).to include(a_user_who_is_an_admin)
+  #
   # ## Custom Matchers
   #
   # When you find that none of the stock matchers provide a natural feeling
@@ -58,15 +81,15 @@ module RSpec
   # zones on a virtual board. To specify that bob should be in zone 4, you
   # could say:
   #
-  #     bob.current_zone.should eql(Zone.new("4"))
+  #     expect(bob.current_zone).to eql(Zone.new("4"))
   #
   # But you might find it more expressive to say:
   #
-  #     bob.should be_in_zone("4")
+  #     expect(bob).to be_in_zone("4")
   #
   # and/or
   #
-  #     bob.should_not be_in_zone("3")
+  #     expect(bob).not_to be_in_zone("3")
   #
   # You can create such a matcher like so:
   #
@@ -85,11 +108,11 @@ module RSpec
   #         player.in_zone?(zone)
   #       end
   #
-  #       failure_message_for_should do |player|
+  #       failure_message do |player|
   #         # generate and return the appropriate string.
   #       end
   #
-  #       failure_message_for_should_not do |player|
+  #       failure_message_when_negated do |player|
   #         # generate and return the appropriate string.
   #       end
   #
@@ -100,9 +123,9 @@ module RSpec
   #
   # Each of the message-generation methods has access to the block arguments
   # passed to the <tt>create</tt> method (in this case, <tt>zone</tt>). The
-  # failure message methods (<tt>failure_message_for_should</tt> and
-  # <tt>failure_message_for_should_not</tt>) are passed the actual value (the
-  # receiver of <tt>should</tt> or <tt>should_not</tt>).
+  # failure message methods (<tt>failure_message</tt> and
+  # <tt>failure_message_when_negated</tt>) are passed the actual value (the
+  # receiver of <tt>expect(..)</tt> or <tt>expect(..).not_to</tt>).
   #
   # ### Custom Matcher from scratch
   #
@@ -118,11 +141,11 @@ module RSpec
   #         @target.current_zone.eql?(Zone.new(@expected))
   #       end
   #
-  #       def failure_message_for_should
+  #       def failure_message
   #         "expected #{@target.inspect} to be in Zone #{@expected}"
   #       end
   #
-  #       def failure_message_for_should_not
+  #       def failure_message_when_negated
   #         "expected #{@target.inspect} not to be in Zone #{@expected}"
   #       end
   #     end
@@ -158,59 +181,112 @@ module RSpec
   #     RSpec::configure do |config|
   #       config.include(CustomGameMatchers)
   #     end
+  #
+  # ### Making custom matchers composable
+  #
+  # RSpec's built-in matchers are designed to be composed, in expressions like:
+  #
+  #     expect(["barn", 2.45]).to contain_exactly(
+  #       a_value_within(0.1).of(2.5),
+  #       a_string_starting_with("bar")
+  #     )
+  #
+  # Custom matchers can easily participate in composed matcher expressions like these.
+  # Include {RSpec::Matchers::Composable} in your custom matcher to make it support
+  # being composed (matchers defined using the DSL have this included automatically).
+  # Within your matcher's `matches?` method (or the `match` block, if using the DSL),
+  # use `values_match?(expected, actual)` rather than `expected == actual`.
+  # Under the covers, `values_match?` is able to match arbitrary
+  # nested data structures containing a mix of both matchers and non-matcher objects.
+  # It uses `===` and `==` to perform the matching, considering the values to
+  # match if either returns `true`. The `Composable` mixin also provides some helper
+  # methods for surfacing the matcher descriptions within your matcher's description
+  # or failure messages.
+  #
+  # RSpec's built-in matchers each have a number of aliases that rephrase the matcher
+  # from a verb phrase (such as `be_within`) to a noun phrase (such as `a_value_within`),
+  # which reads better when the matcher is passed as an argument in a composed matcher
+  # 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
-    # Include Matchers for other test frameworks.  Note that MiniTest _must_
-    # come before TU because on ruby 1.9, T::U::TC is a subclass of MT::U::TC
-    # and a 1.9 bug can lead to infinite recursion from the `super` call in our
-    # method_missing hook.  See this gist for more info:
-    # https://gist.github.com/845896
-    if defined?(MiniTest::Unit::TestCase)
-      MiniTest::Unit::TestCase.send(:include, self)
-    end
-    if defined?(Test::Unit::TestCase)
-      Test::Unit::TestCase.send(:include, self)
+    # @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
+
+    # 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"
+    #
+    # @example
+    #
+    #   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"
+    #
+    # @!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
     end
-  end
-end
-
-require 'rspec/matchers/extensions/instance_eval_with_args'
-require 'rspec/matchers/pretty'
-
-require 'rspec/matchers/built_in'
-require 'rspec/matchers/matcher'
-require 'rspec/matchers/operator_matcher'
-require 'rspec/matchers/be_close'
-
-require 'rspec/matchers/generated_descriptions'
-require 'rspec/matchers/method_missing'
-require 'rspec/matchers/compatibility'
-require 'rspec/matchers/dsl'
-
-module RSpec
-  module Matchers
 
     # Passes if actual is truthy (anything but false or nil)
-    def be_true
-      BuiltIn::BeTrue.new
+    def be_truthy
+      BuiltIn::BeTruthy.new
     end
+    alias_matcher :a_truthy_value, :be_truthy
 
-    # Passes if actual is falsy (false or nil)
-    def be_false
-      BuiltIn::BeFalse.new
+    # Passes if actual is falsey (false or nil)
+    def be_falsey
+      BuiltIn::BeFalsey.new
     end
+    alias_matcher :be_falsy,       :be_falsey
+    alias_matcher :a_falsey_value, :be_falsey
+    alias_matcher :a_falsy_value,  :be_falsey
 
     # Passes if actual is nil
     def be_nil
       BuiltIn::BeNil.new
     end
+    alias_matcher :a_nil_value, :be_nil
 
     # @example
-    #   actual.should be_true
-    #   actual.should be_false
-    #   actual.should be_nil
-    #   actual.should be_[arbitrary_predicate](*args)
-    #   actual.should_not be_nil
-    #   actual.should_not be_[arbitrary_predicate](*args)
+    #   expect(actual).to     be_truthy
+    #   expect(actual).to     be_falsey
+    #   expect(actual).to     be_nil
+    #   expect(actual).to     be_[arbitrary_predicate](*args)
+    #   expect(actual).not_to be_nil
+    #   expect(actual).not_to be_[arbitrary_predicate](*args)
     #
     # Given true, false, or nil, will pass if actual value is true, false or
     # nil (respectively). Given no args means the caller should satisfy an if
@@ -228,49 +304,68 @@ module RSpec
       args.empty? ?
         Matchers::BuiltIn::Be.new : equal(*args)
     end
+    alias_matcher :a_value, :be
 
     # passes if target.kind_of?(klass)
     def be_a(klass)
       be_a_kind_of(klass)
     end
-
     alias_method :be_an, :be_a
 
     # Passes if actual.instance_of?(expected)
     #
     # @example
     #
-    #   5.should be_instance_of(Fixnum)
-    #   5.should_not be_instance_of(Numeric)
-    #   5.should_not be_instance_of(Float)
+    #   expect(5).to     be_an_instance_of(Fixnum)
+    #   expect(5).not_to be_an_instance_of(Numeric)
+    #   expect(5).not_to be_an_instance_of(Float)
     def be_an_instance_of(expected)
       BuiltIn::BeAnInstanceOf.new(expected)
     end
-
-    alias_method :be_instance_of, :be_an_instance_of
+    alias_method  :be_instance_of, :be_an_instance_of
+    alias_matcher :an_instance_of, :be_an_instance_of
 
     # Passes if actual.kind_of?(expected)
     #
     # @example
     #
-    #   5.should be_kind_of(Fixnum)
-    #   5.should be_kind_of(Numeric)
-    #   5.should_not be_kind_of(Float)
+    #   expect(5).to     be_a_kind_of(Fixnum)
+    #   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_method :be_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,
+    # Float, Complex, and Rational).
+    #
+    # By default, `be_between` is inclusive (i.e. passes when given either the max or min value),
+    # 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
+    def be_between(min, max)
+      BuiltIn::BeBetween.new(min, max)
+    end
+    alias_matcher :a_value_between, :be_between
 
     # Passes if actual == expected +/- delta
     #
     # @example
     #
-    #   result.should be_within(0.5).of(3.0)
-    #   result.should_not be_within(0.5).of(3.0)
+    #   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
 
     # Applied to a proc, specifies that its execution will cause some value to
     # change.
@@ -281,78 +376,118 @@ module RSpec
     # You can either pass <tt>receiver</tt> and <tt>message</tt>, or a block,
     # but not both.
     #
-    # When passing a block, it must use the <tt>{ ... }</tt> format, not
-    # do/end, as <tt>{ ... }</tt> binds to the +change+ method, whereas do/end
-    # would errantly bind to the +should+ or +should_not+ method.
+    # When passing a block, it must use the `{ ... }` format, not
+    # do/end, as `{ ... }` binds to the `change` method, whereas do/end
+    # would errantly bind to the `expect(..).to` or `expect(...).not_to` method.
+    #
+    # You can chain any of the following off of the end to specify details
+    # about the change:
+    #
+    # * `by`
+    # * `by_at_least`
+    # * `by_at_most`
+    # * `from`
+    # * `to`
     #
     # @example
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count)
+    #   }.to change(roster, :count)
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count).by(1)
+    #   }.to change(roster, :count).by(1)
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count).by_at_least(1)
+    #   }.to change(roster, :count).by_at_least(1)
     #
-    #   lambda {
+    #   expect {
     #     team.add_player(player)
-    #   }.should change(roster, :count).by_at_most(1)
+    #   }.to change(roster, :count).by_at_most(1)
     #
     #   string = "string"
-    #   lambda {
+    #   expect {
     #     string.reverse!
-    #   }.should change { string }.from("string").to("gnirts")
+    #   }.to change { string }.from("string").to("gnirts")
     #
-    #   lambda {
+    #   string = "string"
+    #   expect {
+    #     string
+    #   }.not_to change { string }.from("string")
+    #
+    #   expect {
     #     person.happy_birthday
-    #   }.should change(person, :birthday).from(32).to(33)
+    #   }.to change(person, :birthday).from(32).to(33)
     #
-    #   lambda {
+    #   expect {
     #     employee.develop_great_new_social_networking_app
-    #   }.should change(employee, :title).from("Mail Clerk").to("CEO")
+    #   }.to change(employee, :title).from("Mail Clerk").to("CEO")
     #
-    #   lambda {
+    #   expect {
     #     doctor.leave_office
-    #   }.should change(doctor, :sign).from(/is in/).to(/is out/)
+    #   }.to change(doctor, :sign).from(/is in/).to(/is out/)
     #
     #   user = User.new(:type => "admin")
-    #   lambda {
+    #   expect {
     #     user.symbolize_type
-    #   }.should change(user, :type).from(String).to(Symbol)
+    #   }.to change(user, :type).from(String).to(Symbol)
     #
     # == Notes
     #
-    # Evaluates <tt>receiver.message</tt> or <tt>block</tt> before and after it
-    # evaluates the proc object (generated by the lambdas in the examples
-    # above).
+    # Evaluates `receiver.message` or `block` before and after it
+    # evaluates the block passed to `expect`.
     #
-    # <tt>should_not change</tt> only supports the form with no subsequent
-    # calls to <tt>by</tt>, <tt>by_at_least</tt>, <tt>by_at_most</tt>,
-    # <tt>to</tt> or <tt>from</tt>.
+    # `expect( ... ).not_to change` supports the form that specifies `from`
+    # (which specifies what you expect the starting, unchanged value to be)
+    # but does not support forms with subsequent calls to `by`, `by_at_least`,
+    # `by_at_most` or `to`.
     def change(receiver=nil, message=nil, &block)
       BuiltIn::Change.new(receiver, message, &block)
     end
+    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
+    # pass if all args are found in collection.
+    #
+    # @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)
+    #
+    # @see #match_array
+    def contain_exactly(*items)
+      BuiltIn::ContainExactly.new(items)
+    end
+    alias_matcher :a_collection_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
     # and it will only pass if all args are found in Range.
     #
     # @example
-    #   (1..10).should cover(5)
-    #   (1..10).should cover(4, 6)
-    #   (1..10).should cover(4, 6, 11) # will fail
-    #   (1..10).should_not cover(11)
-    #   (1..10).should_not cover(5)    # will fail
+    #   expect(1..10).to     cover(5)
+    #   expect(1..10).to     cover(4, 6)
+    #   expect(1..10).to     cover(4, 6, 11) # fails
+    #   expect(1..10).not_to cover(11)
+    #   expect(1..10).not_to cover(5)        # fails
     #
     # ### Warning:: Ruby >= 1.9 only
     def cover(*values)
       BuiltIn::Cover.new(*values)
-    end if (1..2).respond_to?(:cover?)
+    end
+    alias_matcher :a_range_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
@@ -361,149 +496,193 @@ module RSpec
     #
     # @example
     #
-    #   "this string".should end_with "string"
-    #   [0, 1, 2, 3, 4].should end_with 4
-    #   [0, 2, 3, 4, 4].should end_with 3, 4
+    #   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
     def end_with(*expected)
       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
 
     # Passes if <tt>actual == expected</tt>.
     #
-    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+    # information about equality in Ruby.
     #
     # @example
     #
-    #   5.should eq(5)
-    #   5.should_not eq(3)
+    #   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
 
-    # Passes if +actual.eql?(expected)+
+    # Passes if `actual.eql?(expected)`
     #
-    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+    # information about equality in Ruby.
     #
     # @example
     #
-    #   5.should eql(5)
-    #   5.should_not eql(3)
+    #   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
 
     # Passes if <tt>actual.equal?(expected)</tt> (object identity).
     #
-    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more information about equality in Ruby.
+    # See http://www.ruby-doc.org/core/classes/Object.html#M001057 for more
+    # information about equality in Ruby.
     #
     # @example
     #
-    #   5.should equal(5) # Fixnums are equal
-    #   "5".should_not equal("5") # Strings that look the same are not the same object
+    #   expect(5).to       equal(5)   # Fixnums 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
 
     # Passes if `actual.exist?` or `actual.exists?`
     #
     # @example
-    #   File.should exist("path/to/file")
+    #   expect(File).to exist("path/to/file")
     def exist(*args)
       BuiltIn::Exist.new(*args)
     end
+    alias_matcher :an_object_existing, :exist
+    alias_matcher :existing,           :exist
 
-    # Passes if receiver is a collection with the submitted number of items OR
-    # if the receiver OWNS a collection with the submitted number of items.
-    #
-    # If the receiver OWNS the collection, you must use the name of the
-    # collection. So if a `Team` instance has a collection named `#players`,
-    # you must use that name to set the expectation.
+    # 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.
     #
-    # If the receiver IS the collection, you can use any name you like for
-    # `named_collection`. We'd recommend using either "elements", "members", or
-    # "items" as these are all standard ways of describing the things IN a
-    # collection.
+    # @example
     #
-    # This also works for Strings, letting you set expectations about their
-    # lengths.
+    #   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")
+    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
+
+    # Passes if actual all expected objects pass. This works for
+    # any enumerable object.
     #
     # @example
     #
-    #   # Passes if team.players.size == 11
-    #   team.should have(11).players
+    #   expect([1, 3, 5]).to all be_odd
+    #   expect([1, 3, 6]).to all be_odd # fails
     #
-    #   # Passes if [1,2,3].length == 3
-    #   [1,2,3].should have(3).items #"items" is pure sugar
+    # @note The negative form `not_to all` is not supported. Instead
+    #   use `not_to include` or pass a negative form of a matcher
+    #   as the argument (e.g. `all exclude(:foo)`).
     #
-    #   # Passes if ['a', 'b', 'c'].count == 3
-    #   [1,2,3].should have(3).items #"items" is pure sugar
+    # @note You can also use this with compound matchers as well.
     #
-    #   # Passes if "this string".length == 11
-    #   "this string".should have(11).characters #"characters" is pure sugar
-    def have(n)
-      BuiltIn::Have.new(n)
+    # @example
+    #   expect([1, 3, 5]).to all( be_odd.and be_an(Integer) )
+    def all(expected)
+      BuiltIn::All.new(expected)
     end
-    alias :have_exactly :have
 
-    # Exactly like have() with >=.
+    # Given a `Regexp` or `String`, passes if `actual.match(pattern)`
+    # Given an arbitrary nested data structure (e.g. arrays and hashes),
+    # matches if `expected === actual` || `actual == expected` for each
+    # pair of elements.
     #
     # @example
-    #   "this".should have_at_least(3).letters
-    #
-    # ### Warning:
     #
-    # `should_not have_at_least` is not supported
-    def have_at_least(n)
-      BuiltIn::Have.new(n, :at_least)
-    end
-
-    # Exactly like have() with <=.
+    #   expect(email).to match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
+    #   expect(email).to match("@example.com")
     #
     # @example
-    #   should have_at_most(number).items
     #
-    # ### Warning:
+    #   hash = {
+    #     :a => {
+    #       :b => ["foo", 5],
+    #       :c => { :d => 2.05 }
+    #     }
+    #   }
     #
-    # `should_not have_at_most` is not supported
-    def have_at_most(n)
-      BuiltIn::Have.new(n, :at_most)
+    #   expect(hash).to match(
+    #     :a => {
+    #       :b => a_collection_containing_exactly(
+    #         a_string_starting_with("f"),
+    #         an_instance_of(Fixnum)
+    #       ),
+    #       :c => { :d => (a_value < 3) }
+    #     }
+    #   )
+    #
+    # @note The `match_regex` alias is deprecated and is not recommended for use.
+    #       It was added in 2.12.1 to facilitate its use from within custom
+    #       matchers (due to how the custom matcher DSL was evaluated in 2.x,
+    #       `match` could not be used there), but is no longer needed in 3.x.
+    def match(expected)
+      BuiltIn::Match.new(expected)
     end
+    alias_matcher :match_regex,        :match
+    alias_matcher :an_object_matching, :match
+    alias_matcher :a_string_matching,  :match
+    alias_matcher :matching,           :match
 
-    # 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.
+    # An alternate form of `contain_exactly` that accepts
+    # the expected contents as a single array arg rather
+    # that splatted out as individual items.
     #
     # @example
     #
-    #   [1,2,3].should include(3)
-    #   [1,2,3].should include(2,3) #would pass
-    #   [1,2,3].should include(2,3,4) #would fail
-    #   [1,2,3].should_not include(4)
-    #   "spread".should include("read")
-    #   "spread".should_not include("red")
-    def include(*expected)
-      BuiltIn::Include.new(*expected)
+    #   expect(results).to contain_exactly(1, 2)
+    #   # is identical to:
+    #   expect(results).to match_array([1, 2])
+    #
+    # @see #contain_exactly
+    def match_array(items)
+      contain_exactly(*items)
     end
 
-    # Given a Regexp or String, passes if actual.match(pattern)
+    # 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.
     #
     # @example
     #
-    #   email.should match(/^([^\s]+)((?:[-a-z0-9]+\.)+[a-z]{2,})$/i)
-    #   email.should match("@example.com")
-    #   zipcode.should match_regex(/\A\d{5}(-\d{4})?\z/)
-    #   zipcode.should match_regex("90210")
+    #   expect { print 'foo' }.to output.to_stdout
+    #   expect { print 'foo' }.to output('foo').to_stdout
+    #   expect { print 'foo' }.to output(/foo/).to_stdout
     #
-    # @note Due to Ruby's method dispatch mechanism, using the `#match` matcher
-    # within a custom matcher defined via the matcher DSL
-    # (`RSpec::Matcher.define`) will result Ruby calling the wrong `#match`
-    # method and raising an `ArgumentError`. Instead, use the aliased
-    # `#match_regex` method.
-    def match(expected)
-      BuiltIn::Match.new(expected)
+    #   expect { do_something }.to_not output.to_stdout
+    #
+    #   expect { warn('foo') }.to output.to_stderr
+    #   expect { warn('foo') }.to output('foo').to_stderr
+    #   expect { warn('foo') }.to output(/foo/).to_stderr
+    #
+    #   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`
+    #   or that uses a reference to `$stdout`/`$stderr` that was stored before the
+    #   matcher is used.
+    def output(expected=nil)
+      BuiltIn::Output.new(expected)
     end
-
-    alias_method :match_regex, :match
+    alias_matcher :a_block_outputting, :output
 
     # With no args, matches if any error is raised.
     # With a named error, matches only if that specific error is raised.
@@ -513,30 +692,38 @@ module RSpec
     #
     # @example
     #
-    #   lambda { do_something_risky }.should raise_error
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError)
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError) { |error| error.data.should == 42 }
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, "that was too risky")
-    #   lambda { do_something_risky }.should raise_error(PoorRiskDecisionError, /oo ri/)
+    #   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(PoorRiskDecisionError, "that was too risky")
+    #   expect { do_something_risky }.to raise_error(PoorRiskDecisionError, /oo ri/)
     #
-    #   lambda { do_something_risky }.should_not raise_error
-    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError)
-    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, "that was too risky")
-    #   lambda { do_something_risky }.should_not raise_error(PoorRiskDecisionError, /oo ri/)
+    #   expect { do_something_risky }.not_to raise_error
     def raise_error(error=Exception, message=nil, &block)
       BuiltIn::RaiseError.new(error, message, &block)
     end
+    alias_method  :raise_exception,  :raise_error
+
+    alias_matcher :a_block_raising,  :raise_error do |desc|
+      desc.sub("raise", "a block raising")
+    end
 
-    alias_method :raise_exception, :raise_error
+    alias_matcher :raising,        :raise_error do |desc|
+      desc.sub("raise", "raising")
+    end
 
     # Matches if the target object responds to all of the names
     # 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
 
     # Passes if the submitted block returns true. Yields target to the
     # block.
@@ -550,12 +737,12 @@ module RSpec
     #
     # @example
     #
-    #   5.should satisfy { |n|
-    #     n > 3
-    #   }
+    #   expect(5).to satisfy { |n| n > 3 }
     def satisfy(&block)
       BuiltIn::Satisfy.new(&block)
     end
+    alias_matcher :an_object_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
@@ -564,12 +751,15 @@ module RSpec
     #
     # @example
     #
-    #   "this string".should start_with "this s"
-    #   [0, 1, 2, 3, 4].should start_with 0
-    #   [0, 2, 3, 4, 4].should start_with 0, 1
+    #   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
     def start_with(*expected)
       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
 
     # Given no argument, matches if a proc throws any Symbol.
     #
@@ -580,17 +770,25 @@ module RSpec
     #
     # @example
     #
-    #   lambda { do_something_risky }.should throw_symbol
-    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky)
-    #   lambda { do_something_risky }.should throw_symbol(:that_was_risky, culprit)
+    #   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')
     #
-    #   lambda { do_something_risky }.should_not throw_symbol
-    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky)
-    #   lambda { do_something_risky }.should_not throw_symbol(:that_was_risky, culprit)
+    #   expect { do_something_risky }.not_to throw_symbol
+    #   expect { do_something_risky }.not_to throw_symbol(:that_was_risky)
+    #   expect { do_something_risky }.not_to throw_symbol(:that_was_risky, 'culprit')
     def throw_symbol(expected_symbol=nil, expected_arg=nil)
       BuiltIn::ThrowSymbol.new(expected_symbol, expected_arg)
     end
 
+    alias_matcher :a_block_throwing, :throw_symbol do |desc|
+      desc.sub("throw", "a block throwing")
+    end
+
+    alias_matcher :throwing,        :throw_symbol do |desc|
+      desc.sub("throw", "throwing")
+    end
+
     # Passes if the method called in the expect block yields, regardless
     # of whether or not arguments are yielded.
     #
@@ -606,6 +804,8 @@ module RSpec
     def yield_control
       BuiltIn::YieldControl.new
     end
+    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.
@@ -623,6 +823,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
 
     # Given no arguments, matches if the method called in the expect
     # block yields with arguments (regardless of what they are or how
@@ -652,6 +854,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
 
     # Designed for use with methods that repeatedly yield (such as
     # iterators). Passes if the method called in the expect block yields
@@ -672,28 +876,47 @@ 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
+
+    # Delegates to {RSpec::Expectations.configuration}.
+    # This is here because rspec-core's `expect_with` option
+    # looks for a `configuration` method on the mixin
+    # (`RSpec::Matchers`) to yield to a block.
+    # @return [RSpec::Expectations::Configuration] the configuration object
+    def self.configuration
+      Expectations.configuration
+    end
 
-    # Passes if actual contains all of the expected regardless of order.
-    # This works for collections. Pass in multiple args and it will only
-    # pass if all args are found in collection.
-    #
-    # @note This is also available using the `=~` operator with `should`,
-    #       but `=~` is not supported with `expect`.
-    # @note There is no should_not version of array.should =~ other_array
-    #
-    # @example
-    #
-    #   expect([1,2,3]).to match_array([1,2,3])
-    #   expect([1,2,3]).to match_array([1,3,2])
-    #   [1,2,3].should   =~ [1,2,3]   # => would pass
-    #   [1,2,3].should   =~ [2,3,1]   # => would pass
-    #   [1,2,3,4].should =~ [1,2,3]   # => would fail
-    #   [1,2,2,3].should =~ [1,2,3]   # => would fail
-    #   [1,2,3].should   =~ [1,2,3,4] # => would fail
-    def match_array(array)
-      BuiltIn::MatchArray.new(array)
+  private
+
+    BE_PREDICATE_REGEX = /^(be_(?:an?_)?)(.*)/
+    HAS_REGEX = /^(?:have_)(.*)/
+
+    def method_missing(method, *args, &block)
+      case method.to_s
+        when BE_PREDICATE_REGEX
+          BuiltIn::BePredicate.new(method, *args, &block)
+        when HAS_REGEX
+          BuiltIn::Has.new(method, *args, &block)
+        else
+          super
+      end
+    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)
+      return false unless obj.respond_to?(:matches?)
+
+      obj.respond_to?(:failure_message) ||
+      obj.respond_to?(:failure_message_for_should) # support legacy matchers
     end
 
-    OperatorMatcher.register(Enumerable, '=~', BuiltIn::MatchArray)
+    # @api private
+    def self.is_a_describable_matcher?(obj)
+      is_a_matcher?(obj) && obj.respond_to?(:description)
+    end
   end
 end