flexmock 0.5.1 → 0.6.0

data/lib/flexmock/expectation.rb

@@ -0,0 +1,334 @@
+#!/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.
+#+++
+
+require 'flexmock/noop'
+
+class FlexMock
+  
+  ####################################################################
+  # An Expectation is returned from each +should_receive+ message sent
+  # to mock object.  Each expectation records how a message matching
+  # the message name (argument to +should_receive+) and the argument
+  # list (given by +with+) should behave.  Mock expectations can be
+  # recorded by chaining the declaration methods defined in this
+  # class.
+  #
+  # For example:
+  #
+  #   mock.should_receive(:meth).with(args).and_returns(result)
+  #
+  class Expectation
+
+    attr_reader :expected_args, :order_number
+    attr_accessor :mock
+
+    # Create an expectation for a method named +sym+.
+    def initialize(mock, sym)
+      @mock = mock
+      @sym = sym
+      @expected_args = nil
+      @count_validators = []
+      @count_validator_class = ExactCountValidator
+      @actual_count = 0
+      @return_value = nil
+      @return_block = lambda { @return_value }
+      @order_number = nil
+    end
+
+    def to_s
+      FlexMock.format_args(@sym, @expected_args)
+    end
+
+    # Verify the current call with the given arguments matches the
+    # expectations recorded in this object.
+    def verify_call(*args)
+      validate_order
+      @actual_count += 1
+      @return_block.call(*args)
+    end
+
+    # 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?
+      @count_validators.all? { |v| v.eligible?(@actual_count) }
+    end
+
+    # 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
+    end
+    private :validate_order
+
+    # Validate the correct number of calls have been made.  Called by
+    # the teardown process.
+    def mock_verify
+      @count_validators.each do |v|
+        v.validate(@actual_count)
+      end
+    end
+
+    # Does the argument list match this expectation's argument
+    # specification.
+    def match_args(args)
+      # TODO: Rethink this:
+      # return false if @expected_args.nil?
+      return true if @expected_args.nil?
+      return false if args.size != @expected_args.size
+      (0...args.size).all? { |i| match_arg(@expected_args[i], args[i]) }
+    end
+
+    # Does the expected argument match the corresponding actual value.
+    def match_arg(expected, actual)
+      expected === actual ||
+      expected == actual ||
+      ( Regexp === expected && expected === actual.to_s )
+    end
+
+    # Declare that the method should expect the given argument list.
+    def with(*args)
+      @expected_args = args
+      self
+    end
+
+    # Declare that the method should be called with no arguments.
+    def with_no_args
+      with
+    end
+
+    # Declare that the method can be called with any number of
+    # arguments of any type.
+    def with_any_args
+      @expected_args = nil
+      self
+    end
+
+    # :call-seq:
+    #   and_return(value)
+    #   and_return(value, value, ...)
+    #   and_return { |*args| code }
+    #
+    # Declare that the method returns a particular value (when the
+    # argument list is matched).
+    #
+    # * If a single value is given, it will be returned for all matching
+    #   calls.
+    # * If multiple values are given, each value will be returned in turn for
+    #   each successive call.  If the number of matching calls is greater
+    #   than the number of values, the last value will be returned for
+    #   the extra matching calls.
+    # * If a block is given, it is evaluated on each call and its
+    #   value is returned.
+    #
+    # For example:
+    #
+    #  mock.should_receive(:f).returns(12)   # returns 12
+    #
+    #  mock.should_receive(:f).with(String). # returns an
+    #    returns { |str| str.upcase }        # upcased string
+    #
+    # +and_return+ is an alias for +returns+.
+    #
+    def and_return(*args, &block)
+      @return_block = 
+        if block_given? 
+           block
+        else
+          lambda { args.size == 1 ? args.first : args.shift }
+        end
+      self
+    end
+    alias :returns :and_return  # :nodoc:
+
+    # Declare that the method may be called any number of times.
+    def zero_or_more_times
+      at_least.never
+    end
+
+    # Declare that the method is called +limit+ times with the
+    # declared argument list.  This may be modified by the +at_least+
+    # and +at_most+ declarators.
+    def times(limit)
+      @count_validators << @count_validator_class.new(self, limit) unless limit.nil?
+      @count_validator_class = ExactCountValidator
+      self
+    end
+
+    # Declare that the method is never expected to be called with the
+    # given argument list.  This may be modified by the +at_least+ and
+    # +at_most+ declarators.
+    def never
+      times(0)
+    end
+
+    # Declare that the method is expected to be called exactly once
+    # with the given argument list.  This may be modified by the
+    # +at_least+ and +at_most+ declarators.
+    def once
+      times(1)
+    end
+
+    # Declare that the method is expected to be called exactly twice
+    # with the given argument list.  This may be modified by the
+    # +at_least+ and +at_most+ declarators.
+    def twice
+      times(2)
+    end
+
+    # Modifies the next call count declarator (+times+, +never+,
+    # +once+ or +twice+) so that the declarator means the method is
+    # called at least that many times.
+    #
+    # E.g. method f must be called at least twice:
+    #
+    #   mock.should_receive(:f).at_least.twice
+    #
+    def at_least
+      @count_validator_class = AtLeastCountValidator
+      self
+    end
+
+    # Modifies the next call count declarator (+times+, +never+,
+    # +once+ or +twice+) so that the declarator means the method is
+    # called at most that many times.
+    #
+    # E.g. method f must be called no more than twice
+    #
+    #   mock.should_receive(:f).at_most.twice
+    #
+    def at_most
+      @count_validator_class = AtMostCountValidator
+      self
+    end
+
+    # Declare that the given method must be called in order.  All
+    # ordered method calls must be received in the order specified by
+    # the ordering of the +should_receive+ messages.  Receiving a
+    # methods out of the specified order will cause a test failure.
+    #
+    # If the user needs more fine control over ordering
+    # (e.g. specifying that a group of messages may be received in any
+    # order as long as they all come after another group of messages),
+    # a _group_ _name_ may be specified in the +ordered+ calls.  All
+    # messages within the same group may be received in any order.
+    #
+    # For example, in the following, messages +flip+ and +flop+ may be
+    # received in any order (because they are in the same group), but
+    # must occur strictly after +start+ but before +end+.  The message
+    # +any_time+ may be received at any time because it is not
+    # ordered.
+    #
+    #    m = FlexMock.new
+    #    m.should_receive(:any_time)
+    #    m.should_receive(:start).ordered
+    #    m.should_receive(:flip).ordered(:flip_flop_group)
+    #    m.should_receive(:flop).ordered(:flip_flop_group)
+    #    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
+      else
+        @order_number = @mock.mock_allocate_order
+        @mock.mock_groups[group_name] = @order_number
+      end
+      self
+    end
+  end
+
+  ##########################################################################
+  # A composite expectation allows several expectations to be grouped into a
+  # single composite and then apply the same constraints to  all expectations
+  # in the group.
+  class CompositeExpectation
+
+    # Initialize the composite expectation.
+    def initialize
+      @expectations = []
+    end
+
+    # Add an expectation to the composite.
+    def add(expectation)
+      @expectations << expectation
+    end
+
+    # Apply the constraint method to all expectations in the composite.
+    def method_missing(sym, *args, &block)
+      @expectations.each do |expectation|
+        expectation.send(sym, *args, &block)
+      end
+      self
+    end
+
+    # The following methods return a value, so we make an arbitrary choice
+    # and return the value for the first expectation in the composite.
+    
+    # Return the order number of the first expectation in the list.
+    def order_number
+      @expectations.first.order_number
+    end
+
+    # Return the associated mock object.
+    def mock
+      @expectations.first.mock
+    end
+    
+    # Start a new method expectation.  The following constraints will be
+    # applied to the new expectation.
+    def should_receive(*args, &block)
+      @expectations.first.mock.should_receive(*args, &block)
+    end
+
+    # Return a string representations
+    def to_s
+      if @expectations.size > 1
+        "[" + @expectations.collect { |e| e.to_s }.join(', ') + "]"
+      else
+        @expectations.first.to_s
+      end
+    end
+  end
+
+  ##########################################################################
+  # An expectation recorder records any expectations received and plays them
+  # back on demand.  This is used to collect the expectations in the blockless
+  # version of the new_instances call.
+  #
+  class ExpectationRecorder
+
+    # Initialize the recorder.
+    def initialize
+      @expectations = []
+    end
+
+    # Save any incoming messages to be played back later.
+    def method_missing(sym, *args, &block)
+      @expectations << [sym, args, block]
+      self
+    end
+    
+    # Apply the recorded messages to the given object in a chaining fashion
+    # (i.e. the result of the previous call is used as the target of the next
+    # call).
+    def apply(mock)
+      obj = mock
+      @expectations.each do |sym, args, block|
+        obj = obj.send(sym, *args, &block)
+      end
+    end
+  end
+end

