rspec-mocks 3.1.3 → 3.2.0

data/lib/rspec/mocks/error_generator.rb

@@ -10,6 +10,16 @@ module RSpec
     # 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.
+    CannotSupportArgMutationsError = Class.new(StandardError)
+
     # @private
     UnsupportedMatcherError  = Class.new(StandardError)
     # @private
@@ -40,28 +50,42 @@ module RSpec
       def raise_unexpected_message_args_error(expectation, *args)
         expected_args = format_args(*expectation.expected_args)
         actual_args = format_received_args(*args)
-        __raise "#{intro} received #{expectation.message.inspect} with " \
-                "unexpected arguments\n  expected: #{expected_args}\n" \
-                "       got: #{actual_args}"
+        diff = diff_message(expectation.expected_args, args)
+
+        message = default_error_message(expectation, expected_args, actual_args)
+        message << "\nDiff:#{diff}" unless diff.empty?
+
+        __raise message
       end
 
       # @private
       def raise_missing_default_stub_error(expectation, *args)
         expected_args = format_args(*expectation.expected_args)
         actual_args = format_received_args(*args)
-        __raise "#{intro} received #{expectation.message.inspect} with " \
-                "unexpected arguments\n  expected: #{expected_args}\n" \
-                "       got: #{actual_args}\n Please stub a default value " \
-                "first if message might be received with other args as well. \n"
+        diff = diff_message(expectation.expected_args, args)
+
+        message = default_error_message(expectation, expected_args, actual_args)
+        message << "\nDiff:\n #{diff}" unless diff.empty?
+        message << "\n Please stub a default value first if message might be received with other args as well. \n"
+
+        __raise message
       end
 
       # @private
       def raise_similar_message_args_error(expectation, *args_for_multiple_calls)
         expected_args = format_args(*expectation.expected_args)
         actual_args = args_for_multiple_calls.map { |a| format_received_args(*a) }.join(", ")
-        __raise "#{intro} received #{expectation.message.inspect} with " \
-                "unexpected arguments\n  expected: #{expected_args}\n" \
-                "       got: #{actual_args}"
+
+        __raise(default_error_message(expectation, expected_args, actual_args))
+      end
+
+      def default_error_message(expectation, expected_args, actual_args)
+        [
+          intro,
+          "received",
+          expectation.message.inspect,
+          unexpected_arguments_message(expected_args, actual_args),
+        ].join(" ")
       end
 
       # rubocop:disable Style/ParameterLists
@@ -143,8 +167,8 @@ module RSpec
       end
 
       # @private
-      def describe_expectation(message, expected_received_count, _actual_received_count, *args)
-        "have received #{message}#{format_args(*args)} #{count_message(expected_received_count)}"
+      def describe_expectation(verb, message, expected_received_count, _actual_received_count, *args)
+        "#{verb} #{message}#{format_args(*args)} #{count_message(expected_received_count)}"
       end
 
       # @private
@@ -194,6 +218,36 @@ module RSpec
 
     private
 
+      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 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 intro
         if @name
           "Double #{@name.inspect}"
@@ -222,13 +276,11 @@ module RSpec
       end
 
       def arg_list(*args)
-        args.map { |arg| arg_has_valid_description(arg) ? arg.description : arg.inspect }.join(", ")
+        args.map { |arg| arg_has_valid_description?(arg) ? arg.description : arg.inspect }.join(", ")
       end
 
-      def arg_has_valid_description(arg)
-        return false unless arg.respond_to?(:description)
-
-        !arg.description.nil? && !arg.description.empty?
+      def arg_has_valid_description?(arg)
+        RSpec::Support.is_a_matcher?(arg) && arg.respond_to?(:description)
       end
 
       def format_received_args(*args)

data/lib/rspec/mocks/example_methods.rb

@@ -11,11 +11,11 @@ module RSpec
 
       # @overload double()
       # @overload double(name)
-      #   @param name [String/Symbol] used to clarify intent
+      #   @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] used to clarify intent
+      #   @param name [String/Symbol] name or description to be used in failure messages
       #   @param stubs (Hash) hash of message/return-value pairs
       # @return (Double)
       #
@@ -38,9 +38,16 @@ module RSpec
 
       # @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
