rspec-mocks 2.0.0.beta.8 → 2.0.0.beta.9

data/README.markdown

@@ -1,4 +1,4 @@
-# Rspec Mocks
+# RSpec Mocks
 
 rspec-mocks provides a test-double framework for rspec including support
 for method stubs, fakes, and message expectations.

data/Rakefile

@@ -6,15 +6,15 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gem|
     gem.name = "rspec-mocks"
-    gem.version = Rspec::Mocks::Version::STRING
-    gem.summary = "rspec-mocks-#{Rspec::Mocks::Version::STRING}"
-    gem.description = "Rspec's 'test double' framework, with support for stubbing and mocking"
+    gem.version = RSpec::Mocks::Version::STRING
+    gem.summary = "rspec-mocks-#{RSpec::Mocks::Version::STRING}"
+    gem.description = "RSpec's 'test double' framework, with support for stubbing and mocking"
     gem.email = "dchelimsky@gmail.com;chad.humphries@gmail.com"
     gem.homepage = "http://github.com/rspec/mocks"
     gem.authors = ["David Chelimsky", "Chad Humphries"]    
     gem.rubyforge_project = "rspec"
-    gem.add_development_dependency 'rspec-core', Rspec::Mocks::Version::STRING
-    gem.add_development_dependency 'rspec-expectations', Rspec::Mocks::Version::STRING
+    gem.add_development_dependency 'rspec-core', RSpec::Mocks::Version::STRING
+    gem.add_development_dependency 'rspec-expectations', RSpec::Mocks::Version::STRING
     gem.post_install_message = <<-EOM
 #{"*"*50}
 
@@ -34,20 +34,20 @@ end
 namespace :gem do
   desc "push to gemcutter"
   task :push => :build do
-    system "gem push pkg/rspec-mocks-#{Rspec::Mocks::Version::STRING}.gem"
+    system "gem push pkg/rspec-mocks-#{RSpec::Mocks::Version::STRING}.gem"
   end
 end
 
 begin
   require 'rspec/core/rake_task'
-  Rspec::Core::RakeTask.new(:spec)
+  RSpec::Core::RakeTask.new(:spec)
 
-  Rspec::Core::RakeTask.new(:rcov) do |spec|
+  RSpec::Core::RakeTask.new(:rcov) do |spec|
     spec.rcov = true
     spec.rcov_opts = %[--exclude "core,expectations,gems/*,spec/resources,spec/spec,spec/spec_helper.rb,db/*,/Library/Ruby/*,config/*" --text-summary  --sort coverage]
   end
 rescue LoadError
-  puts "Rspec core or one of its dependencies is not installed. Install it with: gem install rspec-meta"
+  puts "RSpec core or one of its dependencies is not installed. Install it with: gem install rspec-meta"
 end
 
 begin
@@ -68,7 +68,7 @@ end
 require 'rake/rdoctask'
 Rake::RDocTask.new do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "rspec-mocks #{Rspec::Mocks::Version::STRING}"
+  rdoc.title = "rspec-mocks #{RSpec::Mocks::Version::STRING}"
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION

@@ -1 +1 @@
-2.0.0.beta.8
+2.0.0.beta.9

data/features/mocks/block_local_expectations.feature

@@ -1,7 +1,7 @@
 Feature: block local expectations
 
   Background:
-    Given a file named "account.rb" with:
+    Given a file named "lib/account.rb" with:
       """
       class Account
         def self.create
@@ -14,7 +14,7 @@ Feature: block local expectations
       """
 
   Scenario: passing example
-    Given a file named "account_passing_spec.rb" with:
+    Given a file named "spec/account_passing_spec.rb" with:
       """
       require 'account'
 
@@ -29,12 +29,12 @@ Feature: block local expectations
         end
       end
       """
-    When I run "rspec account_passing_spec.rb"
+    When I run "rspec ./spec/account_passing_spec.rb"
     Then I should see "1 example, 0 failures"
     
   Scenario: failing example
     
-    Given a file named "account_failing_spec.rb" with:
+    Given a file named "spec/account_failing_spec.rb" with:
       """
       require 'account'
 
@@ -50,5 +50,5 @@ Feature: block local expectations
       end
       """
 
-    When I run "rspec account_failing_spec.rb"
+    When I run "rspec ./spec/account_failing_spec.rb"
     Then I should see "1 example, 1 failure"

data/features/mocks/mix_stubs_and_mocks.feature

