rspec-mocks 3.0.4 → 3.12.6

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)
       #
@@ -24,7 +24,6 @@ module RSpec
       # hash of message/return-value pairs.
       #
       # @example
-      #
       #   book = double("book", :title => "The RSpec Book")
       #   book.title #=> "The RSpec Book"
       #
@@ -38,9 +37,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 +60,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 +83,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
@@ -84,11 +104,100 @@ module RSpec
         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
@@ -110,7 +219,6 @@ module RSpec
       # @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.
       #
@@ -130,7 +238,7 @@ module RSpec
       #   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 = {})
+      def stub_const(constant_name, value, options={})
         ConstantMutator.stub(constant_name, value, options)
       end
 
@@ -144,15 +252,15 @@ module RSpec
       #   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. The method must have previously been stubbed in
-      # order for messages to be verified.
+      # 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.
@@ -161,23 +269,36 @@ module RSpec
       #   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,
@@ -190,7 +311,6 @@ module RSpec
       # 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.
@@ -200,7 +320,6 @@ module RSpec
       # 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.
@@ -210,7 +329,6 @@ module RSpec
       # 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.
@@ -223,7 +341,6 @@ module RSpec
       # 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.
@@ -236,7 +353,6 @@ module RSpec
       # interface.
       #
       # @example
-      #
       #   allow(obj).to receive_messages(:speak => "Hello World")
       #   allow(obj).to receive_messages(:speak => "Hello", :meow => "Meow")
       #
@@ -260,16 +376,15 @@ module RSpec
       # 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 }
       #
-      #     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
+      #   # 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] }
+      #   # 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.
 
@@ -277,20 +392,28 @@ module RSpec
       def self.included(klass)
         klass.class_exec do
           # This gets mixed in so that if `RSpec::Matchers` is included in
-          # `klass` later, it's definition of `expect` will take precedence.
+          # `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?
 
-          raise VerifyingDoubleNotDefinedError,
-            "#{ref.description} is not a defined constant. " +
-            "Perhaps you misspelt it? " +
-            "Disable check with verify_doubled_constant_names configuration option."
+          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)

data/lib/rspec/mocks/instance_method_stasher.rb

@@ -31,7 +31,6 @@ module RSpec
         def stashed_method_name
           "obfuscated_by_rspec_mocks__#{@method}"
         end
-        private :stashed_method_name
 
         # @private
         def restore
@@ -53,8 +52,9 @@ module RSpec
 
         # @private
         def stash
-          return if !method_defined_directly_on_klass?
+          return unless method_defined_directly_on_klass?
           @original_method ||= ::RSpec::Support.method_handle_for(@object, @method)
+          @klass.__send__(:undef_method, @method)
         end
 
         # @private
@@ -80,9 +80,9 @@ module RSpec
           yield
         rescue TypeError
           RSpec.warn_with(
-            "RSpec failed to properly restore a partial double (#{@object.inspect}) " +
-            "to its original state due to a known bug in MRI 2.0.0-p195 & p247 " +
-            "(https://bugs.ruby-lang.org/issues/8686). This object may remain " +
+            "RSpec failed to properly restore a partial double (#{@object.inspect}) " \
+            "to its original state due to a known bug in MRI 2.0.0-p195 & p247 " \
+            "(https://bugs.ruby-lang.org/issues/8686). This object may remain " \
             "screwed up for the rest of this process. Please upgrade to 2.0.0-p353 or above.",
             :call_site => nil, :use_spec_location_as_call_site => true
           )
@@ -102,7 +102,7 @@ module RSpec
       end
 
       # @private
-      def method_defined_on_klass?(klass = @klass)
+      def method_defined_on_klass?(klass=@klass)
         MethodReference.method_defined_at_any_visibility?(klass, @method)
       end
 
@@ -128,6 +128,17 @@ module RSpec
         # Hence, we verify that the owner actually has the method defined.
         # If the given owner does not have the method defined, we assume
         # that the method is actually owned by @klass.
+        #
+        # On 1.8, aliased methods can also report the wrong owner. Example:
+        # module M
+        #   def a; end
+        #   module_function :a
+        #   alias b a
+        #   module_function :b
+        # end
+        # The owner of M.b is the raw Module object, instead of the expected
+        # singleton class of the module
+        return true if RUBY_VERSION < '1.9' && owner == @object
         owner == @klass || !(method_defined_on_klass?(owner))
       end
     end

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

@@ -3,9 +3,11 @@ module RSpec
     module Matchers
       # @private
       class HaveReceived
-        COUNT_CONSTRAINTS = %w(exactly at_least at_most times once twice)
-        ARGS_CONSTRAINTS = %w(with)
-        CONSTRAINTS = COUNT_CONSTRAINTS + ARGS_CONSTRAINTS + %w(ordered)
+        include Matcher
+
+        COUNT_CONSTRAINTS = %w[exactly at_least at_most times time once twice thrice]
+        ARGS_CONSTRAINTS = %w[with]
+        CONSTRAINTS = COUNT_CONSTRAINTS + ARGS_CONSTRAINTS + %w[ordered]
 
         def initialize(method_name, &block)
           @method_name = method_name
@@ -14,7 +16,7 @@ module RSpec
           @subject = nil
         end
 
-        def name
+        def matcher_name
           "have_received"
         end
 
@@ -36,15 +38,15 @@ module RSpec
         end
 
         def failure_message
