rspec-mocks 3.0.0.beta2 → 3.0.0.rc1

data/lib/rspec/mocks/configuration.rb

@@ -14,6 +14,18 @@ module RSpec
         @yield_receiver_to_any_instance_implementation_blocks
       end
 
+      # Sets whether or not RSpec will yield the receiving instance of a
+      # message to blocks that are used for any_instance stub implementations.
+      # When set, the first yielded argument will be the receiving instance.
+      # Defaults to `true`.
+      #
+      # @example
+      #
+      #   RSpec.configure do |rspec|
+      #     rspec.mock_with :rspc do |mocks|
+      #       mocks.yield_receiver_to_any_instance_implementation_blocks = false
+      #     end
+      #   end
       def yield_receiver_to_any_instance_implementation_blocks=(arg)
         @yield_receiver_to_any_instance_implementation_blocks = arg
       end
@@ -118,6 +130,21 @@ module RSpec
         @verify_partial_doubles
       end
 
+      # Monkey-patch `Marshal.dump` to enable dumping of mocked or stubbed
+      # objects. By default this will not work since RSpec mocks works by
+      # adding singleton methods that cannot be serialized. This patch removes
+      # these singleton methods before serialization. Setting to falsey removes
+      # the patch.
+      #
+      # This method is idempotent.
+      def patch_marshal_to_support_partial_doubles=(val)
+        if val
+          RSpec::Mocks::MarshalExtension.patch!
+        else
+          RSpec::Mocks::MarshalExtension.unpatch!
+        end
+      end
+
       # @api private
       # Resets the configured syntax to the default.
       def reset_syntaxes_to_default
@@ -126,6 +153,8 @@ module RSpec
       end
     end
 
+    # Mocks specific configuration, as distinct from `RSpec.configuration`
+    # which is core RSpec configuration.
     def self.configuration
       @configuration ||= Configuration.new
     end

data/lib/rspec/mocks/error_generator.rb

@@ -1,15 +1,12 @@
 module RSpec
   module Mocks
-    # @public
     # Raised when a message expectation is not satisfied.
     MockExpectationError = Class.new(Exception)
 
-    # @public
     # 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)
 
-    # @public
     # Raised when doubles or partial doubles are used outside of the per-test lifecycle.
     OutsideOfExampleError = Class.new(StandardError)
 
@@ -17,7 +14,7 @@ module RSpec
     UnsupportedMatcherError  = Class.new(StandardError)
     # @private
     NegationUnsupportedError = Class.new(StandardError)
-
+    # @private
     VerifyingDoubleNotDefinedError = Class.new(StandardError)
 
     # @private
@@ -69,7 +66,7 @@ module RSpec
 
       # @private
       def raise_unimplemented_error(doubled_module, method_name)
-        __raise "%s does not implement:\n  %s" % [
+        __raise "%s does not implement: %s" % [
           doubled_module.description,
           method_name
         ]

data/lib/rspec/mocks/example_methods.rb

@@ -1,17 +1,22 @@
-require 'rspec/mocks/object_reference'
+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] used to clarify intent
       # @overload double(stubs)
+      #   @param stubs (Hash) hash of message/return-value pairs
       # @overload double(name, stubs)
-      # @param name [String/Symbol] (optional) used in
-      #   clarify intent
-      # @param stubs (Hash) (optional) hash of message/return-value pairs
+      #   @param name [String/Symbol] used to clarify intent
+      #   @param stubs (Hash) hash of message/return-value pairs
       # @return (Double)
       #
       # Constructs an instance of [RSpec::Mocks::Double](RSpec::Mocks::Double) configured
@@ -32,9 +37,10 @@ module RSpec
       end
 
       # @overload instance_double(doubled_class)
+      #   @param doubled_class [String, Class]
       # @overload instance_double(doubled_class, stubs)
