rspec-mocks 2.8.0.rc1 → 2.8.0.rc2

data/lib/rspec/mocks/method_double.rb

@@ -1,8 +1,11 @@
 module RSpec
   module Mocks
+    # @private
     class MethodDouble < Hash
+      # @private
       attr_reader :method_name
 
+      # @private
       def initialize(object, method_name, proxy)
         @method_name = method_name
         @object = object
@@ -12,14 +15,17 @@ module RSpec
         store(:stubs, [])
       end
 
+      # @private
       def expectations
         self[:expectations]
       end
 
+      # @private
       def stubs
         self[:stubs]
       end
 
+      # @private
       def visibility
         if Mock === @object
           'public'
@@ -32,18 +38,22 @@ module RSpec
         end
       end
 
+      # @private
       def object_singleton_class
         class << @object; self; end
       end
 
+      # @private
       def obfuscate(method_name)
         "obfuscated_by_rspec_mocks__#{method_name}"
       end
 
+      # @private
       def stashed_method_name
         obfuscate(method_name)
       end
 
+      # @private
       def object_responds_to?(method_name)
         if @proxy.already_proxied_respond_to?
           @object.__send__(obfuscate(:respond_to?), method_name)
@@ -54,6 +64,7 @@ module RSpec
         end
       end
 
+      # @private
       def configure_method
         RSpec::Mocks::space.add(@object) if RSpec::Mocks::space
         warn_if_nil_class
@@ -63,6 +74,7 @@ module RSpec
         end
       end
 
+      # @private
       def stash_original_method
         stashed = stashed_method_name
         orig = @method_name
@@ -72,6 +84,7 @@ module RSpec
         @stashed = true
       end
 
+      # @private
       def define_proxy_method
         method_name = @method_name
         visibility_for_method = "#{visibility} :#{method_name}"
@@ -79,10 +92,11 @@ module RSpec
           def #{method_name}(*args, &block)
             __mock_proxy.message_received :#{method_name}, *args, &block
           end
-          #{visibility_for_method}
+        #{visibility_for_method}
         EOF
       end
 
+      # @private
       def restore_original_method
         if @stashed
           method_name = @method_name
@@ -98,32 +112,37 @@ module RSpec
         end
       end
 
+      # @private
       def verify
         expectations.each {|e| e.verify_messages_received}
       end
 
+      # @private
       def reset
         reset_nil_expectations_warning
         restore_original_method
         clear
       end
 
+      # @private
       def clear
         expectations.clear
         stubs.clear
       end
 
+      # @private
       def add_expectation(error_generator, expectation_ordering, expected_from, opts, &block)
         configure_method
         expectation = if existing_stub = stubs.first
-          existing_stub.build_child(expected_from, block, 1, opts)
-        else
-          MessageExpectation.new(error_generator, expectation_ordering, expected_from, @method_name, block, 1, opts)
-        end
+                        existing_stub.build_child(expected_from, block, 1, opts)
+                      else
+                        MessageExpectation.new(error_generator, expectation_ordering, expected_from, @method_name, block, 1, opts)
+                      end
         expectations << expectation
         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, @method_name, implementation)
@@ -131,32 +150,38 @@ module RSpec
         expectation
       end
 
+      # @private
       def add_stub(error_generator, expectation_ordering, expected_from, opts={}, &implementation)
         configure_method
         stub = MessageExpectation.new(error_generator, expectation_ordering, expected_from, @method_name, nil, :any, opts, &implementation)
         stubs.unshift stub
         stub
       end
-      
+
+      # @private
       def remove_stub
         raise_method_not_stubbed_error if stubs.empty?
         expectations.empty? ? reset : stubs.clear
       end
 
+      # @private
       def proxy_for_nil_class?
         @object.nil?
       end
 
+      # @private
       def warn_if_nil_class
         if proxy_for_nil_class? & RSpec::Mocks::Proxy.warn_about_expectations_on_nil
           Kernel.warn("An expectation of :#{@method_name} was set on nil. Called from #{caller[4]}. Use allow_message_expectations_on_nil to disable warnings.")
         end
       end
