rspec-mocks-diag 3.8.1.1

data/lib/rspec/mocks/error_generator.rb

@@ -0,0 +1,378 @@
+RSpec::Support.require_rspec_support "object_formatter"
+
+module RSpec
+  module Mocks
+    # Raised when a message expectation is not satisfied.
+    MockExpectationError = Class.new(Exception)
+
+    # Raised when a test double is used after it has been torn
+    # down (typically at the end of an rspec-core example).
+    ExpiredTestDoubleError = Class.new(MockExpectationError)
+
+    # Raised when doubles or partial doubles are used outside of the per-test lifecycle.
+    OutsideOfExampleError = Class.new(StandardError)
+
+    # Raised when an expectation customization method (e.g. `with`,
+    # `and_return`) is called on a message expectation which has already been
+    # invoked.
+    MockExpectationAlreadyInvokedError = Class.new(Exception)
+
+    # Raised for situations that RSpec cannot support due to mutations made
+    # externally on arguments that RSpec is holding onto to use for later
+    # comparisons.
+    #
+    # @deprecated We no longer raise this error but the constant remains until
+    #   RSpec 4 for SemVer reasons.
+    CannotSupportArgMutationsError = Class.new(StandardError)
+
+    # @private
+    UnsupportedMatcherError  = Class.new(StandardError)
+    # @private
+    NegationUnsupportedError = Class.new(StandardError)
+    # @private
+    VerifyingDoubleNotDefinedError = Class.new(StandardError)
+
+    # @private
+    class ErrorGenerator
+      attr_writer :opts
+
+      def initialize(target=nil)
+        @target = target
+      end
+
+      # @private
+      def opts
+        @opts ||= {}
+      end
+
+      # @private
+      def raise_unexpected_message_error(message, args)
+        __raise "#{intro} received unexpected message :#{message} with #{format_args(args)}"
+      end
+
+      # @private
+      def raise_unexpected_message_args_error(expectation, args_for_multiple_calls, source_id=nil)
+        __raise error_message(expectation, args_for_multiple_calls), nil, source_id
+      end
+
+      # @private
+      def raise_missing_default_stub_error(expectation, args_for_multiple_calls)
+        __raise(
+          error_message(expectation, args_for_multiple_calls) +
+          "\n Please stub a default value first if message might be received with other args as well. \n"
+        )
+      end
+
+      # @private
+      def raise_similar_message_args_error(expectation, args_for_multiple_calls, backtrace_line=nil)
+        __raise error_message(expectation, args_for_multiple_calls), backtrace_line
+      end
+
+      def default_error_message(expectation, expected_args, actual_args)
+        "#{intro} received #{expectation.message.inspect} #{unexpected_arguments_message(expected_args, actual_args)}".dup
+      end
+
+      # rubocop:disable Metrics/ParameterLists
+      # @private
+      def raise_expectation_error(message, expected_received_count, argument_list_matcher,
+                                  actual_received_count, expectation_count_type, args,
+                                  backtrace_line=nil, source_id=nil, args_history=nil)
+        expected_part = expected_part_of_expectation_error(expected_received_count, expectation_count_type, argument_list_matcher)
+        received_part = received_part_of_expectation_error(actual_received_count, args, args_history)
+        __raise "(#{intro(:unwrapped)}).#{message}#{format_args(args)}\n    #{expected_part}\n    #{received_part}", backtrace_line, source_id
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      # @private
+      def raise_unimplemented_error(doubled_module, method_name, object)
+        message = case object
+                  when InstanceVerifyingDouble
+                    "the %s class does not implement the instance method: %s".dup <<
+                      if ObjectMethodReference.for(doubled_module, method_name).implemented?
+                        ". Perhaps you meant to use `class_double` instead?"
+                      else
+                        ""
+                      end
+                  when ClassVerifyingDouble
+                    "the %s class does not implement the class method: %s".dup <<
+                      if InstanceMethodReference.for(doubled_module, method_name).implemented?
+                        ". Perhaps you meant to use `instance_double` instead?"
+                      else
+                        ""
+                      end
+                  else
+                    "%s does not implement: %s"
+                  end
+
+        __raise message % [doubled_module.description, method_name]
+      end
+
+      # @private
+      def raise_non_public_error(method_name, visibility)
+        raise NoMethodError, "%s method `%s' called on %s" % [
+          visibility, method_name, intro
+        ]
+      end
+
+      # @private
+      def raise_invalid_arguments_error(verifier)
+        __raise verifier.error_message
+      end
+
+      # @private
+      def raise_expired_test_double_error
+        raise ExpiredTestDoubleError,
+              "#{intro} was originally created in one example but has leaked into " \
+              "another example and can no longer be used. rspec-mocks' doubles are " \
+              "designed to only last for one example, and you need to create a new " \
+              "one in each example you wish to use it for."
+      end
+
+      # @private
+      def describe_expectation(verb, message, expected_received_count, _actual_received_count, args)
+        "#{verb} #{message}#{format_args(args)} #{count_message(expected_received_count)}"
+      end
+
+      # @private
+      def raise_out_of_order_error(message)
+        __raise "#{intro} received :#{message} out of order"
+      end
+
+      # @private
+      def raise_missing_block_error(args_to_yield)
+        __raise "#{intro} asked to yield |#{arg_list(args_to_yield)}| but no block was passed"
+      end
+
+      # @private
+      def raise_wrong_arity_error(args_to_yield, signature)
+        __raise "#{intro} yielded |#{arg_list(args_to_yield)}| to block with #{signature.description}"
+      end
+
+      # @private
+      def raise_only_valid_on_a_partial_double(method)
+        __raise "#{intro} is a pure test double. `#{method}` is only " \
+                "available on a partial double."
+      end
+
+      # @private
+      def raise_expectation_on_unstubbed_method(method)
+        __raise "#{intro} expected to have received #{method}, but that " \
+                "object is not a spy or method has not been stubbed."
+      end
+
+      # @private
+      def raise_expectation_on_mocked_method(method)
+        __raise "#{intro} expected to have received #{method}, but that " \
+                "method has been mocked instead of stubbed or spied."
+      end
+
+      # @private
+      def raise_double_negation_error(wrapped_expression)
+        __raise "Isn't life confusing enough? You've already set a " \
+                "negative message expectation and now you are trying to " \
+                "negate it again with `never`. What does an expression like " \
+                "`#{wrapped_expression}.not_to receive(:msg).never` even mean?"
+      end
+
+      # @private
+      def raise_verifying_double_not_defined_error(ref)
+        notify(VerifyingDoubleNotDefinedError.new(
+          "#{ref.description.inspect} is not a defined constant. " \
+          "Perhaps you misspelt it? " \
+          "Disable check with `verify_doubled_constant_names` configuration option."
+        ))
+      end
+
+      # @private
+      def raise_have_received_disallowed(type, reason)
+        __raise "Using #{type}(...) with the `have_received` " \
+                "matcher is not supported#{reason}."
+      end
+
+      # @private
+      def raise_cant_constrain_count_for_negated_have_received_error(count_constraint)
+        __raise "can't use #{count_constraint} when negative"
+      end
+
+      # @private
+      def raise_method_not_stubbed_error(method_name)
+        __raise "The method `#{method_name}` was not stubbed or was already unstubbed"
+      end
+
+      # @private
+      def raise_already_invoked_error(message, calling_customization)
+        error_message = "The message expectation for #{intro}.#{message} has already been invoked " \
+          "and cannot be modified further (e.g. using `#{calling_customization}`). All message expectation " \
+          "customizations must be applied before it is used for the first time."
+
+        notify MockExpectationAlreadyInvokedError.new(error_message)
+      end
+
+      def raise_expectation_on_nil_error(method_name)
+        __raise expectation_on_nil_message(method_name)
+      end
+
+      def expectation_on_nil_message(method_name)
+        "An expectation of `:#{method_name}` was set on `nil`. " \
+        "To allow expectations on `nil` and suppress this message, set `RSpec::Mocks.configuration.allow_message_expectations_on_nil` to `true`. " \
+        "To disallow expectations on `nil`, set `RSpec::Mocks.configuration.allow_message_expectations_on_nil` to `false`"
+      end
+
+      # @private
+      def intro(unwrapped=false)
+        case @target
+        when TestDouble then TestDoubleFormatter.format(@target, unwrapped)
+        when Class then
+          formatted = "#{@target.inspect} (class)"
+          return formatted if unwrapped
+          "#<#{formatted}>"
+        when NilClass then "nil"
+        else @target.inspect
+        end
+      end
+
+      # @private
+      def method_call_args_description(args, generic_prefix=" with arguments: ", matcher_prefix=" with ")
+        case args.first
+        when ArgumentMatchers::AnyArgsMatcher then "#{matcher_prefix}any arguments"
+        when ArgumentMatchers::NoArgsMatcher  then "#{matcher_prefix}no arguments"
+        else
+          if yield
+            "#{generic_prefix}#{format_args(args)}"
+          else
+            ""
+          end
+        end
+      end
+
+    private
+
+      def received_part_of_expectation_error(actual_received_count, args, args_history=nil)
+        extra = ''
+        if args_history
+          args_history.each_with_index do |(arg, backtrace), index|
+            extra += "\n      call #{index+1}: #{arg.inspect}"
+            backtrace.each do |line|
+              extra += "\n        from #{line}"
+            end
+          end
+        end
+        "received: #{count_message(actual_received_count)}" +
+          method_call_args_description(args) do
+            actual_received_count > 0 && args.length > 0
+          end + extra
+      end
+
+      def expected_part_of_expectation_error(expected_received_count, expectation_count_type, argument_list_matcher)
+        "expected: #{count_message(expected_received_count, expectation_count_type)}" +
+          method_call_args_description(argument_list_matcher.expected_args) do
+            argument_list_matcher.expected_args.length > 0
+          end
+      end
+
+      def unexpected_arguments_message(expected_args_string, actual_args_string)
+        "with unexpected arguments\n  expected: #{expected_args_string}\n       got: #{actual_args_string}"
+      end
+
+      def error_message(expectation, args_for_multiple_calls)
+        expected_args = format_args(expectation.expected_args)
+        actual_args = format_received_args(args_for_multiple_calls)
+        message = default_error_message(expectation, expected_args, actual_args)
+
+        if args_for_multiple_calls.one?
+          diff = diff_message(expectation.expected_args, args_for_multiple_calls.first)
+          message << "\nDiff:#{diff}" unless diff.strip.empty?
+        end
+
+        message
+      end
+
+      def diff_message(expected_args, actual_args)
+        formatted_expected_args = expected_args.map do |x|
+          RSpec::Support.rspec_description_for_object(x)
+        end
+
+        formatted_expected_args, actual_args = unpack_string_args(formatted_expected_args, actual_args)
+
+        differ.diff(actual_args, formatted_expected_args)
+      end
+
+      def unpack_string_args(formatted_expected_args, actual_args)
+        if [formatted_expected_args, actual_args].all? { |x| list_of_exactly_one_string?(x) }
+          [formatted_expected_args.first, actual_args.first]
+        else
+          [formatted_expected_args, actual_args]
+        end
+      end
+
+      def list_of_exactly_one_string?(args)
+        Array === args && args.count == 1 && String === args.first
+      end
+
+      def differ
+        RSpec::Support::Differ.new(:color => RSpec::Mocks.configuration.color?)
+      end
+
+      def __raise(message, backtrace_line=nil, source_id=nil)
+        message = opts[:message] unless opts[:message].nil?
+        exception = RSpec::Mocks::MockExpectationError.new(message)
+        prepend_to_backtrace(exception, backtrace_line) if backtrace_line
+        notify exception, :source_id => source_id
+      end
+
+      if RSpec::Support::Ruby.jruby?
+        def prepend_to_backtrace(exception, line)
+          raise exception
+        rescue RSpec::Mocks::MockExpectationError => with_backtrace
+          with_backtrace.backtrace.unshift(line)
+        end
+      else
+        def prepend_to_backtrace(exception, line)
+          exception.set_backtrace(caller.unshift line)
+        end
+      end
+
+      def notify(*args)
+        RSpec::Support.notify_failure(*args)
+      end
+
+      def format_args(args)
+        return "(no args)" if args.empty?
+        "(#{arg_list(args)})"
+      end
+
+      def arg_list(args)
+        args.map { |arg| RSpec::Support::ObjectFormatter.format(arg) }.join(", ")
+      end
+
+      def format_received_args(args_for_multiple_calls)
+        grouped_args(args_for_multiple_calls).map do |args_for_one_call, index|
+          "#{format_args(args_for_one_call)}#{group_count(index, args_for_multiple_calls)}"
+        end.join("\n            ")
+      end
+
+      def count_message(count, expectation_count_type=nil)
+        return "at least #{times(count.abs)}" if count < 0 || expectation_count_type == :at_least
+        return "at most #{times(count)}" if expectation_count_type == :at_most
+        times(count)
+      end
+
+      def times(count)
+        "#{count} time#{count == 1 ? '' : 's'}"
+      end
+
+      def grouped_args(args)
+        Hash[args.group_by { |x| x }.map { |k, v| [k, v.count] }]
+      end
+
+      def group_count(index, args)
+        " (#{times(index)})" if args.size > 1 || index > 1
+      end
+    end
+
+    # @private
+    def self.error_generator
+      @error_generator ||= ErrorGenerator.new
+    end
+  end
+end