@@ -8,7 +8,7 @@ Feature: Spec and test together
       """
       require 'rspec/expectations'
 
-      Rspec.configure do |config|
+      RSpec.configure do |config|
         config.mock_framework = :rspec
       end
 
@@ -24,5 +24,5 @@ Feature: Spec and test together
         end
       end
       """
-    When I run "rspec stub_and_mocks_spec.rb -fs"
+    When I run "rspec ./stub_and_mocks_spec.rb -fs"
     Then I should see "received :foo with unexpected arguments"

data/features/mocks/warn_when_expectation_is_set_on_nil.feature

@@ -3,7 +3,7 @@ Feature: warn when expectation is set on nil
   Scenario: nil instance variable
     Given a file named "example_spec.rb" with:
       """
-      Rspec.configure {|c| c.mock_with :rspec}
+      RSpec.configure {|c| c.mock_with :rspec}
       describe "something" do
         it "does something" do
           @i_do_not_exist.should_receive(:foo)
@@ -11,13 +11,13 @@ Feature: warn when expectation is set on nil
         end
       end
       """
-    When I run "rspec example_spec.rb"
+    When I run "rspec ./example_spec.rb"
     Then I should see "An expectation of :foo was set on nil"
 
   Scenario: allow
     Given a file named "example_spec.rb" with:
       """
-      Rspec.configure {|c| c.mock_with :rspec}
+      RSpec.configure {|c| c.mock_with :rspec}
       describe "something" do
         it "does something" do
           allow_message_expectations_on_nil
@@ -26,13 +26,13 @@ Feature: warn when expectation is set on nil
         end
       end
       """
-    When I run "rspec example_spec.rb"
+    When I run "rspec ./example_spec.rb"
     Then I should not see "An expectation"
 
   Scenario: allow in one example, but not on another
     Given a file named "example_spec.rb" with:
       """
-      Rspec.configure {|c| c.mock_with :rspec}
+      RSpec.configure {|c| c.mock_with :rspec}
       describe "something" do
         it "does something (foo)" do
           allow_message_expectations_on_nil
@@ -45,6 +45,6 @@ Feature: warn when expectation is set on nil
         end
       end
       """
-    When I run "rspec example_spec.rb"
+    When I run "rspec ./example_spec.rb"
     Then I should see "An expectation of :bar"
     And  I should not see "An expectation of :foo"

data/features/stubs/stub_implementation.feature

@@ -6,7 +6,7 @@ Feature: stub implementation
   Scenario: stub implementation
     Given a file named "stub_implementation_spec.rb" with:
       """
-      Rspec.configure do |c|
+      RSpec.configure do |c|
         c.mock_with :rspec
       end
 
@@ -26,5 +26,5 @@ Feature: stub implementation
         end
       end
       """
-    When I run "rspec stub_implementation_spec.rb"
+    When I run "rspec ./stub_implementation_spec.rb"
     Then I should see "1 example, 0 failures"

data/lib/rspec/mocks.rb

@@ -2,109 +2,74 @@ require 'rspec/mocks/framework'
 require 'rspec/mocks/extensions/object'
 require 'rspec/mocks/version'
 
-module Rspec
-  # == Mocks and Stubs
+module RSpec
+  # == Test Doubles
   #
-  # RSpec will create Mock Objects and Stubs for you at runtime, or attach stub/mock behaviour
-  # to any of your real objects (Partial Mock/Stub). Because the underlying implementation
-  # for mocks and stubs is the same, you can intermingle mock and stub
-  # behaviour in either dynamically generated mocks or your pre-existing classes.
-  # There is a semantic difference in how they are created, however,
-  # which can help clarify the role it is playing within a given spec.
+  # A Test Double is an object that stands in for a real object in a test.
+  # RSpec creates test doubles that support method stubs and message
+  # expectations.
   #
