flexmock 0.6.4 → 0.7.0

data/doc/releases/flexmock-0.7.0.rdoc

@@ -0,0 +1,138 @@
+= FlexMock 0.7.0 Released
+
+FlexMock is a flexible mocking library for use in unit testing and behavior
+specification in Ruby. Version 0.7.0 introduces several enhancements.
+
+== New in 0.7.0
+
+* FlexMock now supports the ability to mock a chain of method calls
+  automatically.  For example:
+
+    car = flexmock("car", "chassis.engine.piston.stroke" => :ok)
+    assert_equal :ok, car.chassis.engine.piston.stroke
+
+  will create a sequence of mocks so that the "chassis" call will
+  return a mock that responds to "engine", which returns a mock that
+  responds to "piston", which returns a mock that responds to
+  "stroke".  This facility makes mocking legacy code that violates the
+  Law of Demeter a bit easier to deal with.
+
+* Added the the +and_yield+ constraint to FlexMock expectations.  This
+  allows the user to easily specify values passed to any block given
+  to the mock method.
+
+* Globally ordering of mocked calls is now optionally available.  When
+  a mock method is globally ordered, it must be called in the correct
+  order with regard to all other globally ordered methods.  Non-global
+  ordering only requires that the method calls be ordered with regard
+  to other methods on the same mock object.
+
+* The output for mock.inspect was modified to be much more consise, so
+  that test framework error messages do not overwhelm the output.
+
+* In order to clean up the method namespace, a number of internally
+  used methods were deprecated.  All non-public methods that get added
+  to mocks, partial mocks or test frameworks now begin with
+  "flexmock_" (rather than "mock_").  The "mock_*" versions are still
+  available, but will display deprecation warnings when used.  The
+  deprecated "mock_*" methods will be removed in a future version.
+
+* Additionally, the ancient "mock_handle" method has been deprecated
+  (prints a warning when used), and will be removed in a future
+  version.  Users are encouraged to use the newer "should_receive"
+  method instead.
+
+== New Features Added in 0.6.x   
+
+In case you missed them, here are a number of features that were added
+during the 0.6.x versions of FlexMock.
+
+* ActiveRecord mocking support with flexmock(:model, ModelName).
+
+* Better partial mock definitions, including a "safe-mode" that
+  minimizes mock namespace pollution in the domain object.
+
+* Support for +and_raise+ constraint to ease the definition of mocks
+  that raise exceptions.
+
+== What is FlexMock?
+
+FlexMock is a flexible framework for creating mock object for testing. When
+running unit tests, it is often desirable to use isolate the objects being
+tested from the "real world" by having them interact with simplified test
+objects. Sometimes these test objects simply return values when called, other
+times they verify that certain methods were called with particular arguments
+in a particular order.
+
+FlexMock makes creating these test objects easy.
+
+=== Features
+
+* Easy integration with both Test::Unit and RSpec. Mocks created with the
+  flexmock method are automatically verified at the end of the test or
+  example.
+
+* A fluent interface that allows mock behavior to be specified very
+  easily.
+
+* A "record mode" where an existing implementation can record its
+  interaction with a mock for later validation against a new
+  implementation.
+
+* Easy mocking of individual methods in existing, non-mock objects.
+
+* The ability to cause classes to instantiate test instances (instead of real
+  instances) for the duration of a test.
+
+=== Example
+
+Suppose you had a Dog object that wagged a tail when it was happy.
+Something like this:
+
+  class Dog
+    def initialize(a_tail)
+      @tail = a_tail
+    end
+    def happy
+      @tail.wag
+    end
+  end
+
+To test the +Dog+ class without a real +Tail+ object (perhaps because
+real +Tail+ objects activate servos in some robotic equipment), you
+can do something like this:
+
+require 'test/unit'
+require 'flexmock/test_unit'
+
+  class TestDog < Test::Unit::TestCase
+    def test_dog_wags_tail_when_happy
+      tail = flexmock("tail")
+      tail.should_receive(:wag).once
+      dog = Dog.new(tail)
+      dog.happy
+    end
+  end
+
+FlexMock will automatically verify that the mocked tail object received the
+message +wag+ exactly one time. If it doesn't, the test will not pass.
+
+See the FlexMock documentation at http://flexmock.rubyforge.org for details on
+specifying arguments and return values on mocked methods, as well as a simple
+technique for mocking tail objects when the Dog class creates the tail objects
+directly.
+
+== Availability
+
+You can make sure you have the latest version with a quick RubyGems command:
+
+  gem install flexmock    (you may need root/admin privileges)
+
+Otherwise, you can get it from the more traditional places:
+
+Download::  http://rubyforge.org/project/showfiles.php?group_id=170
+
+You will find documentation at: http://flexmock.rubyforge.org.
+
+-- Jim Weirich
+