@@ -54,9 +61,16 @@ module RSpec
 
       # @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
@@ -70,9 +84,16 @@ module RSpec
 
       # @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
@@ -86,11 +107,11 @@ module RSpec
 
       # @overload spy()
       # @overload spy(name)
-      #   @param name [String/Symbol] used to clarify intent
+      #   @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] used to clarify intent
+      #   @param name [String/Symbol] name or description to be used in failure messages
       #   @param stubs (Hash) hash of message/return-value pairs
       # @return (Double)
       #
@@ -103,9 +124,16 @@ module RSpec
 
       # @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`
@@ -120,9 +148,16 @@ module RSpec
 
       # @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`
@@ -136,9 +171,16 @@ module RSpec
 
       # @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`
@@ -350,15 +392,26 @@ module RSpec
         end
       end
 
+      # @private
+      def self.extended(object)
+        # This gets extended in so that if `RSpec::Matchers` is included in
+        # `klass` later, it's 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?
 
           raise VerifyingDoubleNotDefinedError,
-                "#{ref.description} is not a defined constant. " \
+                "#{ref.description.inspect} is not a defined constant. " \
                 "Perhaps you misspelt it? " \
-                "Disable check with verify_doubled_constant_names configuration option."
+                "Disable check with `verify_doubled_constant_names` configuration option."
+        end
+
+        RSpec::Mocks.configuration.verifying_double_declaration_callbacks.each do |block|
+          block.call(ref)
         end
 
         declare_double(type, ref, *args)

data/lib/rspec/mocks/matchers/have_received.rb

@@ -44,7 +44,7 @@ module RSpec
         end
 
         def description
-          expect.description
+          (@expectation ||= expect).description_for("have received")
         end
 
         CONSTRAINTS.each do |expectation|
@@ -75,11 +75,9 @@ module RSpec
         end
 
         def expect
-          @expectation ||= begin
-            expectation = mock_proxy.build_expectation(@method_name)
-            apply_constraints_to expectation
-            expectation
-          end
+          expectation = mock_proxy.build_expectation(@method_name)
+          apply_constraints_to expectation
+          expectation
         end
 
         def apply_constraints_to(expectation)

data/lib/rspec/mocks/matchers/receive.rb

@@ -15,9 +15,13 @@ module RSpec
           "receive"
         end
 
+        def description
+          describable.description_for("receive")
+        end
+
         def setup_expectation(subject, &block)
           warn_if_any_instance("expect", subject)
-          setup_mock_proxy_method_substitute(subject, :add_message_expectation, block)
+          @describable = setup_mock_proxy_method_substitute(subject, :add_message_expectation, block)
         end
         alias matches? setup_expectation
 
@@ -60,6 +64,10 @@ module RSpec
 
       private
 
+        def describable
+          @describable ||= DefaultDescribable.new(@message)
+        end
+
         def warn_if_any_instance(expression, subject)
           return unless AnyInstance::Proxy === subject
 
@@ -100,6 +108,22 @@ module RSpec
           last.block ||= block
           nil
         end
+
+        # MessageExpectation objects are able to describe themselves in detail.
+        # We use this as a fall back when a MessageExpectation is not available.
+        # @private
+        class DefaultDescribable
+          def initialize(message)
+            @message = message
+          end
+
+          # This is much simpler for the `any_instance` case than what the
+          # user may want, but I'm not up for putting a bunch of effort
+          # into full descriptions for `any_instance` expectations at this point :(.
+          def description_for(verb)
+            "#{verb} #{@message}"
+          end
+        end
       end
     end
   end

data/lib/rspec/mocks/matchers/receive_message_chain.rb

@@ -22,6 +22,10 @@ module RSpec
           "receive_message_chain"
         end
 
+        def description
+          "receive message chain #{formatted_chain}"
+        end
+
         def setup_allowance(subject, &block)
           chain = StubChain.stub_chain_on(subject, *@chain, &(@block || block))
           replay_customizations(chain)
@@ -60,6 +64,16 @@ module RSpec
             customization.playback_onto(chain)
           end
         end
+
+        def formatted_chain
+          @formatted_chain ||= @chain.map do |part|
+            if Hash === part
+              part.keys.first.to_s
+            else
+              part.to_s
+            end
+          end.join(".")
+        end
       end
     end
   end

