Creates syntax agnostic matchers for message expectations.

pda · Sam Phippen · commit 0b2e5b2556b1 · 2013-07-03T23:44:32.000+02:00
See pull: #311 and #334. Signed-off-by: Sam Phippen <samphippen@googlemail.com> Conflicts: Changelog.md lib/rspec/mocks/message_expectation.rb spec/rspec/mocks/mock_spec.rb
diff --git a/Changelog.md b/Changelog.md
@@ -1,5 +1,13 @@
 ### Development
 
+Enhancements:
+
+* Document test spies in the readme. (Adarsh Pandit)
+* Add an `array_including` matcher. (Sam Phippen)
+* Create syntax agnostic message matchers enable message allowances and
+  expectations to be set independently of any particular syntax being
+  enabled (Paul Anneesley, Myron Marston and Sam Phippen).
+
 Bug Fixes:
 
 * Bypass RSpec::Mocks::Syntax when mass-assigning stubs via double(). (Paul Annesley)
diff --git a/lib/rspec/mocks.rb b/lib/rspec/mocks.rb
@@ -30,6 +30,41 @@ def any_instance_recorder_for(klass)
         space.any_instance_recorder_for(klass)
       end
 
+      # Adds an allowance (stub) on `subject`
+      #
+      # @param subject the subject to which the message will be added
+      # @param message a symbol, representing the message that will be
+      #                added.
+      # @param opts a hash of options, :expected_from is used to set the
+      #             original call site
+      # @param block an optional implementation for the allowance
+      #
+      # @example Defines the implementation of `foo` on `bar`, using the passed block
+      #   x = 0
+      #   RSpec::Mocks.allow_message(bar, :foo) { x += 1 }
+      def allow_message(subject, message, opts={}, &block)
+        orig_caller = opts.fetch(:expected_from) { caller(1)[0] }
+        ::RSpec::Mocks.proxy_for(subject).
+          add_stub(orig_caller, message.to_sym, opts, &block)
+      end
+
+      # Sets a message expectation on `subject`.
+      # @param subject the subject on which the message will be expected
+      # @param message a symbol, representing the message that will be
+      #                expected.
+      # @param opts a hash of options, :expected_from is used to set the
+      #             original call site
+      # @param block an optional implementation for the expectation
+      #
+      # @example Expect the message `foo` to receive `bar`, then call it
+      #   RSpec::Mocks.expect_message(bar, :foo)
+      #   bar.foo
+      def expect_message(subject, message, opts={}, &block)
+        orig_caller = opts.fetch(:expected_from) { caller(1)[0] }
+        ::RSpec::Mocks.proxy_for(subject).
+          add_message_expectation(orig_caller, message.to_sym, opts, &block)
+      end
+
       # @api private
       KERNEL_METHOD_METHOD = ::Kernel.instance_method(:method)
 
diff --git a/lib/rspec/mocks/any_instance/chain.rb b/lib/rspec/mocks/any_instance/chain.rb
@@ -7,39 +7,39 @@ def initialize(*args, &block)
           @expectation_block = block
         end
 
-        class << self
-          private
-
+        module Customizations
           # @macro [attach] record
           #   @method $1(*args, &block)
           #   Records the `$1` message for playback against an instance that
           #   invokes a method stubbed or mocked using `any_instance`.
           #
           #   @see RSpec::Mocks::MessageExpectation#$1
           #
