mocha 0.10.5 → 0.11.0

data/lib/mocha/mockery.rb

@@ -7,41 +7,41 @@ require 'mocha/configuration'
 require 'mocha/stubbing_error'
 
 module Mocha
-  
+
   class Mockery
-    
+
     class << self
-      
+
       def instance
         @instance ||= new
       end
-      
+
       def reset_instance
         @instance = nil
       end
-      
+
     end
-    
+
     def named_mock(name, &block)
       add_mock(Mock.new(self, Name.new(name), &block))
     end
-    
+
     def unnamed_mock(&block)
       add_mock(Mock.new(self, &block))
     end
-    
+
     def mock_impersonating(object, &block)
       add_mock(Mock.new(self, ImpersonatingName.new(object), &block))
     end
-    
+
     def mock_impersonating_any_instance_of(klass, &block)
       add_mock(Mock.new(self, ImpersonatingAnyInstanceName.new(klass), &block))
     end
-    
+
     def new_state_machine(name)
       add_state_machine(StateMachine.new(name))
     end
-    
+
     def verify(assertion_counter = nil)
       unless mocks.all? { |mock| mock.__verified__?(assertion_counter) }
         message = "not all expectations were satisfied\n#{mocha_inspect}"
@@ -60,24 +60,24 @@ module Mocha
         end
       end
     end
-    
+
     def teardown
       stubba.unstub_all
       reset
     end
-    
+
     def stubba
       @stubba ||= Central.new
     end
-    
+
     def mocks
       @mocks ||= []
     end
-    
+
     def state_machines
       @state_machines ||= []
     end
-    
+
     def mocha_inspect
       message = ""
       message << "unsatisfied expectations:\n- #{unsatisfied_expectations.map { |e| e.mocha_inspect }.join("\n- ")}\n" unless unsatisfied_expectations.empty?
@@ -85,7 +85,7 @@ module Mocha
       message << "states:\n- #{state_machines.map { |sm| sm.mocha_inspect }.join("\n- ")}" unless state_machines.empty?
       message
     end
-    
+
     def on_stubbing(object, method)
       method = RUBY_VERSION < '1.9' ? method.to_s : method.to_sym
       unless Mocha::Configuration.allow?(:stubbing_non_existent_method)
@@ -98,11 +98,16 @@ module Mocha
           on_stubbing_non_public_method(object, method)
         end
       end
+      unless Mocha::Configuration.allow?(:stubbing_method_on_nil)
+        if object.nil?
+          on_stubbing_method_on_nil(object, method)
+        end
+      end
       unless Mocha::Configuration.allow?(:stubbing_method_on_non_mock_object)
         on_stubbing_method_on_non_mock_object(object, method)
       end
     end
-    
+
     def on_stubbing_non_existent_method(object, method)
       if Mocha::Configuration.prevent?(:stubbing_non_existent_method)
         raise StubbingError.new("stubbing non-existent method: #{object.mocha_inspect}.#{method}", caller)
@@ -111,7 +116,7 @@ module Mocha
         logger.warn "stubbing non-existent method: #{object.mocha_inspect}.#{method}"
       end
     end
-    
+
     def on_stubbing_non_public_method(object, method)
       if Mocha::Configuration.prevent?(:stubbing_non_public_method)
         raise StubbingError.new("stubbing non-public method: #{object.mocha_inspect}.#{method}", caller)
@@ -120,7 +125,16 @@ module Mocha
         logger.warn "stubbing non-public method: #{object.mocha_inspect}.#{method}"
       end
     end
-    
+
+    def on_stubbing_method_on_nil(object, method)
+      if Mocha::Configuration.prevent?(:stubbing_method_on_nil)
+        raise StubbingError.new("stubbing method on nil: #{object.mocha_inspect}.#{method}", caller)
+      end
+      if Mocha::Configuration.warn_when?(:stubbing_method_on_nil)
+        logger.warn "stubbing method on nil: #{object.mocha_inspect}.#{method}"
+      end
+    end
+
     def on_stubbing_method_on_non_mock_object(object, method)
       if Mocha::Configuration.prevent?(:stubbing_method_on_non_mock_object)
         raise StubbingError.new("stubbing method on non-mock object: #{object.mocha_inspect}.#{method}", caller)
@@ -129,7 +143,7 @@ module Mocha
         logger.warn "stubbing method on non-mock object: #{object.mocha_inspect}.#{method}"
       end
     end
-    
+
     def on_stubbing_method_unnecessarily(expectation)
       if Mocha::Configuration.prevent?(:stubbing_method_unnecessarily)
         raise StubbingError.new("stubbing method unnecessarily: #{expectation.method_signature}", expectation.backtrace)