-  # == Mock Objects
-  # 
-  # Mocks are objects that allow you to set and verify expectations that they will
-  # receive specific messages during run time. They are very useful for specifying how the subject of
-  # the spec interacts with its collaborators. This approach is widely known as "interaction
-  # testing".
-  # 
-  # Mocks are also very powerful as a design tool. As you are
-  # driving the implementation of a given class, Mocks provide an anonymous
-  # collaborator that can change in behaviour as quickly as you can write an expectation in your
-  # spec. This flexibility allows you to design the interface of a collaborator that often
-  # does not yet exist. As the shape of the class being specified becomes more clear, so do the
-  # requirements for its collaborators - often leading to the discovery of new types that are
-  # needed in your system.
-  # 
-  # Read Endo-Testing[http://www.mockobjects.com/files/endotesting.pdf] for a much
-  # more in depth description of this process.
-  # 
-  # == Stubs
-  # 
-  # Stubs are objects that allow you to set "stub" responses to
-  # messages. As Martin Fowler points out on his site,
-  # mocks_arent_stubs[http://www.martinfowler.com/articles/mocksArentStubs.html].
-  # Paraphrasing Fowler's paraphrasing
-  # of Gerard Meszaros: Stubs provide canned responses to messages they might receive in a test, while
-  # mocks allow you to specify and, subsquently, verify that certain messages should be received during
-  # the execution of a test.
-  # 
-  # == Partial Mocks/Stubs
-  # 
-  # RSpec also supports partial mocking/stubbing, allowing you to add stub/mock behaviour
-  # to instances of your existing classes. This is generally
-  # something to be avoided, because changes to the class can have ripple effects on
-  # seemingly unrelated specs. When specs fail due to these ripple effects, the fact
-  # that some methods are being mocked can make it difficult to understand why a
-  # failure is occurring.
-  # 
-  # That said, partials do allow you to expect and
-  # verify interactions with class methods such as +#find+ and +#create+
-  # on Ruby on Rails model classes.
-  # 
-  # == Further Reading
-  # 
-  # There are many different viewpoints about the meaning of mocks and stubs. If you are interested
-  # in learning more, here is some recommended reading:
-  # 
-  # * Mock Objects: http://www.mockobjects.com/
-  # * Endo-Testing: http://www.mockobjects.com/files/endotesting.pdf
-  # * Mock Roles, Not Objects: http://www.mockobjects.com/files/mockrolesnotobjects.pdf
-  # * Test Double Patterns: http://xunitpatterns.com/Test%20Double%20Patterns.html
-  # * Mocks aren't stubs: http://www.martinfowler.com/articles/mocksArentStubs.html
-  #
-  # == Creating a Mock
-  #
-  # You can create a mock in any specification (or setup) using:
+  #   book = double("book")
   #
-  #   double(name, options={})
+  # == Method Stubs
   #
-  # The optional +options+ argument is a +Hash+. Currently the only supported
-  # option is +:null_object+. Setting this to true instructs the mock to ignore
-  # any messages it hasn’t been told to expect – and quietly return itself. For example:
+  # A method stub is an implementation that returns a pre-determined value.
   #
-  #   double("person", :null_object => true)
+  #   book = double("book")
+  #   double.stub(:title) { "The RSpec Book" }
+  #   double.title => "The RSpec Book"
   #
-  # == Creating a Stub
+  # When we declare a stub, we way we "stubbing" a method.
   #
-  # You can create a stub in any specification (or setup) using:
+  # == Message Expectations
   #
-  #   stub(name, stub_methods_and_values_hash)
+  # A message expectation is an expectation that the test double will receive a
+  # message some time before the example ends. If the message is received, the
+  # expectation is satisfied. If not, the example fails.
   #
-  # For example, if you wanted to create an object that always returns
-  # "More?!?!?!" to "please_sir_may_i_have_some_more" you would do this:
-  #
-  #   stub("Mr Sykes", :please_sir_may_i_have_some_more => "More?!?!?!")
-  #
-  # == Creating a Partial Mock
-  #
-  # You don't really "create" a partial mock, you simply add method stubs and/or
-  # mock expectations to existing classes and objects:
-  #
-  #   Factory.should_receive(:find).with(id).and_return(value)
-  #   obj.stub(:to_i).and_return(3)
-  #   etc ...
-  #
-  # == Expecting Messages
-  #
-  #   my_mock.should_receive(:sym)
-  #   my_mock.should_not_receive(:sym)
+  #   registrar = double("registrar")
+  #   validator.should_receive(:validate).with("02134")
+  #   zipcode = Zipcode.new("02134", validator)
+  #   zipcode.valid?
   #   
