flexmock 0.7.1 → 0.8.0

data/doc/releases/flexmock-0.8.0.rdoc

@@ -0,0 +1,108 @@
+= FlexMock 0.7.1 Released
+
+FlexMock is a flexible mocking library for use in unit testing and
+behavior specification in Ruby.  It is a minor release that contains
+some new funtionality.
+
+== New Features n 0.8.0
+
+* When should_ignore_missing is specified, the mock will return an
+  undefined object for any method calls that are ignored.
+
+* A user can also specify an undefined object to be returned
+  explicitly by using FlexMock.undefined.
+
+* Expectations may now be marked with "by_default".  Default
+  expectations will be used unless a non-default expectation is given
+  for a matching method name.
+
+* The :respond_to? method on mocks will now accept multiple arguments.
+  This eases the testing of models in certains situations.
+
+* An experimental view mocker method is availble to mock out views in
+  Rails controller tests.  See flexmock/rails/view_mocking.rb for more
+  details.
+
+== 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.
+
+* Easy mocking of chains of method calls.
+
+* 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

@@ -20,4 +20,5 @@ require 'flexmock/validators'
 require 'flexmock/recorder'
 require 'flexmock/mock_container'
 require 'flexmock/partial_mock'
+require 'flexmock/undefined'
 require 'flexmock/deprecated_methods'

data/lib/flexmock/core.rb

@@ -9,6 +9,7 @@
 # above copyright notice is included.
 #+++
 
+require 'flexmock/errors'
 require 'flexmock/composite'
 require 'flexmock/ordering'
 
@@ -45,13 +46,6 @@ require 'flexmock/ordering'
 class FlexMock
   include Ordering
 
-  # Error raised when flexmock is used incorrectly.
-  class UsageError < RuntimeError
-  end
-
-  class MockError < RuntimeError
-  end
-
   attr_reader :flexmock_name
   attr_accessor :flexmock_container
 
@@ -94,38 +88,50 @@ class FlexMock
   end
   alias mock_ignore_missing should_ignore_missing
 
+  def by_default
+    @last_expectation.by_default
+    self
+  end
+
   # Handle missing methods by attempting to look up a handler.
   def method_missing(sym, *args, &block)
     flexmock_wrap do
       if handler = @expectations[sym]
         args << block  if block_given?
         handler.call(*args)
+      elsif @ignore_missing
+        FlexMock.undefined
       else
-        super(sym, *args, &block)  unless @ignore_missing
+        super(sym, *args, &block)
       end
     end
   end
 
   # Save the original definition of respond_to? for use a bit later.
-  alias mock_respond_to? respond_to?
+  alias flexmock_respond_to? respond_to?
 
   # Override the built-in respond_to? to include the mocked methods.
-  def respond_to?(sym)
+  def respond_to?(sym, *args)
     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]
+  def flexmock_find_expectation(method_name, *args) # :nodoc:
+    exp = @expectations[method_name]
     exp ? exp.find_expectation(*args) : nil
   end
 
+  # Return the expectation director for a method name.
+  def flexmock_expectations_for(method_name) # :nodoc:
+    @expectations[method_name]
+  end
+
   # Override the built-in +method+ to include the mocked methods.
   def method(sym)
     @expectations[sym] || super
   rescue NameError => ex
     if @ignore_missing
-      proc { }
+      proc { FlexMock.undefined }
     else
       raise ex
     end
@@ -151,13 +157,14 @@ class FlexMock
   # See Expectation for a list of declarators that can be used.
   #
   def should_receive(*args)
-    ContainerHelper.parse_should_args(self, args) do |sym|
+    @last_expectation = ContainerHelper.parse_should_args(self, args) do |sym|
       @expectations[sym] ||= ExpectationDirector.new(sym)
       result = Expectation.new(self, sym)
       @expectations[sym] << result
-      override_existing_method(sym) if mock_respond_to?(sym)
+      override_existing_method(sym) if flexmock_respond_to?(sym)
       result
     end
+    @last_expectation
   end
   
   # Declare that the mock object should expect methods by providing a

data/lib/flexmock/errors.rb

@@ -0,0 +1,23 @@
+#!/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
+
+  # Error raised when flexmock is used incorrectly.
+  class UsageError < ::RuntimeError
+  end
+
+  class MockError < ::RuntimeError
+  end
+
+end

data/lib/flexmock/expectation.rb