-          def record(method_name)
+          def self.record(method_name)
             class_eval(<<-EOM, __FILE__, __LINE__ + 1)
               def #{method_name}(*args, &block)
                 record(:#{method_name}, *args, &block)
               end
             EOM
           end
+
+          record :and_return
+          record :and_raise
+          record :and_throw
+          record :and_yield
+          record :and_call_original
+          record :with
+          record :once
+          record :twice
+          record :any_number_of_times
+          record :exactly
+          record :times
+          record :never
+          record :at_least
+          record :at_most
         end
 
-        record :and_return
-        record :and_raise
-        record :and_throw
-        record :and_yield
-        record :and_call_original
-        record :with
-        record :once
-        record :twice
-        record :any_number_of_times
-        record :exactly
-        record :times
-        record :never
-        record :at_least
-        record :at_most
+        include Customizations
 
         # @private
         def playback!(instance)
@@ -63,8 +63,17 @@ def expectation_fulfilled!
           @expectation_fulfilled = true
         end
 
+        def never
+          ErrorGenerator.raise_double_negation_error("expect_any_instance_of(MyClass)") if negated?
+          super
+        end
+
         private
 
+        def negated?
+          messages.any? { |(message, *_), _| message.to_sym == :never }
+        end
+
         def messages
           @messages ||= []
         end
diff --git a/lib/rspec/mocks/any_instance/expectation_chain.rb b/lib/rspec/mocks/any_instance/expectation_chain.rb
@@ -36,34 +36,7 @@ def invocation_order
           }
         end
       end
-
-      # @api private
-      class NegativeExpectationChain < ExpectationChain
-        # `should_not_receive` causes a failure at the point in time the
-        # message is wrongly received, rather than during `rspec_verify`
-        # at the end of an example. Thus, we should always consider a
-        # negative expectation fulfilled for the purposes of end-of-example
-        # verification (which is where this is used).
-        def expectation_fulfilled?
-          true
-        end
-
-        private
-
-        def create_message_expectation_on(instance)
-          proxy = ::RSpec::Mocks.proxy_for(instance)
-          expected_from = IGNORED_BACKTRACE_LINE
-          proxy.add_negative_message_expectation(expected_from, *@expectation_args, &@expectation_block)
-        end
-
-        def invocation_order
-          @invocation_order ||= {
-            :with => [nil],
-            :and_return => [:with, nil],
-            :and_raise => [:with, nil]
-          }
-        end
-      end
     end
   end
 end
+
diff --git a/lib/rspec/mocks/any_instance/recorder.rb b/lib/rspec/mocks/any_instance/recorder.rb
@@ -60,8 +60,7 @@ def should_receive(method_name, &block)
         end
 
         def should_not_receive(method_name, &block)
-          observe!(method_name)
-          message_chains.add(method_name, NegativeExpectationChain.new(method_name, &block))
+          should_receive(method_name, &block).never
         end
 
         # Removes any previously recorded stubs, stub_chains or message
diff --git a/lib/rspec/mocks/error_generator.rb b/lib/rspec/mocks/error_generator.rb
@@ -116,6 +116,13 @@ def raise_expectation_on_mocked_method(method)
                 "method has been mocked instead of stubbed."
       end
 
+      def self.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 intro
diff --git a/lib/rspec/mocks/matchers/receive.rb b/lib/rspec/mocks/matchers/receive.rb
@@ -22,7 +22,11 @@ def setup_expectation(subject, &block)
         alias matches? setup_expectation
 
         def setup_negative_expectation(subject, &block)
-          setup_mock_proxy_method_substitute(subject, :add_negative_message_expectation, block)
+          # ensure `never` goes first for cases like `never.and_return(5)`,
+          # where `and_return` is meant to raise an error
+          @recorded_customizations.unshift Customization.new(:never, [], nil)
+
+          setup_expectation(subject, &block)
         end
         alias does_not_match? setup_negative_expectation
 
diff --git a/lib/rspec/mocks/message_expectation.rb b/lib/rspec/mocks/message_expectation.rb
@@ -71,16 +71,20 @@ def expected_args
       #   counter.stub(:count) { 1 }
       #   counter.count # => 1
       def and_return(*values, &implementation)
-        @expected_received_count = [@expected_received_count, values.size].max unless ignoring_args? || (@expected_received_count == 0 and @at_least)
-
-        if implementation
-          # TODO: deprecate `and_return { value }`
-          self.inner_implementation_action = implementation
+        if negative?
+          raise "`and_return` is not supported with negative message expectations"
         else