data/lib/flexmock/base.rb

@@ -19,4 +19,5 @@ require 'flexmock/argument_types'
 require 'flexmock/validators'
 require 'flexmock/recorder'
 require 'flexmock/mock_container'
-require 'flexmock/partial_mock'
+require 'flexmock/partial_mock'
+require 'flexmock/deprecated_methods'

data/lib/flexmock/core.rb

@@ -10,6 +10,7 @@
 #+++
 
 require 'flexmock/composite'
+require 'flexmock/ordering'
 
 ######################################################################
 # FlexMock is a flexible mock object framework for supporting testing.
@@ -42,55 +43,49 @@ require 'flexmock/composite'
 # call +super+.
 #
 class FlexMock
+  include Ordering
 
   # Error raised when flexmock is used incorrectly.
   class UsageError < RuntimeError
   end
 
-  attr_reader :mock_name, :mock_groups
-  attr_accessor :mock_current_order, :mock_container
+  class MockError < RuntimeError
+  end
+
+  attr_reader :flexmock_name
+  attr_accessor :flexmock_container
 
   # Create a FlexMock object with the given name.  The name is used in
-  # error messages.
-  def initialize(name="unknown")
-    @mock_name = name
+  # error messages.  If no container is given, create a new, one-off
+  # container for this mock.
+  def initialize(name="unknown", container=nil)
+    @flexmock_name = name
     @expectations = Hash.new
-    @allocated_order = 0
-    @mock_current_order = 0
-    @mock_container = nil
-    @mock_groups = {}
     @ignore_missing = false
     @verified = false
+    container = UseContainer.new if container.nil?
+    container.flexmock_remember(self)
   end
 
-  # Handle all messages denoted by +sym+ by calling the given block
-  # and passing any parameters to the block.  If we know exactly how
-  # many calls are to be made to a particular method, we may check
-  # that by passing in the number of expected calls as a second
-  # paramter.
-  def mock_handle(sym, expected_count=nil, &block) # :nodoc:
-    self.should_receive(sym).times(expected_count).returns(&block)
+  # Return the inspection string for a mock.
+  def inspect
+    "<FlexMock:#{flexmock_name}>"
   end
 
   # Verify that each method that had an explicit expected count was
   # actually called that many times.
-  def mock_verify
+  def flexmock_verify
     return if @verified
     @verified = true
-    mock_wrap do
+    flexmock_wrap do
       @expectations.each do |sym, handler|
-        handler.mock_verify
+        handler.flexmock_verify
       end
     end
   end
 
   # Teardown and infrastructure setup for this mock.
-  def mock_teardown
-  end
-
-  # Allocation a new order number from the mock.
-  def mock_allocate_order
-    @allocated_order += 1
+  def flexmock_teardown
   end
 
   # Ignore all undefined (missing) method calls.
@@ -101,7 +96,7 @@ class FlexMock
 
   # Handle missing methods by attempting to look up a handler.
   def method_missing(sym, *args, &block)
-    mock_wrap do
+    flexmock_wrap do
       if handler = @expectations[sym]
         args << block  if block_given?
         handler.call(*args)
@@ -119,6 +114,12 @@ class FlexMock
     super || (@expectations[sym] ? true : @ignore_missing)
   end
 
+  # Find the mock expectation for method sym and arguments.
+  def flexmock_find_expectation(sym, *args)
+    exp = @expectations[sym]
+    exp ? exp.find_expectation(*args) : nil
+  end
+
   # Override the built-in +method+ to include the mocked methods.
   def method(sym)
     @expectations[sym] || super
@@ -150,7 +151,7 @@ class FlexMock
   # See Expectation for a list of declarators that can be used.
   #
   def should_receive(*args)
-    FlexMock.should_receive(args) do |sym|
+    ContainerHelper.parse_should_args(self, args) do |sym|
       @expectations[sym] ||= ExpectationDirector.new(sym)
       result = Expectation.new(self, sym)
       @expectations[sym] << result
@@ -179,11 +180,11 @@ class FlexMock
 
   # Wrap a block of code so the any assertion errors are wrapped so
   # that the mock name is added to the error message .
-  def mock_wrap(&block)
+  def flexmock_wrap(&block)
     yield
   rescue FlexMock.framework_adapter.assertion_failed_error => ex
     raise FlexMock.framework_adapter.assertion_failed_error,
-    "in mock '#{@mock_name}': #{ex.message}",
+    "in mock '#{@flexmock_name}': #{ex.message}",
     ex.backtrace
   end
   

data/lib/flexmock/core_class_methods.rb

@@ -10,34 +10,12 @@
 #+++
 
 require 'flexmock/noop'