@@ -100,6 +100,11 @@ class FlexMock
       @count_validators.all? { |v| v.eligible?(@actual_count) }
     end
 
+    # Is this expectation constrained by any call counts?
+    def call_count_constrained?
+      ! @count_validators.empty?
+    end      
+
     # Validate that the order
     def validate_order
       if @order_number
@@ -192,6 +197,34 @@ class FlexMock
     end
     alias :returns :and_return  # :nodoc:
 
+    # Declare that the method returns and undefined object
+    # (FlexMock.undefined).  Since the undefined object will always
+    # return itself for any message sent to it, it is a good "I don't
+    # care" value to return for methods that are commonly used in
+    # method chains.
+    #
+    # For example, if m.foo returns the undefined object, then:
+    #
+    #    m.foo.bar.baz
+    #
+    # returns the undefined object without throwing an exception.
+    #
+    def and_return_undefined
+      and_return(FlexMock.undefined)
+    end
+    alias :returns_undefined :and_return_undefined
+
+    # :call-seq:
+    #   and_yield(value1, value2, ...)
+    #
+    # Declare that the mocked method is expected to be given a block
+    # and that the block will be called with the values supplied to
+    # yield.  If the mock is called multiple times, mulitple
+    # <tt>and_yield</tt> declarations can be used to supply different
+    # values on each call.
+    #
+    # An error is raised if the mocked method is not called with a
+    # block.
     def and_yield(*yield_values)
       @yield_queue << yield_values
     end
@@ -352,6 +385,11 @@ class FlexMock
     end
     private :define_ordered
 
+    def by_default
+      expectations = mock.flexmock_expectations_for(@sym)
+      expectations.defaultify_expectation(self) if expectations
+    end
+
   end
 
   ##########################################################################

data/lib/flexmock/expectation_director.rb

@@ -10,9 +10,9 @@
 #+++
 
 require 'flexmock/noop'
+require 'flexmock/errors'
 
 class FlexMock
-
   ####################################################################
   # The expectation director is responsible for routing calls to the
   # correct expectations for a given argument list.
@@ -23,6 +23,7 @@ class FlexMock
     def initialize(sym)
       @sym = sym
       @expectations = []
+      @defaults = []
       @expected_order = nil
     end
 
@@ -41,24 +42,43 @@ class FlexMock
       exp.verify_call(*args)
     end
 
-    # Find an expectation matching the given arguments.
-    def find_expectation(*args)
-      @expectations.find { |e| e.match_args(args) && e.eligible? } ||
-        @expectations.find { |e| e.match_args(args) }
-    end
-    
     # Append an expectation to this director.
     def <<(expectation)
       @expectations << expectation
     end
 
+    # Find an expectation matching the given arguments.
+    def find_expectation(*args) # :nodoc:
+      find_expectation_in(@expectations, *args) ||
+        find_expectation_in(@defaults, *args)
+    end
+
     # Do the post test verification for this directory.  Check all the
-    # expectations.
-    def flexmock_verify
-      @expectations.each do |exp|
+    # expectations.  Only check the default expecatations if there are
+    # no non-default expectations.
+    def flexmock_verify         # :nodoc:
+      (@expectations.empty? ? @defaults : @expectations).each do |exp|
         exp.flexmock_verify
       end
     end
+
+    # Move the last defined expectation a default.
+    def defaultify_expectation(exp) # :nodoc:
+      last_exp = @expectations.last
+      if last_exp != exp
+        fail UsageError,
+          "Cannot make a previously defined expection into a default"
+      end
+      @expectations.pop
+      @defaults << exp
+    end
+
+    private
+
+    def find_expectation_in(expectations, *args)
+      expectations.find { |e| e.match_args(args) && e.eligible? } ||
+        expectations.find { |e| e.match_args(args) }
+    end
   end
 
 end

data/lib/flexmock/mock_container.rb

@@ -175,7 +175,7 @@ class FlexMock
 
     # Return the next id for mocked models.
     def next_id
-      @id_counter ||= 0
+      @id_counter ||= 10000
       @id_counter += 1
     end
 

data/lib/flexmock/partial_mock.rb

@@ -44,7 +44,9 @@ class FlexMock
       @methods_proxied = []
       unless safe_mode
         MOCK_METHODS.each do |sym|
-          add_mock_method(@obj, sym)
+          unless @obj.respond_to?(sym)
+            add_mock_method(@obj, sym)
+          end
         end
       end
     end