+  # When we declare a message expectation, we way we "mocking" a method.
+  #
+  # == Mock Objects and Test Stubs
+  #
+  # The names Mock Object and Test Stub suggest specialized Test Doubles.  i.e.
+  # Test Stub evokes Test Double that only supports method stubs, and a Mock
+  # Object evokes a Test Double that only supports message expectations, or
+  # sometimes supports message expectations in addition to method stubs.
+  #
+  # There is a lot of overlapping nomenclature here, and there are many
+  # variations of these patterns (fakes, spies, etc). Keep in mind that most of
+  # the time we're talking about method-level concepts that are variations of
+  # method stubs and message expectations, and we're applying to them to _one_
+  # generic kind of object: a Test Double.
+  #
+  # == Test-Specific Extension
+  #
+  # a.k.a. Partial Stub/Mock, a Test-Specific Extension is an extension of a
+  # real object in a system that is instrumented with test-double like
+  # behaviour in the context of a test. This technique is very common in Ruby
+  # because we often see class objects acting as global namespaces for methods.
+  # For example, in Rails:
+  #
+  #   person = double("person")
+  #   Person.stub(:find) { person }
+  #
+  # In this case we're instrumenting Person to return the person object we've
+  # defined whenever it receives the +find+ message. We can do this with any
+  # object in a system because RSpec adds the +stub+ and +should_receive+
+  # methods to every object. When we use either, RSpec replaces the method
+  # we're stubbing or mocking with it's own test-double-like method. At the
+  # end of the example, RSpec verifies any message expectations, and then
+  # restores the original methods.
+  # 
   # == Expecting Arguments
   #
-  #   my_mock.should_receive(:sym).with(*args)
-  #   my_mock.should_not_receive(:sym).with(*args)
+  #   double.should_receive(:msg).with(*args)
+  #   double.should_not_receive(:msg).with(*args)
   #
   # == Argument Matchers
   #
@@ -112,68 +77,71 @@ module Rspec
   # using == by default. In cases in which you want to specify things about the arguments
   # rather than the arguments themselves, you can use any of RSpec's Expression Matchers.
   # They don't all make syntactic sense (they were primarily designed for use with
-  # Rspec::Expectations), but you are free to create your own custom Rspec::Matchers.
+  # RSpec::Expectations), but you are free to create your own custom RSpec::Matchers.
   #
-  # Rspec::Mocks does provide one additional Matcher method named #ducktype.
+  # RSpec::Mocks does provide one additional Matcher method named #ducktype.
   #
-  # In addition, Rspec::Mocks adds some keyword Symbols that you can use to
+  # In addition, RSpec::Mocks adds some keyword Symbols that you can use to
   # specify certain kinds of arguments:
   #
-  #   my_mock.should_receive(:sym).with(no_args())
-  #   my_mock.should_receive(:sym).with(any_args())
-  #   my_mock.should_receive(:sym).with(1, kind_of(Numeric), "b") #2nd argument can any kind of Numeric
-  #   my_mock.should_receive(:sym).with(1, boolean(), "b") #2nd argument can true or false
-  #   my_mock.should_receive(:sym).with(1, /abc/, "b") #2nd argument can be any String matching the submitted Regexp
-  #   my_mock.should_receive(:sym).with(1, anything(), "b") #2nd argument can be anything at all
-  #   my_mock.should_receive(:sym).with(1, ducktype(:abs, :div), "b")
+  #   double.should_receive(:msg).with(no_args())
+  #   double.should_receive(:msg).with(any_args())
+  #   double.should_receive(:msg).with(1, kind_of(Numeric), "b") #2nd argument can any kind of Numeric
+  #   double.should_receive(:msg).with(1, boolean(), "b") #2nd argument can true or false
+  #   double.should_receive(:msg).with(1, /abc/, "b") #2nd argument can be any String matching the submitted Regexp
+  #   double.should_receive(:msg).with(1, anything(), "b") #2nd argument can be anything at all
+  #   double.should_receive(:msg).with(1, ducktype(:abs, :div), "b")
   #                            #2nd argument can be object that responds to #abs and #div
   #                                                                       
   # == Receive Counts
   #
-  #   my_mock.should_receive(:sym).once
-  #   my_mock.should_receive(:sym).twice
-  #   my_mock.should_receive(:sym).exactly(n).times
-  #   my_mock.should_receive(:sym).at_least(:once)
-  #   my_mock.should_receive(:sym).at_least(:twice)
-  #   my_mock.should_receive(:sym).at_least(n).times
-  #   my_mock.should_receive(:sym).at_most(:once)
-  #   my_mock.should_receive(:sym).at_most(:twice)
-  #   my_mock.should_receive(:sym).at_most(n).times
-  #   my_mock.should_receive(:sym).any_number_of_times
+  #   double.should_receive(:msg).once
+  #   double.should_receive(:msg).twice
+  #   double.should_receive(:msg).exactly(n).times
+  #   double.should_receive(:msg).at_least(:once)
+  #   double.should_receive(:msg).at_least(:twice)
+  #   double.should_receive(:msg).at_least(n).times
+  #   double.should_receive(:msg).at_most(:once)
+  #   double.should_receive(:msg).at_most(:twice)
+  #   double.should_receive(:msg).at_most(n).times
+  #   double.should_receive(:msg).any_number_of_times
   #
   # == Ordering
   #