+require 'flexmock/mock_container'
 
 class FlexMock
   class << self
     attr_reader :framework_adapter
 
-    # :call-seq:
-    #   should_receive(args) { |symbol| ... }
-    #
-    # This method provides common handling for the various should_receive
-    # argument lists. It sorts out the differences between symbols, arrays and
-    # hashes, and identifies the method names specified by each.  As each
-    # method name is identified, create a mock expectation for it using the
-    # supplied block.
-    def should_receive(args)  # :nodoc:
-      result = CompositeExpectation.new
-      args.each do |arg|
-        case arg
-        when Hash
-          arg.each do |k,v|
-            result.add(yield(k.to_sym).and_return(v))
-          end
-        when Symbol, String
-          result.add(yield(arg.to_sym))
-        end
-      end
-      result
-    end
-    
     # Class method to make sure that verify is called at the end of a
     # test.  One mock object will be created for each name given to
     # the use method.  The mocks will be passed to the block as
@@ -60,16 +38,14 @@ class FlexMock
     #
     def use(*names)
       names = ["unknown"] if names.empty?
-      got_excecption = false
-      mocks = names.collect { |n| new(n) }
+      container = UseContainer.new
+      mocks = names.collect { |n| container.flexmock(n) }
       yield(*mocks)
     rescue Exception => ex
-      got_exception = true
+      container.got_exception = true
       raise
     ensure
-      mocks.each do |mock|
-        mock.mock_verify     unless got_exception
-      end
+      container.flexmock_teardown
     end
 
     # Class method to format a method name and argument list as a nice
@@ -87,6 +63,21 @@ class FlexMock
     def check(msg, &block)  # :nodoc:
       FlexMock.framework_adapter.assert_block(msg, &block)
     end
+
   end
 
-end
+  # Container object to be used by the FlexMock.use method.  
+  class UseContainer
+    include MockContainer
+    
+    attr_accessor :got_exception
+    
+    def initialize
+      @got_exception = false
+    end
+    
+    def passed?
+      ! got_exception
+    end
+  end
+end

data/lib/flexmock/deprecated_methods.rb

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+#---
+# Copyright 2003, 2004, 2005, 2006, 2007 by Jim Weirich (jim@weirichhouse.org).
+# All rights reserved.
+#
+# Permission is granted for use, copying, modification, distribution,
+# and distribution of modified versions of this work as long as the
+# above copyright notice is included.
+#+++
+
+
+class Module
+  def flexmock_deprecate(*method_names)
+    method_names.each do |method_name|
+      eval_line = __LINE__ + 1
+      module_eval %{
+        def #{method_name}(*args)
+          $stderr.puts "#{method_name} is deprecated, use flex#{method_name} instead"
+          flex#{method_name}(*args)
+        end
+      }, __FILE__, eval_line
+    end
+  end
+end
+
+# Deprecated Methods
+# ==================
+#
+# The following methods are no longer supported in FlexMock.  Include
+# this file for legacy applications.
+#
+class FlexMock
+
+  # Handle all messages denoted by +sym+ by calling the given block
+  # and passing any parameters to the block.  If we know exactly how
+  # many calls are to be made to a particular method, we may check
+  # that by passing in the number of expected calls as a second
+  # paramter.
+  def mock_handle(sym, expected_count=nil, &block) # :nodoc:
+    $stderr.puts "mock_handle is deprecated, use the new should_receive interface instead."
+    self.should_receive(sym).times(expected_count).returns(&block)
+  end
+
+  flexmock_deprecate :mock_verify, :mock_teardown, :mock_wrap
+
+  class PartialMockProxy
+
+    MOCK_METHODS << :any_instance
+
+    # any_instance is present for backwards compatibility with version 0.5.0.
+    # @deprecated
+    def any_instance(&block)
+      $stderr.puts "any_instance is deprecated, use new_instances instead."
+      new_instances(&block)
+    end
+  end
+
+  module Ordering
+    flexmock_deprecate :mock_allocate_order, :mock_groups, :mock_current_order, :mock_validate_order
+  end
+end

data/lib/flexmock/expectation.rb

@@ -39,8 +39,11 @@ class FlexMock
       @count_validator_class = ExactCountValidator
       @actual_count = 0
       @return_value = nil
-      @return_block = lambda { @return_value }
+      @return_queue = []
+      @yield_queue = []
       @order_number = nil
+      @global_order_number = nil
+      @globally = nil
     end
 
     def to_s
@@ -52,9 +55,45 @@ class FlexMock
     def verify_call(*args)
       validate_order
       @actual_count += 1
-      @return_block.call(*args)
+      perform_yielding(args)
+      return_value(args)
     end
 