data/lib/rspec/mocks/matchers/receive_messages.rb

@@ -12,6 +12,10 @@ module RSpec
           "receive_messages"
         end
 
+        def description
+          "receive messages: #{@message_return_value_hash.inspect}"
+        end
+
         def setup_expectation(subject)
           warn_about_block if block_given?
           each_message_on(proxy_on(subject)) do |host, message, return_value|

data/lib/rspec/mocks/message_expectation.rb

@@ -34,47 +34,11 @@ module RSpec
       end
     end
 
-    # @private
+    # Represents an individual method stub or message expectation. The methods
+    # defined here can be used to configure how it behaves. The methods return
+    # `self` so that they can be chained together to form a fluent interface.
     class MessageExpectation
-      # @private
-      attr_accessor :error_generator, :implementation
-      attr_reader :message
-      attr_reader :orig_object
-      attr_writer :expected_received_count, :expected_from, :argument_list_matcher
-      protected :expected_received_count=, :expected_from=, :error_generator, :error_generator=, :implementation=
-
-      # rubocop:disable Style/ParameterLists
-      # @private
-      def initialize(error_generator, expectation_ordering, expected_from, method_double,
-                     type=:expectation, opts={}, &implementation_block)
-        @error_generator = error_generator
-        @error_generator.opts = opts
-        @expected_from = expected_from
-        @method_double = method_double
-        @orig_object = @method_double.object
-        @message = @method_double.method_name
-        @actual_received_count = 0
-        @expected_received_count = type == :expectation ? 1 : :any
-        @argument_list_matcher = ArgumentListMatcher::MATCH_ALL
-        @order_group = expectation_ordering
-        @order_group.register(self) unless type == :stub
-        @expectation_type = type
-        @ordered = false
-        @at_least = @at_most = @exactly = nil
-        @args_to_yield = []
-        @failed_fast = nil
-        @eval_context = nil
-        @yield_receiver_to_implementation_block = false
-
-        @implementation = Implementation.new
-        self.inner_implementation_action = implementation_block
-      end
-      # rubocop:enable Style/ParameterLists
-
-      # @private
-      def expected_args
-        @argument_list_matcher.expected_args
-      end
+      # @!group Configuring Responses
 
       # @overload and_return(value)
       # @overload and_return(first_value, second_value)
@@ -87,8 +51,8 @@ module RSpec
       # If the message is received more times than there are values, the last
       # value is received for every subsequent call.
       #
+      # @return [nil] No further chaining is supported after this.
       # @example
-      #
       #   allow(counter).to receive(:count).and_return(1)
       #   counter.count # => 1
       #   counter.count # => 1
@@ -101,6 +65,7 @@ module RSpec
       #   counter.count # => 3
       #   # etc
       def and_return(first_value, *values)
+        raise_already_invoked_error_if_necessary(__method__)
         if negative?
           raise "`and_return` is not supported with negative message expectations"
         end
@@ -116,22 +81,13 @@ module RSpec
         nil
       end
 
-      def and_yield_receiver_to_implementation
-        @yield_receiver_to_implementation_block = true
-        self
-      end
-
-      def yield_receiver_to_implementation_block?
-        @yield_receiver_to_implementation_block
-      end
-
       # Tells the object to delegate to the original unmodified method
       # when it receives the message.
       #
       # @note This is only available on partial doubles.
       #
+      # @return [nil] No further chaining is supported after this.
       # @example
-      #
       #   expect(counter).to receive(:increment).and_call_original
       #   original_count = counter.count
       #   counter.increment
@@ -149,12 +105,11 @@ module RSpec
       #
       # @note This is only available on partial doubles.
       #
+      # @return [nil] No further chaining is supported after this.
       # @example
-      #
       #   expect(api).to receive(:large_list).and_wrap_original do |original_method, *args, &block|
       #     original_method.call(*args, &block).first(10)
       #   end
-      #
       def and_wrap_original(&block)
         if RSpec::Mocks::TestDouble === @method_double.object
           @error_generator.raise_only_valid_on_a_partial_double(:and_call_original)