data/lib/flexmock/expectation_director.rb

@@ -0,0 +1,59 @@
+#!/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.
+#+++
+
+require 'flexmock/noop'
+
+class FlexMock
+
+  ####################################################################
+  # The expectation director is responsible for routing calls to the
+  # correct expectations for a given argument list.
+  #
+  class ExpectationDirector
+
+    # Create an ExpectationDirector for a mock object.
+    def initialize(sym)
+      @sym = sym
+      @expectations = []
+      @expected_order = nil
+    end
+
+    # Invoke the expectations for a given set of arguments.
+    #
+    # First, look for an expectation that matches the arguements and
+    # is eligible to be called.  Failing that, look for a expectation
+    # that matches the arguments (at this point it will be ineligible,
+    # but at least we will get a good failure message).  Finally,
+    # check for expectations that don't have any argument matching
+    # criteria.
+    def call(*args)
+      exp = @expectations.find { |e| e.match_args(args) && e.eligible? } ||
+      @expectations.find { |e| e.match_args(args) }
+      FlexMock.check("no matching handler found for " +
+      FlexMock.format_args(@sym, args)) { ! exp.nil? }
+      exp.verify_call(*args)
+    end
+
+    # Append an expectation to this director.
+    def <<(expectation)
+      @expectations << expectation
+    end
+
+    # Do the post test verification for this directory.  Check all the
+    # expectations.
+    def mock_verify
+      @expectations.each do |exp|
+        exp.mock_verify
+      end
+    end
+  end
+
+end

