rspec-mocks 2.6.0 → 2.7.0

data/README.md

@@ -3,21 +3,6 @@
 rspec-mocks provides a test-double framework for rspec including support
 for method stubs, fakes, and message expectations.
 
-[![build status](http://travis-ci.org/rspec/rspec-mocks.png)](http://travis-ci.org/rspec/rspec-mocks)
-
-## Documentation
-
-The [Cucumber features](http://relishapp.com/rspec/rspec-mocks) are the
-most comprehensive and up-to-date docs for end-users.
-
-The [RDoc](http://rubydoc.info/gems/rspec-mocks/2.3.0/frames) provides additional
-information for contributors and/or extenders.
-
-All of the documentation is open source and a work in progress. If you find it
-lacking or confusing, you can help improve it by submitting requests and
-patches to the [rspec-mocks issue
-tracker](https://github.com/rspec/rspec-mocks/issues).
-
 ## Install
 
     gem install rspec       # for rspec-core, rspec-expectations, rspec-mocks
@@ -48,10 +33,6 @@ tracker](https://github.com/rspec/rspec-mocks/issues).
       end
     end
 
-## Contribute
-
-See [http://github.com/rspec/rspec-dev](http://github.com/rspec/rspec-dev)
-
 ## Also see
 
 * [http://github.com/rspec/rspec](http://github.com/rspec/rspec)

data/features/Scope.md

@@ -0,0 +1,17 @@
+Doubles, stubs, and message expectations are all cleaned out after each
+example. This ensures that each example can be run in isolation, and in any
+order.
+
+### `before(:each)`
+
+It is perfectly fine to set up doubles, stubs, and message expectations in
+a `before(:each)` hook, as that hook is executed in the scope of the example:
+
+    before(:each) do
+      @account = double('account')
+    end
+
+### Do not create doubles, stubs, or message expectations in `before(:all)`
+
+If you do, they'll get cleaned out after the first example, and you will be
+very confused as to what's going on in the second example.

data/features/argument_matchers/README.md

@@ -0,0 +1,27 @@
+### Introduction
+
+Argument matchers can be used:
+
+* In stubs to constrain the scope of the stubbed method
+
+      obj.stub(:foo).with(:bar) do |arg|
+        #do something for :bar
+      end
+      obj.stub(:foo).with(:baz) do |arg|
+        #do something for :baz
+      end
+
+* In expectations to validate the arguments that should be received in a method call
+
+      #create a double
+      obj = double()
+      
+      #expect a message with given args
+      obj.should_receive(:message).with('an argument')
+
+If more control is needed, one can use a block
+
+    obj.should_receive(:message) do |arg1,  arg2|
+      # set expectations about the args in this block
+      # and optionally set a return value
+    end

data/features/argument_matchers/explicit.feature

@@ -0,0 +1,60 @@
+Feature: explicit arguments
+
+  Allows you to explicitly specify the argument values
+
+  Scenario: explicit arguments
+    Given a file named "stub_explicit_args_spec.rb" with:
+      """
+      describe "stubbed explicit arguments" do
+        it "works on stubs" do
+          object = Object.new
+          object.stub(:foo).with(:this) do |arg|
+            "got this"
+          end
+          object.stub(:foo).with(:that) do |arg|
+            "got that"
+          end
+
+          object.foo(:this).should eq("got this")
+          object.foo(:that).should eq("got that")
+        end
+
+        it "works on doubles and expectations" do
+          object = double('foo')
+          object.should_receive(:bar).with(:foo)
+
+          object.bar(:foo)
+        end
+      end
+      """
+    When I run `rspec stub_explicit_args_spec.rb`
+    Then the output should contain "2 examples, 0 failures"
+
+  Scenario: explicit arguments with multiple arities
+    Given a file named "stub_multiple_explicit_args_spec.rb" with:
+      """
+      describe "stubbed multiple explicit arguments" do
+        it "works on stubs" do
+          object = Object.new
+          object.stub(:foo).with(:this) do |arg|
+            "got this"
+          end
+          object.stub(:foo).with(:this, :that) do |arg1, arg2|
+            "got this and that"
+          end
+
+          object.foo(:this).should eq("got this")
+          object.foo(:this, :that).should eq("got this and that")
+        end
+        
+        it "works on mocks" do
+          object = double('foo')
+          object.should_receive(:foo).with(:this, :that)
+
+          object.foo(:this, :that)
+        end
+      end
+      """
+    When I run `rspec stub_multiple_explicit_args_spec.rb`
+    Then the output should contain "2 examples, 0 failures"
+

data/features/argument_matchers/general_matchers.feature

@@ -0,0 +1,85 @@
+Feature: General matchers
+
+  The `anything`,  `any_args`,  and `no_args` matchers can be used to require the method 
+  to have arguments (or not) without constraining the details of the argument, such as its
+  type,  pattern or value. The `anything` matcher only reflects a single argument, while
+  the `any_args` matcher matches any arity.
+
+  Scenario: anything argument matcher
+    Given a file named "stub_anything_args_spec.rb" with:
+      """
+      describe "stubbed anything() args spec" do
+        it "works" do
+          object = Object.new
+          object.stub(:foo).with(anything) do
+            "anything"
+          end
+
+          object.foo(1).should eq("anything")
+          object.foo(:that).should eq("anything")
+        end
+      end
+      """
+    When I run `rspec stub_anything_args_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: any_args argument matcher
+    Given a file named "stub_any_args_spec.rb" with:
+      """
+      describe "stubbed any_args() args spec" do
+        it "works" do
+          object = Object.new
+          object.stub(:foo).with(any_args) do
+            "anything"
+          end
+
+          object.foo(1).should eq("anything")
+          object.foo(:that).should eq("anything")
+          object.foo.should eq("anything")
+        end
+      end
+      """
+    When I run `rspec stub_any_args_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: no_args argument matcher
+    Given a file named "stub_no_args_spec.rb" with:
+      """
+      describe "stubbed no_args() args spec" do
+        it "works for no args" do
+          object = Object.new
+          object.stub(:foo).with(no_args) do
+            "nothing"
+          end
+          object.stub(:foo).with(anything) do
+            "something"
+          end
+
+          object.foo(:that).should eq("something")
+          object.foo.should eq("nothing")
+        end
+      end
+      """
+    When I run `rspec stub_no_args_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: no_args argument matcher for expectations
+    Given a file named "stub_no_args_expectations_spec.rb" with:
+      """
+      describe "stubbed no_args() args spec for expectations" do
+        it "works for no args" do
+          object = Object.new
+          object.should_receive(:foo).with(no_args)
+
+          object.foo
+        end
+        it "fails for args" do
+          object = Object.new
+          object.should_receive(:foo).with(no_args)
+
+          object.foo(:bar)
+        end
+      end
+      """
+    When I run `rspec stub_no_args_expectations_spec.rb`
+    Then the output should contain "2 examples, 1 failure"

data/features/argument_matchers/type_matchers.feature

@@ -0,0 +1,25 @@
+Feature: stub with argument constraints
+
+  You can further specify the behavior by constraining the type, format and/or number of arguments with the #with() method chained off of #stub()
+  
+  Scenario: an_instance_of argument matcher
+    Given a file named "stub_an_instance_of_args_spec.rb" with:
+      """
+      describe "stubbed an_instance_of() args spec" do
+        it "works" do
+          object = Object.new
+          object.stub(:foo).with(an_instance_of(Symbol)) do
+            "symbol"
+          end
+          object.stub(:foo).with(an_instance_of(String)) do
+            "string"
+          end
+
+          object.foo("bar").should eq("string")
+          object.foo(:that).should eq("symbol")
+        end
+      end
+      """
+    When I run `rspec stub_an_instance_of_args_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+

data/features/message_expectations/any_instance.feature

@@ -2,6 +2,8 @@ Feature: expect a message on any instance of a class
 
   Use `any_instance.should_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:

data/features/message_expectations/receive_counts.feature

@@ -0,0 +1,209 @@
+Feature: receive counts
+
+  Scenario: expect a message once
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).once
+
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: expect a message twice
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).twice
+
+            account.open
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: expect a message 3 times
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).exactly(3).times
+
+            account.open
+            account.open
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: expect a message at least (:once)
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).at_least(:once)
+
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+
+  Scenario: expect a message at least (n) times
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).at_least(3).times
+
+            # Note that I am calling method under test 4 times
+            # and I specified it to be called at least 3 times
+            account.open
+            account.open
+            account.open
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "1 example, 0 failures"
+
+  Scenario: expect a message at most (:once)
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).at_most(:once)
+
+            account.open
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "expected: 1 time"
+     And the output should contain "received: 2 times"
+
+  Scenario: expect a message at most (n) times
+    Given a file named "spec/account_spec.rb" with:
+      """
+      class Account
+        attr_accessor :logger
+
+        def open
+          logger.account_opened
+        end
+      end
+
+      describe Account do
+        context "when opened" do
+          it "logger#account_opened was called once" do
+            logger = double("logger")
+            account = Account.new
+            account.logger = logger
+
+            logger.should_receive(:account_opened).at_most(2).times
+
+            account.open
+            account.open
+          end
+        end
+      end
+      """
+    When I run `rspec spec/account_spec.rb`
+    Then the output should contain "1 example, 0 failures"

data/features/method_stubs/README.md

@@ -1,15 +1,12 @@
 ### Stub return values
 
-    obj.stub(:message).and_return('this is the value to return')
-    obj.stub(:message) { 'this is the value to return' }
+    obj.stub(:message) { :value }
+    obj.stub(:message => :value)
+    obj.stub(:message).and_return(:value)
 
-These two forms are somewhat interchangeable. The difference is that the
-argument to `and_return` is evaluated immediately, whereas the block contents
-are evaluated lazily when the `obj` receives the `message` message.
-
-The block format is generally preferred as it is more terse and more consistent
-with other forms described below, but lazy evaluation can be confusing because
-things aren't evaluated in the order in which they are declared.
+These forms are somewhat interchangeable. The difference is that the block
+contents are evaluated lazily when the `obj` receives the `message` message,
+whereas the others are evaluated as they are read.
 
 ### Fake implementation
 
@@ -44,4 +41,3 @@ You can also use the block format, for consistency with other stubs:
 #### Regular expressions
 
     obj.stub(:message).with(/abc/) { ... }
-

data/features/method_stubs/any_instance.feature

@@ -6,7 +6,7 @@ Feature: stub on any instance of a class
 
   Messages can be stubbed on any class, including those in Ruby's core library.
 
-  Scenario: simple any_instance stub with a single return value
+  Scenario: any_instance stub with a single return value
     Given a file named "example_spec.rb" with:
       """
       describe "any_instance.stub" do
@@ -20,4 +20,114 @@ Feature: stub on any instance of a class
       """
     When I run `rspec example_spec.rb`
     Then the examples should all pass
+    
+  Scenario: any_instance stub with a hash
+    Given a file named "example_spec.rb" with:
+      """
+      describe "any_instance.stub" do
+        context "with a hash" do
+          it "returns the hash values on any instance of the class" do
+            Object.any_instance.stub(:foo => 'foo', :bar => 'bar')
+
+            o = Object.new
+            o.foo.should eq('foo')
+            o.bar.should eq('bar')
+          end
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass  
+    
+  Scenario: any_instance stub with specific arguments matchers
+    Given a file named "example_spec.rb" with:
+      """
+      describe "any_instance.stub" do
+        context "with arguments" do
+          it "returns the stubbed value when arguments match" do
+            Object.any_instance.stub(:foo).with(:param_one, :param_two).and_return(:result_one)
+            Object.any_instance.stub(:foo).with(:param_three, :param_four).and_return(:result_two)
+          
+            o = Object.new
+            o.foo(:param_one, :param_two).should eq(:result_one)
+            o.foo(:param_three, :param_four).should eq(:result_two)
+          end
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass
+  
+  Scenario: any_instance unstub
+    Given a file named "example_spec.rb" with:
+      """
+      describe "any_instance.unstub" do
+        it "unstubs a stubbed method" do
+          class Object
+            def foo
+              :foo
+            end
+          end
+          
+          Object.any_instance.stub(:foo)
+          Object.any_instance.unstub(:foo)
+
+          Object.new.foo.should eq(:foo)
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass  
+  
+  Scenario: any_instance unstub
+    Given a file named "example_spec.rb" with:
+      """
+      describe "any_instance.unstub" do
+        context "with both an expectation and a stub already set" do
+          it "only removes the stub" do
+            class Object
+              def foo
+                :foo
+              end
+            end
+            Object.any_instance.should_receive(:foo).and_return(:bar)
+            Object.any_instance.stub(:foo)
+            Object.any_instance.unstub(:foo)
+            
+            Object.new.foo.should eq(:bar)
+          end
+        end
+      end
+      """
+    When I run `rspec example_spec.rb`
+    Then the examples should all pass
+    
+  Scenario: stub a chain of methods an any instance
+    Given a file named "stub_chain_spec.rb" with:
+      """
+      describe "stubbing a chain of methods" do
+        context "given symbols representing methods" do
+          it "returns the correct value" do
+            Object.any_instance.stub_chain(:one, :two, :three).and_return(:four)
+            Object.new.one.two.three.should eq(:four)
+          end
+        end
+
+        context "given a hash at the end" do
+          it "returns the correct value" do
+            Object.any_instance.stub_chain(:one, :two, :three => :four)
+            Object.new.one.two.three.should eq(:four)
+          end
+        end
 
+        context "given a string of methods separated by dots" do
+          it "returns the correct value" do
+            Object.any_instance.stub_chain("one.two.three").and_return(:four)
+            Object.new.one.two.three.should eq(:four)
+          end
+        end
+      end
+      """
+    When I run `rspec stub_chain_spec.rb`
+    Then the examples should all pass
+