-      
+
+      # @private
       def raise_method_not_stubbed_error
         raise MockExpectationError, "The method `#{method_name}` was not stubbed or was already unstubbed" 
       end
 
+      # @private
       def reset_nil_expectations_warning
         RSpec::Mocks::Proxy.warn_about_expectations_on_nil = true if proxy_for_nil_class?
       end

data/lib/rspec/mocks/methods.rb

@@ -1,37 +1,82 @@
 module RSpec
   module Mocks
+    # Methods that are added to every object.
     module Methods
-      def should_receive(sym, opts={}, &block)
-        __mock_proxy.add_message_expectation(opts[:expected_from] || caller(1)[0], sym.to_sym, opts, &block)
+      # Sets and expectation that this object should receive a message before
+      # the end of the example.
+      #
+      # @example
+      #
+      #     logger = double('logger')
+      #     thing_that_logs = ThingThatLogs.new(logger)
+      #     logger.should_receive(:log)
+      #     thing_that_logs.do_something_that_logs_a_message
+      def should_receive(message, opts={}, &block)
+        __mock_proxy.add_message_expectation(opts[:expected_from] || caller(1)[0], message.to_sym, opts, &block)
       end
 
-      def should_not_receive(sym, &block)
-        __mock_proxy.add_negative_message_expectation(caller(1)[0], sym.to_sym, &block)
+      # Sets and expectation that this object should _not_ receive a message
+      # during this example.
+      def should_not_receive(message, &block)
+        __mock_proxy.add_negative_message_expectation(caller(1)[0], message.to_sym, &block)
       end
-      
-      def stub(sym_or_hash, opts={}, &block)
-        if Hash === sym_or_hash
-          sym_or_hash.each {|method, value| stub(method).and_return value }
+
+      # Tells the object to respond to the message with the specified value.
+      #
+      # @example
+      #
+      #     counter.stub(:count).and_return(37)
+      #     counter.stub(:count => 37)
+      #     counter.stub(:count) { 37 }
+      def stub(message_or_hash, opts={}, &block)
+        if Hash === message_or_hash
+          message_or_hash.each {|message, value| stub(message).and_return value }
         else
-          __mock_proxy.add_stub(caller(1)[0], sym_or_hash.to_sym, opts, &block)
+          __mock_proxy.add_stub(caller(1)[0], message_or_hash.to_sym, opts, &block)
         end
       end
-      
-      def unstub(sym)
-        __mock_proxy.remove_stub(sym)
+
+      # Removes a stub. On a double, the object will no longer respond to
+      # `message`. On a real object, the original method (if it exists) is
+      # restored.
+      #
+      # This is rarely used, but can be useful when a stub is set up during a
+      # shared `before` hook for the common case, but you want to replace it
+      # for a special case.
+      def unstub(message)
+        __mock_proxy.remove_stub(message)
       end
-      
+
       alias_method :stub!, :stub
       alias_method :unstub!, :unstub
-      
-      # Stubs a chain of methods. Especially useful with fluent and/or
-      # composable interfaces.
+
+      # @overload stub_chain(method1, method2)
+      # @overload stub_chain("method1.method2")
+      # @overload stub_chain(method1, method_to_value_hash)
+      #
+      # Stubs a chain of methods.
+      #
+      # ## Warning:
+      #
+      # Chains can be arbitrarily long, which makes it quite painless to
+      # violate the Law of Demeter in violent ways, so you should consider any
+      # use of `stub_chain` a code smell. Even though not all code smells
+      # indicate real problems (think fluent interfaces), `stub_chain` still
+      # results in brittle examples.  For example, if you write
+      # `foo.stub_chain(:bar, :baz => 37)` in a spec and then the
+      # implementation calls `foo.baz.bar`, the stub will not work.
       #
-      # == Examples
+      # @example
       #