-          self.terminal_implementation_action = AndReturnImplementation.new(values)
-        end
+          @expected_received_count = [@expected_received_count, values.size].max unless ignoring_args? || (@expected_received_count == 0 and @at_least)
 
-        nil
+          if implementation
+            # TODO: deprecate `and_return { value }`
+            self.inner_implementation_action = implementation
+          else
+            self.terminal_implementation_action = AndReturnImplementation.new(values)
+          end
+
+          nil
+        end
       end
 
       # Tells the object to delegate to the original unmodified method
@@ -167,7 +171,7 @@ def matches?(message, *args)
 
       # @private
       def invoke(parent_stub, *args, &block)
-        if (@expected_received_count == 0 && !@at_least) || ((@exactly || @at_most) && (@actual_received_count == @expected_received_count))
+        if negative? || ((@exactly || @at_most) && (@actual_received_count == @expected_received_count))
           @actual_received_count += 1
           @failed_fast = true
           #args are the args we actually received, @argument_list_matcher is the
@@ -188,6 +192,11 @@ def invoke(parent_stub, *args, &block)
         end
       end
 
+      # @private
+      def negative?
+        @expected_received_count == 0 && !@at_least
+      end
+
       # @private
       def called_max_times?
         @expected_received_count != :any &&
@@ -365,6 +374,7 @@ def any_number_of_times(&block)
       #
       #   car.should_receive(:stop).never
       def never
+        ErrorGenerator.raise_double_negation_error("expect(obj)") if negative?
         @expected_received_count = 0
         self
       end
@@ -407,7 +417,7 @@ def ordered(&block)
 
       # @private
       def negative_expectation_for?(message)
-        return false
+        @message == message && negative?
       end
 
       # @private
@@ -450,25 +460,6 @@ def terminal_implementation_action=(action)
       end
     end
 
-    # @private
-    class NegativeMessageExpectation < MessageExpectation
-      # @private
-      def initialize(error_generator, expectation_ordering, expected_from, method_double, &implementation)
-        super(error_generator, expectation_ordering, expected_from, method_double, 0, {}, &implementation)
-      end
-
-      # no-op
-      # @deprecated and_return is not supported with negative message expectations.
-      def and_return(*)
-        RSpec.deprecate "and_return with should_not_receive"
-      end
-
-      # @private
-      def negative_expectation_for?(message)
-        return @message == message
-      end
-    end
-
     # Handles the implementation of an `and_yield` declaration.
     # @private
     class AndYieldImplementation