@@ -163,6 +118,8 @@ module RSpec
           @implementation = AndWrapOriginalImplementation.new(@method_double.original_method, block)
           @yield_receiver_to_implementation_block = false
         end
+
+        nil
       end
 
       # @overload and_raise
@@ -172,8 +129,8 @@ module RSpec
       #
       # Tells the object to raise an exception when the message is received.
       #
+      # @return [nil] No further chaining is supported after this.
       # @note
-      #
       #   When you pass an exception class, the MessageExpectation will raise
       #   an instance of it, creating it with `exception` and passing `message`
       #   if specified.  If the exception class initializer requires more than
@@ -181,12 +138,12 @@ module RSpec
       #   otherwise this method will raise an ArgumentError exception.
       #
       # @example
-      #
       #   allow(car).to receive(:go).and_raise
       #   allow(car).to receive(:go).and_raise(OutOfGas)
       #   allow(car).to receive(:go).and_raise(OutOfGas, "At least 2 oz of gas needed to drive")
       #   allow(car).to receive(:go).and_raise(OutOfGas.new(2, :oz))
       def and_raise(exception=RuntimeError, message=nil)
+        raise_already_invoked_error_if_necessary(__method__)
         if exception.respond_to?(:exception)
           exception = message ? exception.exception(message) : exception.exception
         end
@@ -201,11 +158,12 @@ module RSpec
       # Tells the object to throw a symbol (with the object if that form is
       # used) when the message is received.
       #
+      # @return [nil] No further chaining is supported after this.
       # @example
-      #
       #   allow(car).to receive(:go).and_throw(:out_of_gas)
       #   allow(car).to receive(:go).and_throw(:out_of_gas, :level => 0.1)
       def and_throw(*args)
+        raise_already_invoked_error_if_necessary(__method__)
         self.terminal_implementation_action = Proc.new { throw(*args) }
         nil
       end
@@ -213,167 +171,28 @@ module RSpec
       # Tells the object to yield one or more args to a block when the message
       # is received.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   stream.stub(:open).and_yield(StringIO.new)
       def and_yield(*args, &block)
+        raise_already_invoked_error_if_necessary(__method__)
         yield @eval_context = Object.new if block
         @args_to_yield << args
         self.initial_implementation_action = AndYieldImplementation.new(@args_to_yield, @eval_context, @error_generator)
         self
       end
+      # @!endgroup
 