+    # Public return value (odd name to avoid accidental use as a
+    # constraint).
+    def _return_value(args) # :nodoc:
+      return_value(args)
+    end
+
+    # Find the return value for this expectation. (private version)
+    def return_value(args)
+      case @return_queue.size
+      when 0
+        block = lambda { @return_value }
+      when 1
+        block = @return_queue.first
+      else
+        block = @return_queue.shift
+      end
+      block.call(*args)
+    end
+    private :return_value
+
+    # Yield stored values to any blocks given.
+    def perform_yielding(args)
+      @return_value = nil
+      unless @yield_queue.empty?
+        block = args.last
+        values = (@yield_queue.size == 1) ? @yield_queue.first : @yield_queue.shift
+        if block.respond_to?(:call) 
+          @return_value = block.call(*values)
+        else
+          fail MockError, "No Block given to mock with 'and_yield' expectation"
+        end
+      end
+    end
+    private :perform_yielding
+
     # Is this expectation eligible to be called again?  It is eligible
     # only if all of its count validators agree that it is eligible.
     def eligible?
@@ -63,18 +102,18 @@ class FlexMock
 
     # Validate that the order
     def validate_order
-      return if @order_number.nil?
-      FlexMock.check("method #{to_s} called out of order " +
-      "(expected order #{@order_number}, was #{@mock.mock_current_order})") {
-        @order_number >= @mock.mock_current_order
-      }
-      @mock.mock_current_order = @order_number
+      if @order_number
+        @mock.flexmock_validate_order(to_s, @order_number)
+      end
+      if @global_order_number
+        @mock.flexmock_container.flexmock_validate_order(to_s, @global_order_number)
+      end
     end
     private :validate_order
 
     # Validate the correct number of calls have been made.  Called by
     # the teardown process.
-    def mock_verify
+    def flexmock_verify
       @count_validators.each do |v|
         v.validate(@actual_count)
       end
@@ -142,16 +181,22 @@ class FlexMock
     # +returns+ is an alias for +and_return+.
     #
     def and_return(*args, &block)
-      @return_block = 
-        if block_given? 
-           block
-        else
-          lambda { args.size == 1 ? args.first : args.shift }
+      if block_given? 
+        @return_queue << block
+      else
+        args.each do |arg|
+          @return_queue << lambda { arg }
         end
+      end
       self
     end
     alias :returns :and_return  # :nodoc:
 
+    def and_yield(*yield_values)
+      @yield_queue << yield_values
+    end
+    alias :yields :and_yield
+
     
     # :call-seq:
     #   and_raise(an_exception)
@@ -169,13 +214,27 @@ class FlexMock
     #   additional arguments in the argument list will be passed to
     #   the +new+ constructor when it is invoked.
     #   
-    # +raises+ is an alias for +and_return+.
+    # +raises+ is an alias for +and_raise+.
     #
     def and_raise(exception, *args)
       and_return { raise exception, *args }
     end
     alias :raises :and_raise
 
+    # :call-seq:
+    #   and_throw(a_symbol)
+    #   and_throw(a_symbol, value)
+    #
+    # Declares that the method will throw the given symbol (with an
+    # optional value) when executed.
+    #
+    # +throws+ is an alias for +and_throw+.
+    #
+    def and_throw(sym, value=nil)
+      and_return { throw sym, value }
+    end
+    alias :throws :and_throw
+
     # Declare that the method may be called any number of times.
     def zero_or_more_times
       at_least.never
@@ -262,16 +321,37 @@ class FlexMock
     #    m.should_receive(:end).ordered
     #
     def ordered(group_name=nil)
-      if group_name.nil?
-        @order_number = @mock.mock_allocate_order
-      elsif (num = @mock.mock_groups[group_name])
-        @order_number = num
+      if @globally
+        @global_order_number = define_ordered(group_name, @mock.flexmock_container)
       else
-        @order_number = @mock.mock_allocate_order
-        @mock.mock_groups[group_name] = @order_number
+        @order_number = define_ordered(group_name, @mock)
       end
+      @globally = false
       self
     end
+
+    # Modifier that changes the next ordered constraint to apply
+    # globally across all mock objects in the container.
+    def globally
+      @globally = true
+      self
+    end
+
+    # Helper method for defining ordered expectations.
+    def define_ordered(group_name, ordering)
+      fail UsageError, "Mock #{@mock.flexmock_name} is not in a container and cannot be globally ordered." if ordering.nil?
+      if group_name.nil?
+         result = ordering.flexmock_allocate_order
+      elsif (num = ordering.flexmock_groups[group_name])
+        result = num
+      else
+        result = ordering.flexmock_allocate_order
+        ordering.flexmock_groups[group_name] = result
+      end
+      result
+    end
+    private :define_ordered
+
   end
 
   ##########################################################################