data/lib/rspec/mocks/example_methods.rb

@@ -0,0 +1,434 @@
+RSpec::Support.require_rspec_mocks 'object_reference'
+
+module RSpec
+  module Mocks
+    # Contains methods intended to be used from within code examples.
+    # Mix this in to your test context (such as a test framework base class)
+    # to use rspec-mocks with your test framework. If you're using rspec-core,
+    # it'll take care of doing this for you.
+    module ExampleMethods
+      include RSpec::Mocks::ArgumentMatchers
+
+      # @overload double()
+      # @overload double(name)
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload double(stubs)
+      #   @param stubs (Hash) hash of message/return-value pairs
+      # @overload double(name, stubs)
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs (Hash) hash of message/return-value pairs
+      # @return (Double)
+      #
+      # Constructs an instance of [RSpec::Mocks::Double](RSpec::Mocks::Double) configured
+      # with an optional name, used for reporting in failure messages, and an optional
+      # hash of message/return-value pairs.
+      #
+      # @example
+      #   book = double("book", :title => "The RSpec Book")
+      #   book.title #=> "The RSpec Book"
+      #
+      #   card = double("card", :suit => "Spades", :rank => "A")
+      #   card.suit  #=> "Spades"
+      #   card.rank  #=> "A"
+      #
+      def double(*args)
+        ExampleMethods.declare_double(Double, *args)
+      end
+
+      # @overload instance_double(doubled_class)
+      #   @param doubled_class [String, Class]
+      # @overload instance_double(doubled_class, name)
+      #   @param doubled_class [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload instance_double(doubled_class, stubs)
+      #   @param doubled_class [String, Class]
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @overload instance_double(doubled_class, name, stubs)
+      #   @param doubled_class [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @return InstanceVerifyingDouble
+      #
+      # Constructs a test double against a specific class. If the given class
+      # name has been loaded, only instance methods defined on the class are
+      # allowed to be stubbed. In all other ways it behaves like a
+      # [double](double).
+      def instance_double(doubled_class, *args)
+        ref = ObjectReference.for(doubled_class)
+        ExampleMethods.declare_verifying_double(InstanceVerifyingDouble, ref, *args)
+      end
+
+      # @overload class_double(doubled_class)
+      #   @param doubled_class [String, Module]
+      # @overload class_double(doubled_class, name)
+      #   @param doubled_class [String, Module]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload class_double(doubled_class, stubs)
+      #   @param doubled_class [String, Module]
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @overload class_double(doubled_class, name, stubs)
+      #   @param doubled_class [String, Module]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @return ClassVerifyingDouble
+      #
+      # Constructs a test double against a specific class. If the given class
+      # name has been loaded, only class methods defined on the class are
+      # allowed to be stubbed. In all other ways it behaves like a
+      # [double](double).
+      def class_double(doubled_class, *args)
+        ref = ObjectReference.for(doubled_class)
+        ExampleMethods.declare_verifying_double(ClassVerifyingDouble, ref, *args)
+      end
+
+      # @overload object_double(object_or_name)
+      #   @param object_or_name [String, Object]
+      # @overload object_double(object_or_name, name)
+      #   @param object_or_name [String, Object]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload object_double(object_or_name, stubs)
+      #   @param object_or_name [String, Object]
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @overload object_double(object_or_name, name, stubs)
+      #   @param object_or_name [String, Object]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @return ObjectVerifyingDouble
+      #
+      # Constructs a test double against a specific object. Only the methods
+      # the object responds to are allowed to be stubbed. If a String argument
+      # is provided, it is assumed to reference a constant object which is used
+      # for verification. In all other ways it behaves like a [double](double).
+      def object_double(object_or_name, *args)
+        ref = ObjectReference.for(object_or_name, :allow_direct_object_refs)
+        ExampleMethods.declare_verifying_double(ObjectVerifyingDouble, ref, *args)
+      end
+
+      # @overload spy()
+      # @overload spy(name)
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload spy(stubs)
+      #   @param stubs (Hash) hash of message/return-value pairs
+      # @overload spy(name, stubs)
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs (Hash) hash of message/return-value pairs
+      # @return (Double)
+      #
+      # Constructs a test double that is optimized for use with
+      # `have_received`. With a normal double one has to stub methods in order
+      # to be able to spy them. A spy automatically spies on all methods.
+      def spy(*args)
+        double(*args).as_null_object
+      end
+
+      # @overload instance_spy(doubled_class)
+      #   @param doubled_class [String, Class]
+      # @overload instance_spy(doubled_class, name)
+      #   @param doubled_class [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload instance_spy(doubled_class, stubs)
+      #   @param doubled_class [String, Class]
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @overload instance_spy(doubled_class, name, stubs)
+      #   @param doubled_class [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @return InstanceVerifyingDouble
+      #
+      # Constructs a test double that is optimized for use with `have_received`
+      # against a specific class. If the given class name has been loaded, only
+      # instance methods defined on the class are allowed to be stubbed.  With
+      # a normal double one has to stub methods in order to be able to spy
+      # them. An instance_spy automatically spies on all instance methods to
+      # which the class responds.
+      def instance_spy(*args)
+        instance_double(*args).as_null_object
+      end
+
+      # @overload object_spy(object_or_name)
+      #   @param object_or_name [String, Object]
+      # @overload object_spy(object_or_name, name)
+      #   @param object_or_name [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload object_spy(object_or_name, stubs)
+      #   @param object_or_name [String, Object]
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @overload object_spy(object_or_name, name, stubs)
+      #   @param object_or_name [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @return ObjectVerifyingDouble
+      #
+      # Constructs a test double that is optimized for use with `have_received`
+      # against a specific object. Only instance methods defined on the object
+      # are allowed to be stubbed.  With a normal double one has to stub
+      # methods in order to be able to spy them. An object_spy automatically
+      # spies on all methods to which the object responds.
+      def object_spy(*args)
+        object_double(*args).as_null_object
+      end
+
+      # @overload class_spy(doubled_class)
+      #   @param doubled_class [String, Module]
+      # @overload class_spy(doubled_class, name)
+      #   @param doubled_class [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      # @overload class_spy(doubled_class, stubs)
+      #   @param doubled_class [String, Module]
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @overload class_spy(doubled_class, name, stubs)
+      #   @param doubled_class [String, Class]
+      #   @param name [String/Symbol] name or description to be used in failure messages
+      #   @param stubs [Hash] hash of message/return-value pairs
+      # @return ClassVerifyingDouble
+      #
+      # Constructs a test double that is optimized for use with `have_received`
+      # against a specific class. If the given class name has been loaded,
+      # only class methods defined on the class are allowed to be stubbed.
+      # With a normal double one has to stub methods in order to be able to spy
+      # them. An class_spy automatically spies on all class methods to which the
+      # class responds.
+      def class_spy(*args)
+        class_double(*args).as_null_object
+      end
+
+      # Disables warning messages about expectations being set on nil.
+      #
+      # By default warning messages are issued when expectations are set on
+      # nil.  This is to prevent false-positives and to catch potential bugs
+      # early on.
+      # @deprecated Use {RSpec::Mocks::Configuration#allow_message_expectations_on_nil} instead.
+      def allow_message_expectations_on_nil
+        RSpec::Mocks.space.proxy_for(nil).warn_about_expectations = false
+      end
+
+      # Stubs the named constant with the given value.
+      # Like method stubs, the constant will be restored
+      # to its original value (or lack of one, if it was
+      # undefined) when the example completes.
+      #
+      # @param constant_name [String] The fully qualified name of the constant. The current
+      #   constant scoping at the point of call is not considered.
+      # @param value [Object] The value to make the constant refer to. When the
+      #   example completes, the constant will be restored to its prior state.
+      # @param options [Hash] Stubbing options.
+      # @option options :transfer_nested_constants [Boolean, Array<Symbol>] Determines
+      #   what nested constants, if any, will be transferred from the original value
+      #   of the constant to the new value of the constant. This only works if both
+      #   the original and new values are modules (or classes).
+      # @return [Object] the stubbed value of the constant
+      #
+      # @example
+      #   stub_const("MyClass", Class.new) # => Replaces (or defines) MyClass with a new class object.
+      #   stub_const("SomeModel::PER_PAGE", 5) # => Sets SomeModel::PER_PAGE to 5.
+      #
+      #   class CardDeck
+      #     SUITS = [:Spades, :Diamonds, :Clubs, :Hearts]
+      #     NUM_CARDS = 52
+      #   end
+      #
+      #   stub_const("CardDeck", Class.new)
+      #   CardDeck::SUITS # => uninitialized constant error
+      #   CardDeck::NUM_CARDS # => uninitialized constant error
+      #
+      #   stub_const("CardDeck", Class.new, :transfer_nested_constants => true)
+      #   CardDeck::SUITS # => our suits array
+      #   CardDeck::NUM_CARDS # => 52
+      #
+      #   stub_const("CardDeck", Class.new, :transfer_nested_constants => [:SUITS])
+      #   CardDeck::SUITS # => our suits array
+      #   CardDeck::NUM_CARDS # => uninitialized constant error
+      def stub_const(constant_name, value, options={})
+        ConstantMutator.stub(constant_name, value, options)
+      end
+
+      # Hides the named constant with the given value. The constant will be
+      # undefined for the duration of the test.
+      #
+      # Like method stubs, the constant will be restored to its original value
+      # when the example completes.
+      #
+      # @param constant_name [String] The fully qualified name of the constant.
+      #   The current constant scoping at the point of call is not considered.
+      #
+      # @example
+      #   hide_const("MyClass") # => MyClass is now an undefined constant
+      def hide_const(constant_name)
+        ConstantMutator.hide(constant_name)
+      end
+
+      # Verifies that the given object received the expected message during the
+      # course of the test. On a spy objects or as null object doubles this
+      # works for any method, on other objects the method must have
+      # been stubbed beforehand in order for messages to be verified.
+      #
+      # Stubbing and verifying messages received in this way implements the
+      # Test Spy pattern.
+      #
+      # @param method_name [Symbol] name of the method expected to have been
+      #   called.
+      #
+      # @example
+      #   invitation = double('invitation', accept: true)
+      #   user.accept_invitation(invitation)
+      #   expect(invitation).to have_received(:accept)
+      #
+      #   # You can also use most message expectations:
+      #   expect(invitation).to have_received(:accept).with(mailer).once
+      #
+      # @note `have_received(...).with(...)` is unable to work properly when
+      #   passed arguments are mutated after the spy records the received message.
+      def have_received(method_name, &block)
+        Matchers::HaveReceived.new(method_name, &block)
+      end
+
+      # Turns off the verifying of partial doubles for the duration of the
+      # block, this is useful in situations where methods are defined at run
+      # time and you wish to define stubs for them but not turn off partial
+      # doubles for the entire run suite. (e.g. view specs in rspec-rails).
+      def without_partial_double_verification
+        original_state = Mocks.configuration.temporarily_suppress_partial_double_verification
+        Mocks.configuration.temporarily_suppress_partial_double_verification = true
+        yield
+      ensure
+        Mocks.configuration.temporarily_suppress_partial_double_verification = original_state
+      end
+
+      # @method expect
+      # Used to wrap an object in preparation for setting a mock expectation
+      # on it.
+      #
+      # @example
+      #   expect(obj).to receive(:foo).with(5).and_return(:return_value)
+      #
+      # @note This method is usually provided by rspec-expectations. However,
+      #   if you use rspec-mocks without rspec-expectations, there's a definition
+      #   of it that is made available here. If you disable the `:expect` syntax
+      #   this method will be undefined.
+
+      # @method allow
+      # Used to wrap an object in preparation for stubbing a method
+      # on it.
+      #
+      # @example
+      #   allow(dbl).to receive(:foo).with(5).and_return(:return_value)
+      #
+      # @note If you disable the `:expect` syntax this method will be undefined.
+
+      # @method expect_any_instance_of
+      # Used to wrap a class in preparation for setting a mock expectation
+      # on instances of it.
+      #
+      # @example
+      #   expect_any_instance_of(MyClass).to receive(:foo)
+      #
+      # @note If you disable the `:expect` syntax this method will be undefined.
+
+      # @method allow_any_instance_of
+      # Used to wrap a class in preparation for stubbing a method
+      # on instances of it.
+      #
+      # @example
+      #   allow_any_instance_of(MyClass).to receive(:foo)
+      #
+      # @note This is only available when you have enabled the `expect` syntax.
+
+      # @method receive
+      # Used to specify a message that you expect or allow an object
+      # to receive. The object returned by `receive` supports the same
+      # fluent interface that `should_receive` and `stub` have always
+      # supported, allowing you to constrain the arguments or number of
+      # times, and configure how the object should respond to the message.
+      #
+      # @example
+      #   expect(obj).to receive(:hello).with("world").exactly(3).times
+      #
+      # @note If you disable the `:expect` syntax this method will be undefined.
+
+      # @method receive_messages
+      # Shorthand syntax used to setup message(s), and their return value(s),
+      # that you expect or allow an object to receive. The method takes a hash
+      # of messages and their respective return values. Unlike with `receive`,
+      # you cannot apply further customizations using a block or the fluent
+      # interface.
+      #
+      # @example
+      #   allow(obj).to receive_messages(:speak => "Hello World")
+      #   allow(obj).to receive_messages(:speak => "Hello", :meow => "Meow")
+      #
+      # @note If you disable the `:expect` syntax this method will be undefined.
+
+      # @method receive_message_chain
+      # @overload receive_message_chain(method1, method2)
+      # @overload receive_message_chain("method1.method2")
+      # @overload receive_message_chain(method1, method_to_value_hash)
+      #
+      # stubs/mocks a chain of messages on an object or test double.
+      #
+      # ## Warning:
+      #
+      # Chains can be arbitrarily long, which makes it quite painless to
+      # violate the Law of Demeter in violent ways, so you should consider any
+      # use of `receive_message_chain` a code smell. Even though not all code smells
+      # indicate real problems (think fluent interfaces), `receive_message_chain` still
+      # results in brittle examples.  For example, if you write
+      # `allow(foo).to receive_message_chain(:bar, :baz => 37)` in a spec and then the
+      # implementation calls `foo.baz.bar`, the stub will not work.
+      #
+      # @example
+      #   allow(double).to receive_message_chain("foo.bar") { :baz }
+      #   allow(double).to receive_message_chain(:foo, :bar => :baz)
+      #   allow(double).to receive_message_chain(:foo, :bar) { :baz }
+      #
+      #   # Given any of ^^ these three forms ^^:
+      #   double.foo.bar # => :baz
+      #
+      #   # Common use in Rails/ActiveRecord:
+      #   allow(Article).to receive_message_chain("recent.published") { [Article.new] }
+      #
+      # @note If you disable the `:expect` syntax this method will be undefined.
+
+      # @private
+      def self.included(klass)
+        klass.class_exec do
+          # This gets mixed in so that if `RSpec::Matchers` is included in
+          # `klass` later, its definition of `expect` will take precedence.
+          include ExpectHost unless method_defined?(:expect)
+        end
+      end
+
+      # @private
+      def self.extended(object)
+        # This gets extended in so that if `RSpec::Matchers` is included in
+        # `klass` later, its definition of `expect` will take precedence.
+        object.extend ExpectHost unless object.respond_to?(:expect)
+      end
+
+      # @private
+      def self.declare_verifying_double(type, ref, *args)
+        if RSpec::Mocks.configuration.verify_doubled_constant_names? &&
+          !ref.defined?
+
+          RSpec::Mocks.error_generator.raise_verifying_double_not_defined_error(ref)
+        end
+
+        RSpec::Mocks.configuration.verifying_double_callbacks.each do |block|
+          block.call(ref)
+        end
+
+        declare_double(type, ref, *args)
+      end
+
+      # @private
+      def self.declare_double(type, *args)
+        args << {} unless Hash === args.last
+        type.new(*args)
+      end
+
+      # This module exists to host the `expect` method for cases where
+      # rspec-mocks is used w/o rspec-expectations.
+      module ExpectHost
+      end
+    end
+  end
+end