-      # @private
-      def matches?(message, *args)
-        @message == message && @argument_list_matcher.args_match?(*args)
-      end
-
-      # @private
-      def safe_invoke(parent_stub, *args, &block)
-        invoke_incrementing_actual_calls_by(1, false, parent_stub, *args, &block)
-      end
-
-      # @private
-      def invoke(parent_stub, *args, &block)
-        invoke_incrementing_actual_calls_by(1, true, parent_stub, *args, &block)
-      end
-
-      # @private
-      def invoke_without_incrementing_received_count(parent_stub, *args, &block)
-        invoke_incrementing_actual_calls_by(0, true, parent_stub, *args, &block)
-      end
-
-      # @private
-      def negative?
-        @expected_received_count == 0 && !@at_least
-      end
-
-      # @private
-      def called_max_times?
-        @expected_received_count != :any &&
-          !@at_least &&
-          @expected_received_count > 0 &&
-          @actual_received_count >= @expected_received_count
-      end
-
-      # @private
-      def matches_name_but_not_args(message, *args)
-        @message == message && !@argument_list_matcher.args_match?(*args)
-      end
-
-      # @private
-      def verify_messages_received
-        InsertOntoBacktrace.line(@expected_from) do
-          generate_error unless expected_messages_received? || failed_fast?
-        end
-      end
-
-      # @private
-      def expected_messages_received?
-        ignoring_args? || matches_exact_count? || matches_at_least_count? || matches_at_most_count?
-      end
-
-      def ensure_expected_ordering_received!
-        @order_group.verify_invocation_order(self) if @ordered
-        true
-      end
-
-      # @private
-      def ignoring_args?
-        @expected_received_count == :any
-      end
-
-      # @private
-      def matches_at_least_count?
-        @at_least && @actual_received_count >= @expected_received_count
-      end
-
-      # @private
-      def matches_at_most_count?
-        @at_most && @actual_received_count <= @expected_received_count
-      end
-
-      # @private
-      def matches_exact_count?
-        @expected_received_count == @actual_received_count
-      end
-
-      # @private
-      def similar_messages
-        @similar_messages ||= []
-      end
-
-      # @private
-      def advise(*args)
-        similar_messages << args
-      end
-
-      # @private
-      def generate_error
-        if similar_messages.empty?
-          @error_generator.raise_expectation_error(@message, @expected_received_count, @argument_list_matcher, @actual_received_count, expectation_count_type, *expected_args)
-        else
-          @error_generator.raise_similar_message_args_error(self, *@similar_messages)
-        end
-      end
-
-      def expectation_count_type
-        return :at_least if @at_least
-        return :at_most if @at_most
-        nil
-      end
-
-      # @private
-      def description
-        @error_generator.describe_expectation(@message, @expected_received_count, @actual_received_count, *expected_args)
-      end
-
-      def raise_out_of_order_error
-        @error_generator.raise_out_of_order_error @message
-      end
-
-      # Constrains a stub or message expectation to invocations with specific
-      # arguments.
-      #
-      # With a stub, if the message might be received with other args as well,
-      # you should stub a default value first, and then stub or mock the same
-      # message using `with` to constrain to specific arguments.
-      #
-      # A message expectation will fail if the message is received with different
-      # arguments.
-      #
-      # @example
-      #
-      #   allow(cart).to receive(:add) { :failure }
-      #   allow(cart).to receive(:add).with(Book.new(:isbn => 1934356379)) { :success }
-      #   cart.add(Book.new(:isbn => 1234567890))
-      #   # => :failure
-      #   cart.add(Book.new(:isbn => 1934356379))
-      #   # => :success
-      #
-      #   expect(cart).to receive(:add).with(Book.new(:isbn => 1934356379)) { :success }
-      #   cart.add(Book.new(:isbn => 1234567890))
-      #   # => failed expectation
-      #   cart.add(Book.new(:isbn => 1934356379))
-      #   # => passes
-      def with(*args, &block)
-        if args.empty?
-          raise ArgumentError,
-                "`with` must have at least one argument. Use `no_args` matcher to set the expectation of receiving no arguments."
-        end
-
-        self.inner_implementation_action = block
-        @argument_list_matcher = ArgumentListMatcher.new(*args)
-        self
-      end
+      # @!group Constraining Receive Counts
 
       # Constrain a message expectation to be received a specific number of
       # times.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(dealer).to receive(:deal_card).exactly(10).times
       def exactly(n, &block)
+        raise_already_invoked_error_if_necessary(__method__)
         self.inner_implementation_action = block
         set_expected_received_count :exactly, n
         self
@@ -382,10 +201,11 @@ module RSpec
       # Constrain a message expectation to be received at least a specific
       # number of times.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(dealer).to receive(:deal_card).at_least(9).times
       def at_least(n, &block)
+        raise_already_invoked_error_if_necessary(__method__)
         set_expected_received_count :at_least, n
 
         if n == 0
@@ -400,10 +220,11 @@ module RSpec
       # Constrain a message expectation to be received at most a specific
       # number of times.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(dealer).to receive(:deal_card).at_most(10).times
       def at_most(n, &block)
+        raise_already_invoked_error_if_necessary(__method__)
         self.inner_implementation_action = block
         set_expected_received_count :at_most, n
         self
@@ -411,8 +232,8 @@ module RSpec
 
       # Syntactic sugar for `exactly`, `at_least` and `at_most`
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(dealer).to receive(:deal_card).exactly(10).times
       #   expect(dealer).to receive(:deal_card).at_least(10).times
       #   expect(dealer).to receive(:deal_card).at_most(10).times
@@ -423,8 +244,8 @@ module RSpec
 
       # Expect a message not to be received at all.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(car).to receive(:stop).never
       def never
         ErrorGenerator.raise_double_negation_error("expect(obj)") if negative?
@@ -434,8 +255,8 @@ module RSpec
 
       # Expect a message to be received exactly one time.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(car).to receive(:go).once
       def once(&block)
         self.inner_implementation_action = block