-      #   double.stub_chain("foo.bar") { :baz }
-      #   double.stub_chain(:foo, :bar) { :baz }
-      #   Article.stub_chain("recent.published") { [Article.new] }
+      #     double.stub_chain("foo.bar") { :baz }
+      #     double.stub_chain(:foo, :bar => :baz)
+      #     double.stub_chain(:foo, :bar) { :baz }
+      #
+      #     # Given any of ^^ these three forms ^^:
+      #     double.foo.bar # => :baz
+      #
+      #     # Common use in Rails/ActiveRecord:
+      #     Article.stub_chain("recent.published") { [Article.new] }
       def stub_chain(*chain, &blk)
         chain, blk = format_chain(*chain, &blk)
         if chain.length > 1
@@ -47,26 +92,33 @@ module RSpec
           stub(chain.shift, &blk)
         end
       end
-      
+
+      # Tells the object to respond to all messages. If specific stub values
+      # are declared, they'll work as expected. If not, the receiver is
+      # returned.
+      def as_null_object
+        __mock_proxy.as_null_object
+      end
+
+      # Returns true if this object has received `as_null_object`
+      def null_object?
+        __mock_proxy.null_object?
+      end
+
+      # @private
       def received_message?(sym, *args, &block)
         __mock_proxy.received_message?(sym.to_sym, *args, &block)
       end
-      
+
+      # @private
       def rspec_verify
         __mock_proxy.verify
       end
 
+      # @private
       def rspec_reset
         __mock_proxy.reset
       end
-      
-      def as_null_object
-        __mock_proxy.as_null_object
-      end
-      
-      def null_object?
-        __mock_proxy.null_object?
-      end
 
     private
 

data/lib/rspec/mocks/mock.rb

@@ -3,8 +3,8 @@ module RSpec
     class Mock
       include Methods
 
-      # Creates a new test double with a +name+ (that will be used in error messages
-      # only)
+      # Creates a new test double with a `name` (that will be used in error
+      # messages only)
       def initialize(name=nil, stubs_and_options={})
         if name.is_a?(Hash) && stubs_and_options.empty?
           stubs_and_options = name
@@ -24,18 +24,21 @@ module RSpec
         other == __mock_proxy
       end
 
+      # @private
       def inspect
         "#<#{self.class}:#{sprintf '0x%x', self.object_id} @name=#{@name.inspect}>"
       end
 
+      # @private
       def to_s
         inspect.gsub('<','[').gsub('>',']')
       end
 
       alias_method :to_str, :to_s
 
+      # @private
       def respond_to?(sym, incl_private=false)
-        __mock_proxy.null_object? && sym != :to_ary ? true : super 
+        __mock_proxy.null_object? && sym != :to_ary ? true : super
       end
 
     private
@@ -59,7 +62,7 @@ module RSpec
         extract_option(stubs_and_options, options, :__declared_as, 'Mock')
         options
       end
-      
+
       def extract_option(source, target, key, default=nil)
         if source[key]
           target[key] = source.delete(key)
@@ -76,4 +79,3 @@ module RSpec
     end
   end
 end
-

data/lib/rspec/mocks/order_group.rb

@@ -1,29 +1,33 @@
 module RSpec
   module Mocks
+    # @private
     class OrderGroup
       def initialize error_generator
         @error_generator = error_generator
         @ordering = Array.new
       end
-      
+
+      # @private
       def register(expectation)
         @ordering << expectation
       end
-      
+
+      # @private
       def ready_for?(expectation)
         return @ordering.first == expectation
       end
-      
+
+      # @private
       def consume
         @ordering.shift
       end
-      
+
+      # @private
       def handle_order_constraint expectation
         return unless @ordering.include? expectation
         return consume if ready_for?(expectation)
         @error_generator.raise_out_of_order_error expectation.sym
       end
-      
     end
   end
 end

data/lib/rspec/mocks/proxy.rb

@@ -1,43 +1,51 @@
 module RSpec
   module Mocks
+    # @private
     class Proxy
       class << self