data/lib/flexmock/mock_container.rb

@@ -0,0 +1,159 @@
+#!/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.
+#+++
+
+require 'flexmock/noop'
+
+class FlexMock
+  
+  ####################################################################
+  # Mock container methods
+  #
+  # Include this module in to get integration with FlexMock.  When 
+  # this module is included, mocks may be created with a simple call 
+  # to the +flexmock+ method.  Mocks created with via the method call
+  # will automatically be verified in the teardown of the test case.
+  # 
+  module MockContainer
+    # Do the flexmock specific teardown stuff.  If you need finer control,
+    # you can use either +flexmock_verify+ or +flexmock_close+.
+    def flexmock_teardown
+      flexmock_verify if passed?
+    ensure
+      flexmock_close
+    end
+
+    # Perform verification on all mocks in the container.
+    def flexmock_verify
+      @flexmock_created_mocks ||= []
+      @flexmock_created_mocks.each do |m|
+        m.mock_verify
+      end
+    end
+    
+    # Close all the mock objects in the container.  Closing a mock object
+    # restores any original behavior that was displaced by the mock.
+    def flexmock_close
+      @flexmock_created_mocks ||= []
+      @flexmock_created_mocks.each do |m|
+        m.mock_teardown
+      end
+      @flexmock_created_mocks = []
+    end
+    
+    # Create a mocking object in the FlexMock framework.  The +flexmock+ 
+    # method has a number of options available, depending on just what
+    # kind of mocking object your require.  Mocks created via +flexmock+
+    # will be automatically verify during the teardown phase of your 
+    # test framework.
+    #
+    # :call-seq:
+    #   flexmock() { |mock| ... }
+    #   flexmock(name) { |mock| ... }
+    #   flexmock(expect_hash) { |mock| ... }
+    #   flexmock(name, expect_hash) { |mock| ... }
+    #   flexmock(real_object) { |mock| ... }
+    #   flexmock(real_object, name) { |mock| ... }
+    #   flexmock(real_object, name, expect_hash) { |mock| ... }
+    #   flexmock(:base, string, name, expect_hash) { |mock| ... }
+    #
+    # name ::
+    #   Name of the mock object.  If no name is given, "unknown" is used for
+    #   full mocks and "flexmock(<em>real_object</em>)" is used for partial
+    #   mocks.
+    #
+    # expect_hash ::
+    #   Hash table of method names and values.  Each method/value pair is 
+    #   used to setup a simple expectation so that if the mock object
+    #   receives a message matching an entry in the table, it returns 
+    #   the associated value.  No argument our call count constraints are
+    #   added.  Using an expect_hash is identical to calling:
+    #
+    #       mock.should_receive(method_name).and_return(value)
+    #
+    #   for each of the method/value pairs in the hash.
+    #
+    # real_object ::
+    #   If a real object is given, then a partial mock is constructed 
+    #   using the real_object as a base. Partial mocks (formally referred 
+    #   to as stubs) behave as a mock object when an expectation is matched, 
+    #   and otherwise will behave like the original object.  This is useful 
+    #   when you want to use a real object for testing, but need to mock out 
+    #   just one or two methods.  
+    #
+    # :base ::
+    #   Forces the following argument to be used as the base of a
+    #   partial mock object.  This explicit tag is only needed if you 
+    #   want to use a string or a symbol as the mock base (string and
+    #   symbols would normally be interpretted as the mock name).
+    # 
+    # &block ::
+    #   If a block is given, then the mock object is passed to the block and
+    #   expectations may be configured within the block.
+    #
+    def flexmock(*args)
+      name = nil
+      quick_defs = {}
+      stub_target = nil
+      while ! args.empty?
+        case args.first
+        when :base
+          args.shift
+          stub_target = args.shift
+        when String, Symbol
+          name = args.shift.to_s
+        when Hash
+          quick_defs = args.shift
+        else
+          stub_target = args.shift
+        end
+      end
+      if stub_target
+        mock = flexmock_make_stub(stub_target, name)
+      else
+        mock = FlexMock.new(name || "unknown")
+      end
+      flexmock_quick_define(mock, quick_defs)
+      yield(mock) if block_given?
+      flexmock_remember(mock)
+      mock
+    end
+    alias flexstub flexmock
+    
+    private
+    
+    # Create a PartialMock for the given object.  Use +name+ as the name 
+    # of the mock object.
+    def flexmock_make_stub(obj, name)
+      name ||= "flexmock(#{obj.class.to_s})"
+      obj.instance_eval {
+        @flexmock_proxy ||= PartialMock.new(obj, FlexMock.new(name))
+      }
+      obj.instance_variable_get("@flexmock_proxy")
+    end
+
+    # Create a set of mocked methods from a hash.
+    def flexmock_quick_define(mock, defs)
+      defs.each do |method, value|
+        mock.should_receive(method).and_return(value)
+      end
+      mock
+    end
+    
+    # Remember the mock object / stub in the mock container.
+    def flexmock_remember(mocking_object)
+      @flexmock_created_mocks ||= []
+      @flexmock_created_mocks << mocking_object
+      mocking_object.mock_container = self
+      mocking_object
+    end
+  end
+
+end