@@ -445,8 +266,8 @@ module RSpec
 
       # Expect a message to be received exactly two times.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(car).to receive(:go).twice
       def twice(&block)
         self.inner_implementation_action = block
@@ -456,19 +277,58 @@ module RSpec
 
       # Expect a message to be received exactly three times.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
-      #
       #   expect(car).to receive(:go).thrice
       def thrice(&block)
         self.inner_implementation_action = block
         set_expected_received_count :exactly, 3
         self
       end
+      # @!endgroup
 
-      # Expect messages to be received in a specific order.
+      # @!group Other Constraints
+
+      # Constrains a stub or message expectation to invocations with specific
+      # arguments.
+      #
+      # With a stub, if the message might be received with other args as well,
+      # you should stub a default value first, and then stub or mock the same
+      # message using `with` to constrain to specific arguments.
+      #
+      # A message expectation will fail if the message is received with different
+      # arguments.
       #
+      # @return [MessageExpecation] self, to support further chaining.
       # @example
+      #   allow(cart).to receive(:add) { :failure }
+      #   allow(cart).to receive(:add).with(Book.new(:isbn => 1934356379)) { :success }
+      #   cart.add(Book.new(:isbn => 1234567890))
+      #   # => :failure
+      #   cart.add(Book.new(:isbn => 1934356379))
+      #   # => :success
+      #
+      #   expect(cart).to receive(:add).with(Book.new(:isbn => 1934356379)) { :success }
+      #   cart.add(Book.new(:isbn => 1234567890))
+      #   # => failed expectation
+      #   cart.add(Book.new(:isbn => 1934356379))
+      #   # => passes
+      def with(*args, &block)
+        raise_already_invoked_error_if_necessary(__method__)
+        if args.empty?
+          raise ArgumentError,
+                "`with` must have at least one argument. Use `no_args` matcher to set the expectation of receiving no arguments."
+        end
+
+        self.inner_implementation_action = block
+        @argument_list_matcher = ArgumentListMatcher.new(*args)
+        self
+      end
+
+      # Expect messages to be received in a specific order.
       #
+      # @return [MessageExpecation] self, to support further chaining.
+      # @example
       #   expect(api).to receive(:prepare).ordered
       #   expect(api).to receive(:run).ordered
       #   expect(api).to receive(:finish).ordered
@@ -482,93 +342,264 @@ module RSpec
       end
 
       # @private
-      def additional_expected_calls
-        return 0 if @expectation_type == :stub || !@exactly
-        @expected_received_count - 1
-      end
+      # Contains the parts of `MessageExpecation` that aren't part of
+      # rspec-mocks' public API. The class is very big and could really use
+      # some collaborators it delegates to for this stuff but for now this was
+      # the simplest way to split the public from private stuff to make it
+      # easier to publish the docs for the APIs we want published.
+      module ImplementationDetails
+        attr_accessor :error_generator, :implementation
+        attr_reader :message
+        attr_reader :orig_object
+        attr_writer :expected_received_count, :expected_from, :argument_list_matcher
+        protected :expected_received_count=, :expected_from=, :error_generator, :error_generator=, :implementation=
+
+        # rubocop:disable Style/ParameterLists
+        def initialize(error_generator, expectation_ordering, expected_from, method_double,
+                       type=:expectation, opts={}, &implementation_block)
+          @error_generator = error_generator
+          @error_generator.opts = opts
+          @expected_from = expected_from
+          @method_double = method_double
+          @orig_object = @method_double.object
+          @message = @method_double.method_name
+          @actual_received_count = 0
+          @expected_received_count = type == :expectation ? 1 : :any
+          @argument_list_matcher = ArgumentListMatcher::MATCH_ALL
+          @order_group = expectation_ordering
+          @order_group.register(self) unless type == :stub
+          @expectation_type = type
+          @ordered = false
+          @at_least = @at_most = @exactly = nil
+          @args_to_yield = []
+          @failed_fast = nil
+          @eval_context = nil
+          @yield_receiver_to_implementation_block = false
 
-      # @private
-      def ordered?
-        @ordered
-      end
+          @implementation = Implementation.new
+          self.inner_implementation_action = implementation_block
+        end
+        # rubocop:enable Style/ParameterLists
 