@@ -163,6 +165,11 @@ class FlexMock
     def flexmock_container=(container)
     end
 
+    # Forward the request for the expectation director to the mock.
+    def flexmock_expectations_for(method_name)
+      @mock.flexmock_expectations_for(method_name)
+    end
+
     private
 
     # The singleton class of the object.

data/lib/flexmock/rails/view_mocking.rb

@@ -0,0 +1,30 @@
+require 'flexmock'
+
+class FlexMock
+  module MockContainer
+
+    # Declare that the Rails controller under test should render the
+    # named view.  If a view template name is given, it will be an
+    # error if the named view is not rendered during the execution of
+    # the contoller action.  If no template name is given, then the
+    # any view may be rendered. If no view is actually rendered, then
+    # a assertion failure will occur.
+    def should_render_view(template_name=nil)
+      view = flexmock("MockView")
+       view.should_receive(
+         :assigns => {},
+         :render_file => true,
+         :first_render => "dummy_template"
+        )
+      if template_name
+        view.should_receive(:file_exists?).with(/#{template_name}$/).once.
+          and_return(true)
+      end
+      view.should_receive(:file_exists?).with(any).and_return(true)
+      view_class = flexmock("MockViewClasss")
+      view_class.should_receive(:new).and_return(view)
+      flexmock(@controller.class).should_receive(:view_class).once.
+        and_return(view_class)
+    end
+  end
+end

data/lib/flexmock/rails.rb

@@ -0,0 +1,15 @@
+#!/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 the modules needed for rails oriented mocking.
+
+require 'flexmock'
+require 'flexmock/rails/view_mocking'

data/lib/flexmock/undefined.rb

@@ -0,0 +1,50 @@
+#!/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 FlexMock
+
+  # Undefined is a self preserving undefined object.  The result of
+  # any interaction with the undefined object will be the undefined
+  # object itself.
+  class Undefined
+    def method_missing(sym, *args, &block)
+      self
+    end
+
+    def to_s
+      "-UNDEFINED-"
+    end
+
+    def inspect
+      to_s
+    end
+
+    def clone
+      self
+    end
+    
+    def coerce(other)
+      [FlexMock.undefined, FlexMock.undefined]
+    end
+  end
+
+  # Single instance of undefined
+  @undefined = Undefined.new
+
+  # Undefined is normally available as FlexMock.undefined
+  def self.undefined
+    @undefined
+  end
+  
+  class << Undefined
+    private :new
+  end
+end 

data/test/test_aliasing.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+
+require 'test/unit'
+require 'flexmock'
+
+class FlexMock
+  module StubsAndExpects
+    def expects(*args)
+      result = should_receive(*args)
+      result.at_least.once unless result.call_count_constrained?
+      result
+    end
+    def stubs(*args)
+      should_receive(*args)
+    end
+  end
+
+  module MockContainer
+    alias :mock :flexmock
+    alias :stub :flexmock
+  end
+
+  include StubsAndExpects
+
+  class PartialMockProxy
+    include StubsAndExpects
+    MOCK_METHODS << :stubs << :expects
+  end
+end
+
+class AliasingTest < Test::Unit::TestCase
+  include FlexMock::TestCase
+
+  def test_mocking
+    m = mock("a cute dog").expects(:pat).twice.and_return(:woof!).mock
+    assert_equal :woof!, m.pat
+    assert_equal :woof!, m.pat
+  end
+  
+  def test_once_mocking
+    m = mock("a cute dog").expects(:pat).and_return(:woof!).mock
+  end
+  
+  def test_twice_mocking
+    m = mock("a cute dog").expects(:pat).and_return(:woof!).twice.mock
+    assert_raises(Test::Unit::AssertionFailedError) { m.flexmock_verify }
+  end
+  
+  def test_stubbing
+    m = stub("a cute dog").expects(:pat).and_return(:woof!).mock
+    assert_equal :woof!, m.pat
+  end
+  
+  def test_partial
+    obj = Object.new
+    stub(obj).stubs(:wag).and_return(:tail)
+    assert_equal :tail, obj.wag
+  end
+end
+

data/test/test_deprecated_methods.rb

@@ -184,7 +184,7 @@ class TestFlexMock < Test::Unit::TestCase
     @mock.mock_ignore_missing
     method_proc = @mock.method(:plugh)
     assert_not_nil method_proc
-    method_proc.call
+    assert_equal FlexMock.undefined, method_proc.call
   end
 end