@@ -138,44 +152,44 @@ module Mocha
         logger.warn "stubbing method unnecessarily: #{expectation.method_signature}"
       end
     end
-    
+
     attr_writer :logger
-    
+
     def logger
       @logger ||= Logger.new($stderr)
     end
-    
-    
+
+
     private
-    
+
     def expectations
       mocks.map { |mock| mock.__expectations__.to_a }.flatten
     end
-    
+
     def unsatisfied_expectations
       expectations.reject { |e| e.verified? }
     end
-    
+
     def satisfied_expectations
       expectations.select { |e| e.verified? }
     end
-    
+
     def add_mock(mock)
       mocks << mock
       mock
     end
-    
+
     def add_state_machine(state_machine)
       state_machines << state_machine
       state_machine
     end
-    
+
     def reset
       @stubba = nil
       @mocks = nil
       @state_machines = nil
     end
-    
+
   end
-  
+
 end

data/lib/mocha/module_method.rb

@@ -12,5 +12,5 @@ module Mocha
     end
 
   end
-  
-end
+
+end

data/lib/mocha/multiple_yields.rb

@@ -1,20 +1,20 @@
-module Mocha # :nodoc:
-  
-  class MultipleYields # :nodoc:
-    
+module Mocha
+
+  class MultipleYields
+
     attr_reader :parameter_groups
-    
+
     def initialize(*parameter_groups)
       @parameter_groups = parameter_groups
     end
-    
+
     def each
       @parameter_groups.each do |parameter_group|
         yield(parameter_group)
       end
     end
-    
+
   end
-  
+
 end
-    
+

data/lib/mocha/names.rb

@@ -1,53 +1,53 @@
 module Mocha
-  
+
   class ImpersonatingName
-    
+
     def initialize(object)
       @object = object
     end
-    
+
     def mocha_inspect
       @object.mocha_inspect
     end
-    
+
   end
-  
+
   class ImpersonatingAnyInstanceName
-    
+
     def initialize(klass)
       @klass = klass
     end
-    
+
     def mocha_inspect
       "#<AnyInstance:#{@klass.mocha_inspect}>"
     end
-    
+
   end
-  
+
   class Name
-    
+
     def initialize(name)
       @name = name
     end
-    
+
     def mocha_inspect
       "#<Mock:#{@name}>"
     end
-    
+
   end
-  
+
   class DefaultName
-    
+
     def initialize(mock)
       @mock = mock
     end
-    
+
     def mocha_inspect
       address = @mock.__id__ * 2
       address += 0x100000000 if address < 0
       "#<Mock:0x#{'%x' % address}>"
     end
-    
+
   end
-  
-end
+
+end

data/lib/mocha/no_yields.rb

@@ -1,11 +1,11 @@
-module Mocha # :nodoc:
-  
-  class NoYields # :nodoc:
-    
+module Mocha
+
+  class NoYields
+
     def each
     end
-    
+
   end
-  
+
 end
-    
+

data/lib/mocha/object.rb

@@ -6,42 +6,50 @@ require 'mocha/any_instance_method'
 require 'mocha/argument_iterator'
 
 module Mocha
-  
-  # Methods added to all objects to allow mocking and stubbing on real objects.
+
+  # Methods added to all objects to allow mocking and stubbing on real (i.e. non-mock) objects.
   #
-  # Methods return a Mocha::Expectation which can be further modified by methods on Mocha::Expectation.
+  # Both {#expects} and {#stubs} return an {Expectation} which can be further modified by methods on {Expectation}.
   module ObjectMethods
-  
-    def mocha # :nodoc:
+
+    # @private
+    def mocha
       @mocha ||= Mocha::Mockery.instance.mock_impersonating(self)
     end
-  
-    def reset_mocha # :nodoc:
+
+    # @private
+    def reset_mocha
       @mocha = nil
     end
-  
-    def stubba_method # :nodoc:
+
+    # @private
+    def stubba_method
       Mocha::InstanceMethod
     end
-  
-    def stubba_object # :nodoc:
+
+    # @private
+    def stubba_object
       self
     end
-  
-    # :call-seq: expects(method_name) -> expectation
-    #            expects(method_names_vs_return_values) -> last expectation
+
+    # Adds an expectation that the specified method must be called exactly once with any parameters.
+    #
+    # The original implementation of the method is replaced during the test and then restored at the end of the test.
+    #
+    # @param [Symbol,String] method_name name of expected method
+    # @param [Hash] expected_methods_vs_return_values expected method name symbols as keys and corresponding return values as values - these expectations are setup as if {#expects} were called multiple times.
     #