-  #   my_mock.should_receive(:sym).ordered
-  #   my_mock.should_receive(:other_sym).ordered
+  #   double.should_receive(:msg).ordered
+  #   double.should_receive(:other_msg).ordered
   #     #This will fail if the messages are received out of order
   #
   # == Setting Reponses
   #
-  # Whether you are setting a mock expectation or a simple stub, you can tell the
-  # object precisely how to respond:
+  # Whether you are setting a message expectation or a method stub, you can
+  # tell the object precisely how to respond. The most generic way is to pass
+  # a block to +stub+ or +should_receive+:
+  #
+  #   double.should_receive(:msg) { value }
+  #
+  # When the double receives the +msg+ message, it evaluates the block and returns
+  # the result.
   #
-  #   my_mock.should_receive(:sym).and_return(value)
-  #   my_mock.should_receive(:sym).exactly(3).times.and_return(value1, value2, value3)
+  #   double.should_receive(:msg).and_return(value)
+  #   double.should_receive(:msg).exactly(3).times.and_return(value1, value2, value3)
   #     # returns value1 the first time, value2 the second, etc
-  #   my_mock.should_receive(:sym).and_return { ... } #returns value returned by the block
-  #   my_mock.should_receive(:sym).and_raise(error)
+  #   double.should_receive(:msg).and_raise(error)
   #     #error can be an instantiated object or a class
   #     #if it is a class, it must be instantiable with no args
-  #   my_mock.should_receive(:sym).and_throw(:sym)
-  #   my_mock.should_receive(:sym).and_yield(values,to,yield)
-  #   my_mock.should_receive(:sym).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+  #   double.should_receive(:msg).and_throw(:msg)
+  #   double.should_receive(:msg).and_yield(values,to,yield)
+  #   double.should_receive(:msg).and_yield(values,to,yield).and_yield(some,other,values,this,time)
   #     # for methods that yield to a block multiple times
   #
-  # Any of these responses can be applied to a stub as well, but stubs do
-  # not support any qualifiers about the message received (i.e. you can't specify arguments
-  # or receive counts):
+  # Any of these responses can be applied to a stub as well
   #
-  #   my_mock.stub(:sym).and_return(value)
-  #   my_mock.stub(:sym).and_return(value1, value2, value3)
-  #   my_mock.stub(:sym).and_raise(error)
-  #   my_mock.stub(:sym).and_throw(:sym)
-  #   my_mock.stub(:sym).and_yield(values,to,yield)
-  #   my_mock.stub(:sym).and_yield(values,to,yield).and_yield(some,other,values,this,time)
+  #   double.stub(:msg).and_return(value)
+  #   double.stub(:msg).and_return(value1, value2, value3)
+  #   double.stub(:msg).and_raise(error)
+  #   double.stub(:msg).and_throw(:msg)
+  #   double.stub(:msg).and_yield(values,to,yield)
+  #   double.stub(:msg).and_yield(values,to,yield).and_yield(some,other,values,this,time)
   #
   # == Arbitrary Handling
   #
@@ -182,21 +150,28 @@ module Rspec
   # to come with an Array argument that has a specific length, but you don't care
   # what is in it. You could do this:
   #
-  #   my_mock.should_receive(:sym) do |arg|
+  #   double.should_receive(:msg) do |arg|
   #     arg.should be_an_istance_of(Array)
   #     arg.length.should == 7
   #   end
   #
-  # Note that this would fail if the number of arguments received was different from
-  # the number of block arguments (in this case 1).
-  #
   # == Combining Expectation Details
   #
   # Combining the message name with specific arguments, receive counts and responses
   # you can get quite a bit of detail in your expectations:
   #
-  #   my_mock.should_receive(:<<).with("illegal value").once.and_raise(ArgumentError)
+  #   double.should_receive(:<<).with("illegal value").once.and_raise(ArgumentError)
+  #
+  # == Further Reading
+  # 
+  # There are many different viewpoints about the meaning of mocks and stubs. If you are interested
+  # in learning more, here is some recommended reading:
+  # 
+  # * Mock Objects: http://www.mockobjects.com/
+  # * Endo-Testing: http://www.mockobjects.com/files/endotesting.pdf
+  # * Mock Roles, Not Objects: http://www.mockobjects.com/files/mockrolesnotobjects.pdf
+  # * Test Double Patterns: http://xunitpatterns.com/Test%20Double%20Patterns.html
+  # * Mocks aren't stubs: http://www.martinfowler.com/articles/mocksArentStubs.html
   module Mocks
   end
-  
 end