-      # @private
-      def negative_expectation_for?(message)
-        @message == message && negative?
-      end
+        def expected_args
+          @argument_list_matcher.expected_args
+        end
 
-      # @private
-      def actual_received_count_matters?
-        @at_least || @at_most || @exactly
-      end
+        def and_yield_receiver_to_implementation
+          @yield_receiver_to_implementation_block = true
+          self
+        end
 
-      # @private
-      def increase_actual_received_count!
-        @actual_received_count += 1
-      end
+        def yield_receiver_to_implementation_block?
+          @yield_receiver_to_implementation_block
+        end
 
-    private
+        def matches?(message, *args)
+          @message == message && @argument_list_matcher.args_match?(*args)
+        end
+
+        def safe_invoke(parent_stub, *args, &block)
+          invoke_incrementing_actual_calls_by(1, false, parent_stub, *args, &block)
+        end
+
+        def invoke(parent_stub, *args, &block)
+          invoke_incrementing_actual_calls_by(1, true, parent_stub, *args, &block)
+        end
+
+        def invoke_without_incrementing_received_count(parent_stub, *args, &block)
+          invoke_incrementing_actual_calls_by(0, true, parent_stub, *args, &block)
+        end
 
-      def invoke_incrementing_actual_calls_by(increment, allowed_to_fail, parent_stub, *args, &block)
-        args.unshift(orig_object) if yield_receiver_to_implementation_block?
+        def negative?
+          @expected_received_count == 0 && !@at_least
+        end
 
-        if negative? || (allowed_to_fail && (@exactly || @at_most) && (@actual_received_count == @expected_received_count))
-          @actual_received_count += increment
-          @failed_fast = true
-          # args are the args we actually received, @argument_list_matcher is the
-          # list of args we were expecting
-          @error_generator.raise_expectation_error(@message, @expected_received_count, @argument_list_matcher, @actual_received_count, expectation_count_type, *args)
+        def called_max_times?
+          @expected_received_count != :any &&
+            !@at_least &&
+            @expected_received_count > 0 &&
+            @actual_received_count >= @expected_received_count
         end
 
-        @order_group.handle_order_constraint self
+        def matches_name_but_not_args(message, *args)
+          @message == message && !@argument_list_matcher.args_match?(*args)
+        end
 
-        begin
-          if implementation.present?
-            implementation.call(*args, &block)
-          elsif parent_stub
-            parent_stub.invoke(nil, *args, &block)
+        def verify_messages_received
+          InsertOntoBacktrace.line(@expected_from) do
+            generate_error unless expected_messages_received? || failed_fast?
           end
-        ensure
-          @actual_received_count += increment
         end
-      end
 
-      def failed_fast?
-        @failed_fast
-      end
+        def expected_messages_received?
+          ignoring_args? || matches_exact_count? || matches_at_least_count? || matches_at_most_count?
+        end
 
-      def set_expected_received_count(relativity, n)
-        @at_least = (relativity == :at_least)
-        @at_most  = (relativity == :at_most)
-        @exactly  = (relativity == :exactly)
-        @expected_received_count = case n
-                                   when Numeric then n
-                                   when :once   then 1
-                                   when :twice  then 2
-                                   when :thrice then 3
-                                   end
-      end
+        def ensure_expected_ordering_received!
+          @order_group.verify_invocation_order(self) if @ordered
+          true
+        end
 
-      def initial_implementation_action=(action)
-        implementation.initial_action = action
-      end
+        def ignoring_args?
+          @expected_received_count == :any
+        end
 
-      def inner_implementation_action=(action)
-        return unless action
-        warn_about_stub_override if implementation.inner_action
-        implementation.inner_action = action
-      end
+        def matches_at_least_count?
+          @at_least && @actual_received_count >= @expected_received_count
+        end
 