-    # Adds an expectation that a method identified by +method_name+ Symbol must be called exactly once with any parameters.
-    # Returns the new expectation which can be further modified by methods on Mocha::Expectation.
+    # @overload def expects(method_name)
+    # @overload def expects(expected_methods_vs_return_values)
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
+    # @raise [StubbingError] if attempting to stub method which is not allowed.
+    #
+    # @example Setting up an expectation on a non-mock object.
     #   product = Product.new
     #   product.expects(:save).returns(true)
     #   assert_equal true, product.save
     #
-    # The original implementation of <tt>Product#save</tt> is replaced temporarily.
-    #
-    # The original implementation of <tt>Product#save</tt> is restored at the end of the test.
-    #
-    # If +method_names_vs_return_values+ is a +Hash+, an expectation will be set up for each entry using the key as +method_name+ and value as +return_value+.
+    # @example Setting up multiple expectations on a non-mock object.
     #   product = Product.new
     #   product.expects(:valid? => true, :save => true)
     #
@@ -50,13 +58,18 @@ module Mocha
     #   product = Product.new
     #   product.expects(:valid?).returns(true)
     #   product.expects(:save).returns(true)
-    def expects(method_name_or_hash)
-      if method_name_or_hash.to_s =~ /the[^a-z]*spanish[^a-z]*inquisition/i
+    #
+    # @see Mock#expects
+    def expects(expected_methods_vs_return_values)
+      if expected_methods_vs_return_values.to_s =~ /the[^a-z]*spanish[^a-z]*inquisition/i
         raise Mocha::ExpectationError.new('NOBODY EXPECTS THE SPANISH INQUISITION!')
       end
+      if frozen?
+        raise StubbingError.new("can't stub method on frozen object: #{mocha_inspect}", caller)
+      end
       expectation = nil
       mockery = Mocha::Mockery.instance
-      iterator = ArgumentIterator.new(method_name_or_hash)
+      iterator = ArgumentIterator.new(expected_methods_vs_return_values)
       iterator.each { |*args|
         method_name = args.shift
         mockery.on_stubbing(self, method_name)
@@ -67,21 +80,23 @@ module Mocha
       }
       expectation
     end
-  
-    # :call-seq: stubs(method_name) -> expectation
-    #            stubs(method_names_vs_return_values) -> last expectation
+
+    # Adds an expectation that the specified method may be called any number of times with any parameters.
     #
-    # Adds an expectation that a method identified by +method_name+ Symbol may be called any number of times with any parameters.
-    # Returns the new expectation which can be further modified by methods on Mocha::Expectation.
+    # @param [Symbol,String] method_name name of stubbed method
+    # @param [Hash] stubbed_methods_vs_return_values stubbed method name symbols as keys and corresponding return values as values - these stubbed methods are setup as if {#stubs} were called multiple times.
+    #
+    # @overload def stubs(method_name)
+    # @overload def stubs(stubbed_methods_vs_return_values)
+    # @return [Expectation] last-built expectation which can be further modified by methods on {Expectation}.
+    # @raise [StubbingError] if attempting to stub method which is not allowed.
+    #
+    # @example Setting up a stubbed methods on a non-mock object.
     #   product = Product.new
     #   product.stubs(:save).returns(true)
     #   assert_equal true, product.save
     #
-    # The original implementation of <tt>Product#save</tt> is replaced temporarily.
-    #
-    # The original implementation of <tt>Product#save</tt> is restored at the end of the test.
-    #
-    # If +method_names_vs_return_values+ is a +Hash+, an expectation will be set up for each entry using the key as +method_name+ and value as +return_value+.
+    # @example Setting up multiple stubbed methods on a non-mock object.
     #   product = Product.new
     #   product.stubs(:valid? => true, :save => true)
     #
@@ -90,10 +105,15 @@ module Mocha
     #   product = Product.new
     #   product.stubs(:valid?).returns(true)
     #   product.stubs(:save).returns(true)
-    def stubs(method_name_or_hash)
+    #
+    # @see Mock#stubs
+    def stubs(stubbed_methods_vs_return_values)
+      if frozen?
+        raise StubbingError.new("can't stub method on frozen object: #{mocha_inspect}", caller)
+      end
       expectation = nil
       mockery = Mocha::Mockery.instance
-      iterator = ArgumentIterator.new(method_name_or_hash)
+      iterator = ArgumentIterator.new(stubbed_methods_vs_return_values)
       iterator.each { |*args|
         method_name = args.shift
         mockery.on_stubbing(self, method_name)
@@ -104,26 +124,24 @@ module Mocha
       }
       expectation
     end
