rspec-mocks 2.14.0.rc1 → 2.14.0

data/Changelog.md

@@ -1,3 +1,27 @@
+### 2.14.0 / 2013-07-06
+[full changelog](http://github.com/rspec/rspec-mocks/compare/v2.14.0.rc1...v2.14.0)
+
+Enhancements:
+
+* Document test spies in the readme. (Adarsh Pandit)
+* Add an `array_including` matcher. (Sam Phippen)
+* Add a syntax-agnostic API for mocking or stubbing a method. This is
+  intended for use by libraries such as rspec-rails that need to mock
+  or stub a method, and work regardless of the syntax the user has
+  configured (Paul Annesley, Myron Marston and Sam Phippen).
+
+Bug Fixes:
+
+* Fix `double` so that it sets up passed stubs correctly regardless of
+  the configured syntax (Paul Annesley).
+* Allow a block implementation to be used in combination with
+  `and_yield`, `and_raise`, `and_return` or `and_throw`. This got fixed
+  in 2.13.1 but failed to get merged into master for the 2.14.0.rc1
+  release (Myron Marston).
+* `Marshal.dump` does not unnecessarily duplicate objects when rspec-mocks has
+  not been fully initialized. This could cause errors when using `spork` or
+  similar preloading gems (Andy Lindeman).
+
 ### 2.14.0.rc1 / 2013-05-27
 [full changelog](http://github.com/rspec/rspec-mocks/compare/v2.13.0...v2.14.0.rc1)
 
@@ -37,6 +61,7 @@ Bug fixes
   (Luke Imhoff, Jon Rowe)
 * Fix isolation of `allow_message_expectations_on_nil` (Jon Rowe)
 * Use inspect to format actual arguments on expectations in failure messages (#280, Ben Langfeld)
+* Protect against improperly initialised test doubles (#293) (Joseph Shraibman and Jon Rowe)
 
 Deprecations
 

data/features/message_expectations/allow_any_instance_of.feature

@@ -0,0 +1,26 @@
+Feature: allow a message on any instance of a class
+
+  Use `allow_any_instance_of(Class).to receive` when you want to configure how
+  instances of the given class respond to a message without setting an
+  expectation that the message will be received.
+
+  Scenario: allowing a message on any instance of a class
+    Given a file named "example_spec.rb" with:
+      """ruby
+      describe "any_instance.should_receive" do
+        before do
+          allow_any_instance_of(Object).to receive(:foo).and_return(:return_value)
+        end
+
+        it "allows any instance of the class to receive the message" do
+          o = Object.new
+          expect(o.foo).to eq(:return_value)
+        end
+
+        it "passes even if no instances receive that message" do
+          o = Object.new
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass

data/features/message_expectations/expect_any_instance_of.feature

@@ -0,0 +1,27 @@
+Feature: expect a message on any instance of a class
+
+  Use `expect_any_instance_of(Class).to receive` to set an expectation that one
+  (and only one) instance of a class receives a message before the example is
+  completed. The spec will fail if no instance receives a message.
+
+  Scenario: expect a message on any instance of a class
+    Given a file named "example_spec.rb" with:
+      """ruby
+      describe "expect_any_instance_of" do
+        before do
+          expect_any_instance_of(Object).to receive(:foo).and_return(:return_value)
+        end
+
+        it "verifies that one instance of the class receives the message" do
+          o = Object.new
+          expect(o.foo).to eq(:return_value)
+        end
+
+        it "fails unless an instance receives that message" do
+          o = Object.new
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the output should contain "2 examples, 1 failure"
+    And the output should contain "1) expect_any_instance_of fails unless an instance receives that message"

data/features/message_expectations/expect_message_using_expect.feature

@@ -4,6 +4,10 @@ Feature: expect message using `expect`
   `object` should receive the message `:message` before the example is
   completed.
 
+  Note: You can use `expect_any_instance_of` when you don't have a reference
+  to the object that receives a message in your test. For more information,
+  see the message_expectations/expect_any_instance_of feature.
+
   Scenario: expect a message
     Given a file named "spec/account_spec.rb" with:
       """ruby

data/features/method_stubs/README.md

@@ -3,7 +3,11 @@
     # create a double
     obj = double()
 
-    # specify a return value
+    # specify a return value using `:expect` syntax
+    allow(obj).to receive(:message) { :value }
+    allow(obj).to receive(:message).and_return(:value)
+
+    # specify a return value using `:should` syntax
     obj.stub(:message) { :value }
     obj.stub(:message => :value)
     obj.stub(:message).and_return(:value)
@@ -14,18 +18,29 @@ block contents are evaluated lazily when the `obj` receives the
 
 ### Fake implementation
 
+    allow(obj).to receive(:message) do |arg1, arg2|
+      # set expectations about the args in this block
+      # and/or return  value
+    end
+
     obj.stub(:message) do |arg1, arg2|
       # set expectations about the args in this block
-      # and/or set a return value
+      # and/or return a value
     end
 
 ### Raising/Throwing
 
+    allow(obj).to receive(:message).and_raise("this error")
+    allow(obj).to receive(:message).and_throw(:this_symbol)
+
     obj.stub(:message).and_raise("this error")
     obj.stub(:message).and_throw(:this_symbol)
 
 You can also use the block format:
 
+    allow(obj).to receive(:message) { raise "this error" }
+    allow(obj).to receive(:message) { throw :this_symbol }
+
     obj.stub(:message) { raise "this error" }
     obj.stub(:message) { throw :this_symbol }
 
@@ -33,15 +48,26 @@ You can also use the block format:
 
 #### Explicit arguments
 
+    allow(obj).to receive(:message).with('an argument') { ... }
+
     obj.stub(:message).with('an argument') { ... }
     obj.stub(:message).with('more_than', 'one_argument') { ... }
 
 #### Argument matchers
 
+    allow(obj).to receive(:message).with(anything()) { ... }
+    allow(obj).to receive(:message).with(an_instance_of(Money)) { ... }
+    allow(obj).to receive(:message).with(hash_including(:a => 'b')) { ... }
+    allow(obj).to receive(:message).with(array_including(1,2,3)) { ... }
+    # or
+    allow(obj).to receive(:message).with(array_including([1,2,3])) { ... }
+
     obj.stub(:message).with(anything()) { ... }
     obj.stub(:message).with(an_instance_of(Money)) { ... }
     obj.stub(:message).with(hash_including(:a => 'b')) { ... }
 
 #### Regular expressions
 
+    allow(obj).to receive(:message).with(/abc/) { ... }
+
     obj.stub(:message).with(/abc/) { ... }

data/features/method_stubs/any_instance.feature

@@ -6,6 +6,10 @@ Feature: stub on any instance of a class
 
   Messages can be stubbed on any class, including those in Ruby's core library.
 
+  Note: You can use `allow_any_instance_of` when you don't have a reference
+  to the object that receives a message in your test. For more information,
+  see the message_expectations/allow_any_instance_of feature.
+
   Scenario: any_instance stub with a single return value
     Given a file named "example_spec.rb" with:
       """ruby
@@ -129,4 +133,4 @@ Feature: stub on any instance of a class
       end
       """
     When I run `rspec stub_chain_spec.rb`
-    Then the examples should all pass
+    Then the examples should all pass

data/features/method_stubs/as_null_object.feature

@@ -16,7 +16,12 @@ Feature: as_null_object
           null_object.should respond_to(:an_undefined_method)
         end
 
-        it "allows explicit stubs" do
+        it "allows explicit stubs using expect syntax" do
+          allow(null_object).to receive(:foo) { "bar" }
+          expect(null_object.foo).to eq("bar")
+        end
+
+        it "allows explicit stubs using should syntax" do
           null_object.stub(:foo) { "bar" }
           null_object.foo.should eq("bar")
         end

data/features/method_stubs/simple_return_value_with_allow.feature

@@ -0,0 +1,44 @@
+Feature: allow with a simple return value
+
+  Use the `allow` method with the `receive` matcher on a test double or a real
+  object to tell the object to return a value (or values) in response to a given
+  message. Nothing happens if the message is never received.
+
+  Scenario: stub with no return value
+    Given a file named "example_spec.rb" with:
+      """ruby
+      describe "a stub with no return value specified" do
+        let(:collaborator) { double("collaborator") }
+
+        it "returns nil" do
+          allow(collaborator).to receive(:message)
+          expect(collaborator.message).to be(nil)
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass
+
+  Scenario: stubs with return values
+    Given a file named "example_spec.rb" with:
+      """ruby
+      describe "a stub with a return value" do
+        context "specified in a block" do
+          it "returns the specified value" do
+            collaborator = double("collaborator")
+            allow(collaborator).to receive(:message) { :value }
+            expect(collaborator.message).to eq(:value)
+          end
+        end
+
+        context "specified with #and_return" do
+          it "returns the specified value" do
+            collaborator = double("collaborator")
+            allow(collaborator).to receive(:message).and_return(:value)
+            expect(collaborator.message).to eq(:value)
+          end
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass

data/features/method_stubs/stub_implementation.feature

@@ -3,7 +3,29 @@ Feature: stub with substitute implementation
   You can stub an implementation of a method (a.k.a. fake) by passing a block
   to the `stub` method.
 
-  Scenario: stub implementation
+  Scenario: stub implementation using `expect` syntax
+  Given a file named "stub_implementation_spec.rb" with:
+    """ruby
+    describe "a stubbed implementation" do
+      it "works" do
+        object = Object.new
+        allow(object).to receive(:foo) do |arg|
+          if arg == :this
+            "got this"
+          elsif arg == :that
+            "got that"
+          end
+        end
+
+        expect(object.foo(:this)).to eq("got this")
+        expect(object.foo(:that)).to eq("got that")
+      end
+    end
+    """
+  When I run `rspec stub_implementation_spec.rb`
+  Then the output should contain "1 example, 0 failures"
+
+  Scenario: stub implementation using `should` syntax
     Given a file named "stub_implementation_spec.rb" with:
       """ruby
       describe "a stubbed implementation" do

data/lib/rspec/mocks.rb

@@ -30,6 +30,41 @@ module RSpec
         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)
 

data/lib/rspec/mocks/any_instance/chain.rb

@@ -7,9 +7,7 @@ module RSpec
           @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
@@ -17,29 +15,31 @@ module RSpec
           #
           #   @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 @@ module RSpec
           @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

data/lib/rspec/mocks/any_instance/expectation_chain.rb

@@ -36,34 +36,7 @@ module RSpec
           }
         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
+

data/lib/rspec/mocks/any_instance/recorder.rb

@@ -60,8 +60,7 @@ module RSpec
         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