diff --git a/lib/rspec/mocks/method_double.rb b/lib/rspec/mocks/method_double.rb
@@ -226,15 +226,6 @@ def add_expectation(error_generator, expectation_ordering, expected_from, opts,
         expectation
       end
 
-      # @private
-      def add_negative_expectation(error_generator, expectation_ordering, expected_from, &implementation)
-        configure_method
-        expectation = NegativeMessageExpectation.new(error_generator, expectation_ordering,
-                                                     expected_from, self, &implementation)
-        expectations.unshift expectation
-        expectation
-      end
-
       # @private
       def build_expectation(error_generator, expectation_ordering)
         expected_from = IGNORED_BACKTRACE_LINE
diff --git a/lib/rspec/mocks/proxy.rb b/lib/rspec/mocks/proxy.rb
@@ -51,11 +51,6 @@ def add_message_expectation(location, method_name, opts={}, &block)
         meth_double.add_expectation @error_generator, @expectation_ordering, location, opts, &block
       end
 
-      # @private
-      def add_negative_message_expectation(location, method_name, &implementation)
-        method_double[method_name].add_negative_expectation @error_generator, @expectation_ordering, location, &implementation
-      end
-
       # @private
       def build_expectation(method_name)
         meth_double = method_double[method_name]
diff --git a/lib/rspec/mocks/proxy_for_nil.rb b/lib/rspec/mocks/proxy_for_nil.rb
@@ -28,7 +28,8 @@ def add_stub(location, method_name, opts={}, &implementation)
       private
 
       def warn method_name
-        Kernel.warn("An expectation of :#{method_name} was set on nil. Called from #{caller[2]}. Use allow_message_expectations_on_nil to disable warnings.")
+        non_rspec_caller = caller.find { |line| !line.include?('lib/rspec/mocks') }
+        Kernel.warn("An expectation of :#{method_name} was set on nil. Called from #{non_rspec_caller}. Use allow_message_expectations_on_nil to disable warnings.")
       end
 
     end
diff --git a/lib/rspec/mocks/syntax.rb b/lib/rspec/mocks/syntax.rb
@@ -12,20 +12,21 @@ def self.enable_should(syntax_host = default_should_syntax_host)
 
         syntax_host.class_eval do
           def should_receive(message, opts={}, &block)
-            proxy = ::RSpec::Mocks.proxy_for(self)
-            proxy.add_message_expectation(opts[:expected_from] || caller(1)[0], message.to_sym, opts, &block)
+            opts[:expected_from] ||= caller(1)[0]
+            ::RSpec::Mocks.expect_message(self, message.to_sym, opts, &block)
           end
 
           def should_not_receive(message, &block)
-            proxy = ::RSpec::Mocks.proxy_for(self)
-            proxy.add_negative_message_expectation(caller(1)[0], message.to_sym, &block)
+            opts = {:expected_from => caller(1)[0]}
+            ::RSpec::Mocks.expect_message(self, message.to_sym, opts, &block).never
           end
 
           def stub(message_or_hash, opts={}, &block)
             if ::Hash === message_or_hash
               message_or_hash.each {|message, value| stub(message).and_return value }
             else
-              ::RSpec::Mocks.proxy_for(self).add_stub(caller(1)[0], message_or_hash.to_sym, opts, &block)
+              opts[:expected_from] = caller(1)[0]
+              ::RSpec::Mocks.allow_message(self, message_or_hash, opts, &block)
             end
           end
 
diff --git a/spec/rspec/mocks/any_instance_spec.rb b/spec/rspec/mocks/any_instance_spec.rb
@@ -347,6 +347,12 @@ class RSpec::SampleRspecTestClass;end
             RSpec::Mocks.space.verify_all
           end
         end
+
+        it "prevents confusing double-negative expressions involving `never`" do
+          expect {
+            klass.any_instance.should_not_receive(:not_expected).never
+          }.to raise_error(/trying to negate it again/)
+        end
       end
 
       context "with #should_receive" do
diff --git a/spec/rspec/mocks/matchers/receive_spec.rb b/spec/rspec/mocks/matchers/receive_spec.rb
@@ -136,6 +136,16 @@ def receiver.method_missing(*a); end # a poor man's stub...
             receiver.foo(:a)
           }.to raise_error(/expected: 0 times.*received: 1 time/m)
         end
+
+        it 'prevents confusing double-negative expressions involving `never`' do
+          expect {
+            wrapped.not_to receive(:foo).never
+          }.to raise_error(/trying to negate it again/)
+
+          expect {
+            wrapped.to_not receive(:foo).never
+          }.to raise_error(/trying to negate it again/)
+        end
       end
 
       describe "allow(...).to receive" do
diff --git a/spec/rspec/mocks/mock_spec.rb b/spec/rspec/mocks/mock_spec.rb
diff --git a/spec/rspec/mocks/partial_mock_spec.rb b/spec/rspec/mocks/partial_mock_spec.rb
diff --git a/spec/rspec/mocks/syntax_agnostic_message_matchers_spec.rb b/spec/rspec/mocks/syntax_agnostic_message_matchers_spec.rb