-      # @param doubled_class [String, Class]
-      # @param stubs [Hash] (optional) hash of message/return-value pairs
+      #   @param doubled_class [String, Class]
+      #   @param stubs [Hash] hash of message/return-value pairs
       # @return InstanceVerifyingDouble
       #
       # Constructs a test double against a specific class. If the given class
@@ -47,9 +53,10 @@ module RSpec
       end
 
       # @overload class_double(doubled_class)
+      #   @param doubled_class [String, Module]
       # @overload class_double(doubled_class, stubs)
-      # @param doubled_class [String, Module]
-      # @param stubs [Hash] (optional) hash of message/return-value pairs
+      #   @param doubled_class [String, Module]
+      #   @param stubs [Hash] hash of message/return-value pairs
       # @return ClassVerifyingDouble
       #
       # Constructs a test double against a specific class. If the given class
@@ -62,9 +69,10 @@ module RSpec
       end
 
       # @overload object_double(object_or_name)
+      #   @param object_or_name [String, Object]
       # @overload object_double(object_or_name, stubs)
-      # @param object_or_name [String, Object]
-      # @param stubs [Hash] (optional) hash of message/return-value pairs
+      #   @param object_or_name [String, Object]
+      #   @param stubs [Hash] hash of message/return-value pairs
       # @return ObjectVerifyingDouble
       #
       # Constructs a test double against a specific object. Only the methods
@@ -164,7 +172,108 @@ module RSpec
         Matchers::HaveReceived.new(method_name, &block)
       end
 
-      # @api private
+      # @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
+      # `foo.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
@@ -173,7 +282,7 @@ module RSpec
         end
       end
 
-      # @api private
+      # @private
       def self.declare_verifying_double(type, ref, *args)
         if RSpec::Mocks.configuration.verify_doubled_constant_names? &&
           !ref.defined?
@@ -187,7 +296,7 @@ module RSpec
         declare_double(type, ref, *args)
       end
 
-      # @api private
+      # @private
       def self.declare_double(type, *args)
         args << {} unless Hash === args.last
         type.new(*args)

data/lib/rspec/mocks/instance_method_stasher.rb

@@ -65,12 +65,36 @@ module RSpec
             @klass.__send__(:undef_method, @method)
           end
 
-          @klass.__send__(:define_method, @method, @original_method)
+          handle_restoration_failures do
+            @klass.__send__(:define_method, @method, @original_method)
+          end
+
           @original_method = nil
         end
       end
 
-      private
+      if RUBY_DESCRIPTION.include?('2.0.0p247')
+        # ruby 2.0.0-p247 has a bug that we can't work around :(.
+        # https://bugs.ruby-lang.org/issues/8686
+        def handle_restoration_failures
+          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-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
+          )
+        end
+      else
+        def handle_restoration_failures
+          # No known reasons for restoration to fail on other rubies.
+          yield
+        end
+      end
+
+    private
 
       # @private
       def method_defined_directly_on_klass?

data/lib/rspec/mocks/marshal_extension.rb

@@ -0,0 +1,41 @@
+module RSpec
+  module Mocks
+    # Support for `patch_marshal_to_support_partial_doubles` configuration.
+    #
+    # @private
+    class MarshalExtension
+      def self.patch!
+        return if Marshal.respond_to?(:dump_with_rspec_mocks)
+
+        Marshal.instance_eval do
+          class << self
+            def dump_with_rspec_mocks(object, *rest)
+              if !::RSpec::Mocks.space.registered?(object) || NilClass === object
+                dump_without_rspec_mocks(object, *rest)
+              else
+                dump_without_rspec_mocks(object.dup, *rest)
+              end
+            end
+
+            alias_method :dump_without_rspec_mocks, :dump
+            undef_method :dump
+            alias_method :dump, :dump_with_rspec_mocks
+          end
+        end
+      end
+
+      def self.unpatch!
+        return unless Marshal.respond_to?(:dump_with_rspec_mocks)
+
+        Marshal.instance_eval do
+          class << self
+            undef_method :dump_with_rspec_mocks
+            undef_method :dump
+            alias_method :dump, :dump_without_rspec_mocks
+            undef_method :dump_without_rspec_mocks
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module RSpec
+  module Mocks
+    module Matchers
+      # @private
+      class ExpectationCustomization
+        attr_accessor :block
+
+        def initialize(method_name, args, block)
+          @method_name = method_name
+          @args        = args
+          @block       = block
+        end
+
+        def playback_onto(expectation)
+          expectation.__send__(@method_name, *@args, &@block)
+        end
+      end
+    end
+  end
+end

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