+        # @private
         def warn_about_expectations_on_nil
           defined?(@warn_about_expectations_on_nil) ? @warn_about_expectations_on_nil : true
         end
-      
+
+        # @private
         def warn_about_expectations_on_nil=(new_value)
           @warn_about_expectations_on_nil = new_value
         end
-      
+
+        # @private
         def allow_message_expectations_on_nil
           @warn_about_expectations_on_nil = false
-          
+
           # ensure nil.rspec_verify is called even if an expectation is not set in the example
           # otherwise the allowance would effect subsequent examples
           RSpec::Mocks::space.add(nil) unless RSpec::Mocks::space.nil?
         end
 
+        # @private
         def allow_message_expectations_on_nil?
           !warn_about_expectations_on_nil
         end
       end
 
+      # @private
       def initialize(object, name=nil, options={})
         @object = object
         @name = name
         @error_generator = ErrorGenerator.new object, name, options
         @expectation_ordering = OrderGroup.new @error_generator
-        @messages_received = []
+          @messages_received = []
         @options = options
         @already_proxied_respond_to = false
         @null_object = false
       end
 
+      # @private
       def null_object?
         @null_object
       end
 
+      # @private
       # Tells the object to ignore any messages that aren't explicitly set as
       # stubs or message expectations.
       def as_null_object
@@ -45,52 +53,64 @@ module RSpec
         @object
       end
 
+      # @private
       def already_proxied_respond_to
         @already_proxied_respond_to = true
       end
 
+      # @private
       def already_proxied_respond_to?
         @already_proxied_respond_to
       end
 
+      # @private
       def add_message_expectation(location, method_name, opts={}, &block)        
         method_double[method_name].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 add_stub(location, method_name, opts={}, &implementation)
         method_double[method_name].add_stub @error_generator, @expectation_ordering, location, opts, &implementation
       end
-      
+
+      # @private
       def remove_stub(method_name)
         method_double[method_name].remove_stub
       end
-      
+
+      # @private
       def verify
         method_doubles.each {|d| d.verify}
       ensure
         reset
       end
 
+      # @private
       def reset
         method_doubles.each {|d| d.reset}
       end
 
+      # @private
       def received_message?(method_name, *args, &block)
         @messages_received.any? {|array| array == [method_name, args, block]}
       end
 
+      # @private
       def has_negative_expectation?(method_name)
         method_double[method_name].expectations.detect {|expectation| expectation.negative_expectation_for?(method_name)}
       end
-      
+
+      # @private
       def record_message_received(method_name, *args, &block)
         @messages_received << [method_name, args, block]
       end
 
+      # @private
       def message_received(method_name, *args, &block)
         expectation = find_matching_expectation(method_name, *args)
         stub = find_matching_method_stub(method_name, *args)
@@ -116,15 +136,17 @@ module RSpec
         end
       end
 
+      # @private
       def raise_unexpected_message_args_error(expectation, *args)
         @error_generator.raise_unexpected_message_args_error(expectation, *args)
       end
 
+      # @private
       def raise_unexpected_message_error(method_name, *args)
         @error_generator.raise_unexpected_message_error method_name, *args
       end
-      
-    private
+
+      private
 
       def method_double
         @method_double ||= Hash.new {|h,k|
@@ -135,10 +157,10 @@ module RSpec
       def method_doubles
         method_double.values
       end
-      
+
       def find_matching_expectation(method_name, *args)
         method_double[method_name].expectations.find {|expectation| expectation.matches?(method_name, *args) && !expectation.called_max_times?} || 
-        method_double[method_name].expectations.find {|expectation| expectation.matches?(method_name, *args)}
+          method_double[method_name].expectations.find {|expectation| expectation.matches?(method_name, *args)}
       end
 
       def find_almost_matching_expectation(method_name, *args)
@@ -152,7 +174,6 @@ module RSpec
       def find_almost_matching_stub(method_name, *args)
         method_double[method_name].stubs.find {|stub| stub.matches_name_but_not_args(method_name, *args)}
       end
-
     end
   end
 end