-          generate_failure_message
+          capture_failure_message
         end
 
         def failure_message_when_negated
-          generate_failure_message
+          capture_failure_message
         end
 
         def description
-          expect.description
+          (@expectation ||= expect).description_for("have received")
         end
 
         CONSTRAINTS.each do |expectation|
@@ -54,14 +56,40 @@ module RSpec
           end
         end
 
+        def setup_expectation(subject, &block)
+          notify_failure_message unless matches?(subject, &block)
+        end
+
+        def setup_negative_expectation(subject, &block)
+          notify_failure_message unless does_not_match?(subject, &block)
+        end
+
+        def setup_allowance(_subject, &_block)
+          disallow("allow", " as it would have no effect")
+        end
+
+        def setup_any_instance_allowance(_subject, &_block)
+          disallow("allow_any_instance_of")
+        end
+
+        def setup_any_instance_expectation(_subject, &_block)
+          disallow("expect_any_instance_of")
+        end
+
+        def setup_any_instance_negative_expectation(_subject, &_block)
+          disallow("expect_any_instance_of")
+        end
+
       private
 
+        def disallow(type, reason="")
+          RSpec::Mocks.error_generator.raise_have_received_disallowed(type, reason)
+        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)
@@ -71,23 +99,25 @@ module RSpec
         end
 
         def ensure_count_unconstrained
-          if count_constraint
-            raise RSpec::Mocks::MockExpectationError,
-              "can't use #{count_constraint} when negative"
-          end
+          return unless count_constraint
+          RSpec::Mocks.error_generator.raise_cant_constrain_count_for_negated_have_received_error(count_constraint)
         end
 
         def count_constraint
-          @constraints.map(&:first).detect do |constraint|
+          @constraints.map(&:first).find do |constraint|
             COUNT_CONSTRAINTS.include?(constraint)
           end
         end
 
-        def generate_failure_message
+        def capture_failure_message
+          RSpec::Support.with_failure_notifier(Proc.new { |err, _opt| return err.message }) do
+            notify_failure_message
+          end
+        end
+
+        def notify_failure_message
           mock_proxy.check_for_unexpected_arguments(@expectation)
           @expectation.generate_error
-        rescue RSpec::Mocks::MockExpectationError => error
-          error.message
         end
 
         def expected_messages_received_in_order?

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

@@ -5,19 +5,25 @@ module RSpec
     module Matchers
       # @private
       class Receive
+        include Matcher
+
         def initialize(message, block)
           @message                 = message
           @block                   = block
           @recorded_customizations = []
         end
 
-        def name
+        def matcher_name
           "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
 
@@ -49,26 +55,32 @@ module RSpec
           setup_any_instance_method_substitute(subject, :stub, block)
         end
 
+        own_methods = (instance_methods - superclass.instance_methods)
         MessageExpectation.public_instance_methods(false).each do |method|
-          next if method_defined?(method)
+          next if own_methods.include?(method)
 
           define_method(method) do |*args, &block|
             @recorded_customizations << ExpectationCustomization.new(method, args, block)
             self
           end
+          ruby2_keywords(method) if respond_to?(:ruby2_keywords, true)
         end
 
       private
 
+        def describable
+          @describable ||= DefaultDescribable.new(@message)
+        end
+
         def warn_if_any_instance(expression, subject)
-          if AnyInstance::Proxy === subject
-            RSpec.warning(
-              "`#{expression}(#{subject.klass}.any_instance).to` " <<
-              "is probably not what you meant, it does not operate on " <<
-              "any instance of `#{subject.klass}`. " <<
-              "Use `#{expression}_any_instance_of(#{subject.klass}).to` instead."
-            )
-          end
+          return unless AnyInstance::Proxy === subject
+
+          RSpec.warning(
+            "`#{expression}(#{subject.klass}.any_instance).to` " \
+            "is probably not what you meant, it does not operate on " \
+            "any instance of `#{subject.klass}`. " \
+            "Use `#{expression}_any_instance_of(#{subject.klass}).to` instead."
+          )
         end
 
         def setup_mock_proxy_method_substitute(subject, method, block)
@@ -100,6 +112,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

@@ -5,23 +5,29 @@ module RSpec
     module Matchers
       # @private
       class ReceiveMessageChain
+        include Matcher
+
         def initialize(chain, &block)
           @chain = chain
           @block = block
           @recorded_customizations  = []
         end
 
-        [:with, :and_return, :and_throw, :and_raise, :and_yield, :and_call_original].each do |msg|
+        [:with, :and_return, :and_invoke, :and_throw, :and_raise, :and_yield, :and_call_original].each do |msg|
           define_method(msg) do |*args, &block|
             @recorded_customizations << ExpectationCustomization.new(msg, args, block)
             self
           end
         end
 
-        def name
+        def matcher_name
           "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)
@@ -44,11 +50,10 @@ module RSpec
           replay_customizations(chain)
         end
 
-        def setup_negative_expectation(*args)
-          raise NegationUnsupportedError.new(
-            "`expect(...).not_to receive_message_chain` is not supported " +
-            "since it doesn't really make sense. What would it even mean?"
-          )
+        def setup_negative_expectation(*_args)
+          raise NegationUnsupportedError,
+                "`expect(...).not_to receive_message_chain` is not supported " \
+                "since it doesn't really make sense. What would it even mean?"
         end
 
         alias matches? setup_expectation
@@ -61,6 +66,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