@@ -1,3 +1,5 @@
+RSpec::Support.require_rspec_mocks 'matchers/expectation_customization'
+
 module RSpec
   module Mocks
     module Matchers
@@ -7,7 +9,6 @@ module RSpec
           @message                 = message
           @block                   = block
           @recorded_customizations = []
-          @backtrace_line          = CallerFilter.first_non_rspec_line
         end
 
         def name
@@ -60,7 +61,7 @@ module RSpec
       private
 
         def warn_if_any_instance(expression, subject)
-          if AnyInstance::Recorder === subject
+          if AnyInstance::Proxy === subject
             RSpec.warning(
               "`#{expression}(#{subject.klass}.any_instance).to` " <<
               "is probably not what you meant, it does not operate on " <<
@@ -72,12 +73,12 @@ module RSpec
 
         def setup_mock_proxy_method_substitute(subject, method, block)
           proxy = ::RSpec::Mocks.space.proxy_for(subject)
-          setup_method_substitute(proxy, method, block, @backtrace_line)
+          setup_method_substitute(proxy, method, block)
         end
 
         def setup_any_instance_method_substitute(subject, method, block)
-          any_instance_recorder = ::RSpec::Mocks.space.any_instance_recorder_for(subject)
-          setup_method_substitute(any_instance_recorder, method, block)
+          proxy = ::RSpec::Mocks.space.any_instance_proxy_for(subject)
+          setup_method_substitute(proxy, method, block)
         end
 
         def setup_method_substitute(host, method, block, *args)
@@ -101,20 +102,5 @@ module RSpec
         end
       end
     end
-
-    # @private
-    class ExpectationCustomization
-      attr_accessor :block
-
-      def initialize(method_name, args, block)
-        @method_name = method_name
-        @args        = args
-        @block       = block
-      end
-
-      def playback_onto(expectation)
-        expectation.__send__(@method_name, *@args, &@block)
-      end
-    end
   end
 end

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

@@ -1,3 +1,5 @@
+RSpec::Support.require_rspec_mocks 'matchers/expectation_customization'
+
 module RSpec
   module Mocks
     module Matchers
@@ -26,14 +28,14 @@ module RSpec
         end
 
         def setup_any_instance_allowance(subject, &block)
-          recorder = ::RSpec::Mocks.space.any_instance_recorder_for(subject)
-          chain = recorder.stub_chain(*@chain, &(@block || block))
+          proxy = ::RSpec::Mocks.space.any_instance_proxy_for(subject)
+          chain = proxy.stub_chain(*@chain, &(@block || block))
           replay_customizations(chain)
         end
 
         def setup_any_instance_expectation(subject, &block)
-          recorder = ::RSpec::Mocks.space.any_instance_recorder_for(subject)
-          chain = recorder.expect_chain(*@chain, &(@block || block))
+          proxy = ::RSpec::Mocks.space.any_instance_proxy_for(subject)
+          chain = proxy.expect_chain(*@chain, &(@block || block))
           replay_customizations(chain)
         end
 
@@ -52,7 +54,7 @@ module RSpec
         alias matches? setup_expectation
         alias does_not_match? setup_negative_expectation
 
-        private
+      private
 
         def replay_customizations(chain)
           @recorded_customizations.each do |customization|