-    
-    # :call-seq: unstub(*method_names)
+
+    # Removes the specified stubbed methods (added by calls to {#expects} or {#stubs}) and all expectations associated with them.
+    #
+    # Restores the original behaviour of the methods before they were stubbed.
     #
-    # Removes the method stub added by calls to #expects or #stubs.
-    # Restores the original behaviour of the method before it was stubbed.
+    # WARNING: If you {#unstub} a method which still has unsatisfied expectations, you may be removing the only way those expectations can be satisfied. Use {#unstub} with care.
+    #
+    # @param [Array<Symbol>] method_names names of methods to unstub.
+    #
+    # @example Stubbing and unstubbing a method on a real (non-mock) object.
     #   multiplier = Multiplier.new
     #   multiplier.double(2) # => 4
-    #   multiplier.stubs(:double).raises
+    #   multiplier.stubs(:double).raises # new behaviour defined
     #   multiplier.double(2) # => raises exception
-    #   multiplier.unstub(:double)
+    #   multiplier.unstub(:double) # original behaviour restored
     #   multiplier.double(2) # => 4
     #
-    # The original implementation of <tt>Multiplier#double</tt> is replaced temporarily.
-    #
-    # The original implementation of <tt>Multiplier#double</tt> is restored when #unstub is called.
-    #
-    # WARNING: If you #unstub a method which still has unsatisfied expectations, you may be removing
-    # the only way those expectations can be satisfied. Use #unstub with care.
-    #
-    # If multiple +method_names+ are supplied, each method is unstubbed.
+    # @example Unstubbing multiple methods on a real (non-mock) object.
     #   multiplier.unstub(:double, :triple)
     #
     #   # exactly equivalent to
@@ -137,8 +155,9 @@ module Mocha
         mockery.stubba.unstub(method)
       end
     end
-  
-    def method_exists?(method, include_public_methods = true) # :nodoc:
+
+    # @private
+    def method_exists?(method, include_public_methods = true)
       if include_public_methods
         return true if public_methods(include_superclass_methods = true).include?(method)
         return true if respond_to?(method.to_sym)
@@ -147,30 +166,33 @@ module Mocha
       return true if private_methods(include_superclass_methods = true).include?(method)
       return false
     end
-  
+
   end
-  
-  module ModuleMethods # :nodoc:
-    
+
+  # @private
+  module ModuleMethods
+
     def stubba_method
       Mocha::ModuleMethod
     end
-    
+
   end
-  
-  # Methods added all classes to allow mocking and stubbing on real objects.
+
+  # Methods added to all classes to allow mocking and stubbing on real (i.e. non-mock) objects.
   module ClassMethods
-    
-    def stubba_method # :nodoc:
+
+    # @private
+    def stubba_method
       Mocha::ClassMethod
     end
 
-    class AnyInstance # :nodoc:
-    
+    # @private
+    class AnyInstance
+
       def initialize(klass)
         @stubba_object = klass
       end
-    
+
       def mocha
         @mocha ||= Mocha::Mockery.instance.mock_impersonating_any_instance_of(@stubba_object)
       end
@@ -178,11 +200,11 @@ module Mocha
       def stubba_method
         Mocha::AnyInstanceMethod
       end
-    
+
       def stubba_object
         @stubba_object
       end
-    
+
       def method_exists?(method, include_public_methods = true)
         if include_public_methods
           return true if @stubba_object.public_instance_methods(include_superclass_methods = true).include?(method)
@@ -191,33 +213,40 @@ module Mocha
         return true if @stubba_object.private_instance_methods(include_superclass_methods = true).include?(method)
         return false
       end
-    
+
     end
-  
-    # :call-seq: any_instance -> mock object
+
+    # @return [Mock] a mock object which will detect calls to any instance of this class.
+    # @raise [StubbingError] if attempting to stub method which is not allowed.
     #
-    # Returns a mock object which will detect calls to any instance of this class.
+    # @example Return false to invocation of +Product#save+ for any instance of +Product+.
     #   Product.any_instance.stubs(:save).returns(false)
     #   product_1 = Product.new
     #   assert_equal false, product_1.save
     #   product_2 = Product.new
     #   assert_equal false, product_2.save
     def any_instance
+      if frozen?
+        raise StubbingError.new("can't stub method on frozen object: #{mocha_inspect}.any_instance", caller)
+      end
       @any_instance ||= AnyInstance.new(self)
     end
-  
+
   end
-  
+
 end
 
-class Object # :nodoc:
+# @private
+class Object
   include Mocha::ObjectMethods
 end
 
-class Module # :nodoc:
+# @private
+class Module
   include Mocha::ModuleMethods
 end
 
-class Class # :nodoc:
+# @private
+class Class
   include Mocha::ClassMethods
 end