-      def terminal_implementation_action=(action)
-        implementation.terminal_action = action
-      end
+        def matches_at_most_count?
+          @at_most && @actual_received_count <= @expected_received_count
+        end
+
+        def matches_exact_count?
+          @expected_received_count == @actual_received_count
+        end
+
+        def similar_messages
+          @similar_messages ||= []
+        end
+
+        def advise(*args)
+          similar_messages << args
+        end
+
+        def generate_error
+          if similar_messages.empty?
+            @error_generator.raise_expectation_error(@message, @expected_received_count, @argument_list_matcher, @actual_received_count, expectation_count_type, *expected_args)
+          else
+            @error_generator.raise_similar_message_args_error(self, *@similar_messages)
+          end
+        end
+
+        def expectation_count_type
+          return :at_least if @at_least
+          return :at_most if @at_most
+          nil
+        end
+
+        def description_for(verb)
+          @error_generator.describe_expectation(
+            verb, @message, @expected_received_count,
+            @actual_received_count, *expected_args
+          )
+        end
+
+        def raise_out_of_order_error
+          @error_generator.raise_out_of_order_error @message
+        end
+
+        def additional_expected_calls
+          return 0 if @expectation_type == :stub || !@exactly
+          @expected_received_count - 1
+        end
+
+        def ordered?
+          @ordered
+        end
+
+        def negative_expectation_for?(message)
+          @message == message && negative?
+        end
+
+        def actual_received_count_matters?
+          @at_least || @at_most || @exactly
+        end
 
-      def warn_about_stub_override
-        RSpec.warning(
-          "You're overriding a previous stub implementation of `#{@message}`. " \
-          "Called from #{CallerFilter.first_non_rspec_line}."
-        )
+        def increase_actual_received_count!
+          @actual_received_count += 1
+        end
+
+        def fail_if_problematic_received_arg_mutations(received_arg_list)
+          return if @argument_list_matcher == ArgumentListMatcher::MATCH_ALL
+          return unless received_arg_list.has_mutations?
+
+          raise CannotSupportArgMutationsError,
+                "`have_received(...).with(...)` cannot be used when received " \
+                "message args have later been mutated. You can use a normal " \
+                "message expectation (`expect(...).to receive(...).with(...)`) " \
+                "instead."
+        end
+
+      private
+
+        def invoke_incrementing_actual_calls_by(increment, allowed_to_fail, parent_stub, *args, &block)
+          args.unshift(orig_object) if yield_receiver_to_implementation_block?
+
+          if negative? || (allowed_to_fail && (@exactly || @at_most) && (@actual_received_count == @expected_received_count))
+            @actual_received_count += increment
+            @failed_fast = true
+            # args are the args we actually received, @argument_list_matcher is the
+            # list of args we were expecting
+            @error_generator.raise_expectation_error(@message, @expected_received_count, @argument_list_matcher, @actual_received_count, expectation_count_type, *args)
+          end
+
+          @order_group.handle_order_constraint self
+
+          begin
+            if implementation.present?
+              implementation.call(*args, &block)
+            elsif parent_stub
+              parent_stub.invoke(nil, *args, &block)
+            end
+          ensure
+            @actual_received_count += increment
+          end
+        end
+
+        def has_been_invoked?
+          @actual_received_count > 0
+        end
+
+        def raise_already_invoked_error_if_necessary(calling_customization)
+          return unless has_been_invoked?
+
+          error_message = "The message expectation for #{orig_object.inspect}.#{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."
+
+          raise MockExpectationAlreadyInvokedError, error_message
+        end
+
+        def failed_fast?
+          @failed_fast
+        end
+
+        def set_expected_received_count(relativity, n)
+          @at_least = (relativity == :at_least)
+          @at_most  = (relativity == :at_most)
+          @exactly  = (relativity == :exactly)
+          @expected_received_count = case n
+                                     when Numeric then n
+                                     when :once   then 1
+                                     when :twice  then 2
+                                     when :thrice then 3
+                                     end
+        end
+
+        def initial_implementation_action=(action)
+          implementation.initial_action = action
+        end
+
+        def inner_implementation_action=(action)
+          return unless action
+          warn_about_stub_override if implementation.inner_action
+          implementation.inner_action = action
+        end
+
+        def terminal_implementation_action=(action)
+          implementation.terminal_action = action
+        end
+
+        def warn_about_stub_override
+          RSpec.warning(
+            "You're overriding a previous stub implementation of `#{@message}`. " \
+            "Called from #{CallerFilter.first_non_rspec_line}."
+          )
+        end
       end
+
+      include ImplementationDetails
     end
 
     # Handles the implementation of an `and_yield` declaration.