flexmock 0.4.5 → 0.5.0

data/CHANGELOG

@@ -2,6 +2,10 @@
 
 = Changes for FlexMock
 
+== Version 0.5.0
+
+* Added any_instance stubbing to class objects.
+
 == Version 0.4.5
 
 * Fixed version typo in 0.4.4 (internall claimed to be 0.4.3.1)

data/README

@@ -3,7 +3,7 @@
 FlexMock is a simple, but flexible, mock object library for Ruby unit
 testing.
 
-Version :: 0.4.5
+Version :: 0.5.0
 
 = Links
 
@@ -283,6 +283,37 @@ everything is back to normal.
 The stub technique was inspired by the +Stuba+ library in the +Mocha+
 project.
 
+=== Stubbing Behavior in All Instances Created by a Class Object
+
+Sometimes you want to stub all instances created by a class object.
+For example, you might wish to work with Connection objects that have
+their "send" method stubbed out.  However, the code under test creates
+connections dynamically, so you can't stub them before the test is
+run.
+
+One approach is to stub the "new" method on the class object.  The
+stubbed implementation of "new" would create a mock object to be
+returned as the value of "new".  But since your stubbed implementation
+of "new" has no access to the original behavior of new, you can't
+really create stubs.
+
+The <tt>any_instance</tt> method allows you to easily add stub
+expectations to objects created by new.  Here's the Connection example
+using <tt>any_instance</tt>:
+
+      def test_connections
+        flexstub(Connection).any_instance do |new_con|
+          new_con.should_receive(:send).and_return(0)
+        end
+        connection = Connection.new
+        connection.send    # This calls the stubbed version of send.
+      end
+
+Note that FlexMock adds the stub expectations after the original +new+
+method has completed.  If the original version of +new+ yields the
+newly created instance to a block, that block will get an unstubbed
+version of the object.
+
 === Class Interception
 
 <b>NOTE:</b> :: 
@@ -450,7 +481,7 @@ following:
 
 ruby-mock      :: http://www.b13media.com/dev/ruby/mock.html
 test-unit-mock :: http://www.deveiate.org/code/Test-Unit-Mock.shtml
-
+mocha/stubba   :: http://mocha.rubyforge.org/
 == License
 
 Copyright 2003, 2004, 2005, 2006 by Jim Weirich (jim@weirichhouse.org).

data/Rakefile

@@ -9,7 +9,7 @@ require 'rake/testtask'
 CLEAN.include('*.tmp')
 CLOBBER.include("html", 'pkg')
 
-PKG_VERSION = '0.4.5'
+PKG_VERSION = '0.5.0'
 
 PKG_FILES = FileList[
   '[A-Z]*',
@@ -41,18 +41,19 @@ end
 
 # RDoc Target --------------------------------------------------------
 
-rd = Rake::RDocTask.new("rdoc") do |rdoc|
+task :rdoc => ["README"]
+
+$rd = Rake::RDocTask.new("rdoc") do |rdoc|
   rdoc.rdoc_dir = 'html'
   rdoc.template = 'doc/jamis.rb'
-#  rdoc.template = 'html'
-#  rdoc.template = 'kilmer'
-#  rdoc.template = 'css2'
+  #  rdoc.template = 'html'
+  #  rdoc.template = 'kilmer'
+  #  rdoc.template = 'css2'
   rdoc.title    = "Flex Mock"
   rdoc.options << '--line-numbers' << '--inline-source' << '--main' << 'README'
   rdoc.rdoc_files.include(RDOC_FILES)
 end
 
-task :rdoc => ["README"]
 file "README" => ["Rakefile"] do
   ruby %{-i.bak -pe 'sub!(/^Version *:: *(\\d+\\.)+\\d+ *$/, "Version :: #{PKG_VERSION}")' README} # "
 end
@@ -95,7 +96,7 @@ else
     #### Documentation and testing.
 
     s.has_rdoc = true
-    s.extra_rdoc_files = rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
+    s.extra_rdoc_files = $rd.rdoc_files.reject { |fn| fn =~ /\.rb$/ }.to_a
     s.rdoc_options <<
       '--title' <<  'Flex Mock' <<
       '--main' << 'README' <<

data/doc/releases/flexmock-0.5.0.rdoc

@@ -0,0 +1,103 @@
+= FlexMock 0.5.0 Released
+
+FlexMock is a flexible mocking library for use in Ruby's Test::Unit
+test framework.  Version 0.5.0 adds the ability to automatically stub any
+instance created by an existing class.
+
+== New in 0.5.0
+
+* flexstub(obj) will now accept a block argument in the same way that 
+  flexmock() does.
+  
+* When stubbing Class objects, the any_instance method can be used to 
+  automatically stub any instance object created by the class.  For 
+  example, if you wish that any Connection object created during a test
+  has a stubbed "send" method, you could do the following:
+  
+      def test_connections
+        flexstub(Connection).any_instance do |new_con|
+          new_con.should_receive(:send).and_return(0)
+        end
+        connection = Connection.new
+        connection.send    # This calls the stubbed version of send.
+      end
+
+  Only objects created during the test will be automatically stubbed.  
+  Existing objects are unaffected.
+
+== What is FlexMock?
+
+FlexMock is a flexible Ruby mocking library that works with Ruby's
+Test::Unit framework to create easy to use mocks.
+
+=== Features
+
+* Easy integration with Test::Unit.  Mocks created with the flexmock
+  method are automatically verified at the end of the test.
+
+* 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.
+
+=== 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'
+
+  class TestDog < Test::Unit::TestCase
+    include FlexMock::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://onestepback.org/software/flexmock 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://onestepback.org/software/flexmock/
+
+-- Jim Weirich
+

data/lib/flexmock.rb

@@ -26,9 +26,9 @@ require 'test/unit'
 #
 #   m = FlexMock.new("name")
 #   m.should_receive(:upcase).with("stuff").
-#     returns("STUFF")
+#     and_return("STUFF")
 #   m.should_receive(:downcase).with(String).
-#     returns { |s| s.downcase }.once
+#     and_return { |s| s.downcase }.once
 #
 # With Test::Unit Integration:
 #
@@ -52,7 +52,7 @@ class FlexMock
   class BadInterceptionError < RuntimeError; end
 
   attr_reader :mock_name, :mock_groups
-  attr_accessor :mock_current_order
+  attr_accessor :mock_current_order, :mock_container
 
   # Create a FlexMock object with the given name.  The name is used in
   # error messages.
@@ -61,6 +61,7 @@ class FlexMock
     @expectations = Hash.new
     @allocated_order = 0
     @mock_current_order = 0
+    @mock_container = nil
     @mock_groups = {}
     @ignore_missing = false
     @verified = false
@@ -843,6 +844,7 @@ class FlexMock
     def flexmock_remember(mocking_object)
       @flexmock_created_mocks ||= []
       @flexmock_created_mocks << mocking_object
+      mocking_object.mock_container = self
       mocking_object
     end
   end
@@ -977,6 +979,7 @@ class FlexMock
   class StubProxy
     attr_reader :mock
     
+    # Initialize a StubProxy object.
     def initialize(obj, mock)
       @obj = obj
       @mock = mock
@@ -995,6 +998,32 @@ class FlexMock
       @mock.should_receive(method_name)
     end
     
+    # any_instance is a short cut method for overriding the behavior of any 
+    # instance created via a stubbed class object.
+    def any_instance(&block)
+      fail ArgumentError, "any_instance requires a Class to stub" unless Class === @obj
+      self.should_receive(:new).and_return { |*args|
+        new_obj = invoke_original(:new, args)
+        mock = mock_container.flexstub(new_obj)
+        block.call(mock)
+        new_obj
+      }
+      nil
+    end
+
+    # Invoke the original definition of method on the object supported by 
+    # the stub.
+    def invoke_original(method, args)
+      method_proc = @method_definitions[:new]
+      block = nil
+      if Proc === args.last
+        block = args.last
+        args = args[0...-1]
+      end
+      method_proc.call(*args, &block)
+    end
+    private :invoke_original
+
     # Verify that the mock has been properly called.  After verification, 
     # detach the mocking infrastructure from the existing object.
     def mock_verify
@@ -1012,6 +1041,18 @@ class FlexMock
         @obj = nil
       end
     end
+    
+    # Return the container for this mocking object.  Returns nil if the   
+    # mock is not in a container.  Mock containers make sure that mock objects
+    # inside the container are torn down at the end of a test
+    def mock_container
+      @mock.mock_container
+    end
+    
+    # Set the container for this mock object.
+    def mock_container=(container)
+      @mock.mock_container = container
+    end
 
     private
 
@@ -1033,10 +1074,8 @@ class FlexMock
     # not a singleton, all we need to do is override it with our own
     # singleton.
     def hide_existing_method(method_name)
-      if singleton?(method_name)
-        @method_definitions[method_name] = @obj.method(method_name)
-        remove_current_method(method_name)
-      end
+      @method_definitions[method_name] = @obj.method(method_name) if @obj.respond_to?(method_name)
+      remove_current_method(method_name) if singleton?(method_name)
       define_proxy_method(method_name)
     end
 

data/test/test_any_instance.rb

@@ -0,0 +1,111 @@
+#!/usr/bin/env ruby
+
+#---
+# Copyright 2006 by Jim Weirich (jweirich@one.net).
+# 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 'test/unit'
+require 'flexmock'
+
+class TestStubbingOnNew < Test::Unit::TestCase
+  include FlexMock::TestCase
+  
+  class Dog
+    def bark
+      :woof
+    end
+    def wag
+      :tail
+    end
+  end
+
+  class Cat
+    attr_reader :name
+    def initialize(name, &block)
+      @name = name
+      block.call(self) if block_given?
+    end
+  end
+  
+  class Connection
+    def initialize(*args)
+      yield(self) if block_given?
+    end
+    def send(args)
+      post(args)
+    end
+    def post(args)
+      :unstubbed
+    end
+  end
+
+  def test_any_instance_allows_stubbing_of_existing_methods
+    flexstub(Dog).any_instance do |obj|
+      obj.should_receive(:bark).and_return(:whimper)
+    end
+    m = Dog.new
+    assert_equal :whimper,  m.bark
+  end
+  
+  def test_any_instance_stubs_still_have_existing_methods
+    flexstub(Dog).any_instance do |obj|
+      obj.should_receive(:bark).and_return(:whimper)
+    end
+    m = Dog.new
+    assert_equal :tail,  m.wag
+  end
+
+  def test_any_instance_will_pass_args_to_new
+    flexstub(Cat).any_instance do |obj|
+      obj.should_receive(:meow).and_return(:scratch)
+    end
+    x = :not_called
+    m = Cat.new("Fido") { x = :called }
+    assert_equal :scratch,  m.meow
+    assert_equal "Fido", m.name
+    assert_equal :called, x
+  end
+
+  def test_any_instance_stub_verification_happens_on_teardown
+    flexstub(Dog).any_instance do |obj|
+      obj.should_receive(:bark).once.and_return(nil)
+    end
+    
+    fido = Dog.new    
+    ex = assert_raise(Test::Unit::AssertionFailedError) { flexmock_teardown }
+    assert_match(/method 'bark\(.*\)' called incorrect number of times/, ex.message)
+  end
+
+  def test_any_instance_reports_error_on_non_classes
+    ex = assert_raise(ArgumentError) { 
+      flexstub(Dog.new).any_instance do |obj|
+        obj.should_receive(:hi)
+      end
+    }
+    assert_match(/Class/, ex.message)
+    assert_match(/any_instance/, ex.message)
+  end
+  
+  # Current behavior does not install stubs into the block passed to new. 
+  # This is rather difficult to achieve, although it would be nice.  For the
+  # moment, we assure that they are not stubbed, but I am willing to change 
+  # this in the future.
+  def test_blocks_on_new_do_not_have_stubs_installed
+    flexstub(Connection).any_instance do |new_con|
+      new_con.should_receive(:post).and_return {
+        :stubbed
+      }
+    end
+    block_run = false
+    Connection.new do |c|
+      assert_equal :unstubbed, c.send("hi")
+      block_run = true
+    end
+    assert block_run
+  end
+end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0.10
+rubygems_version: 0.9.2
 specification_version: 1
 name: flexmock
 version: !ruby/object:Gem::Version 
-  version: 0.4.5
-date: 2007-01-26 00:00:00 -05:00
+  version: 0.5.0
+date: 2007-02-10 00:00:00 -05:00
 summary: Simple and Flexible Mock Objects for Testing
 require_paths: 
 - lib
@@ -33,6 +33,7 @@ files:
 - Rakefile
 - README
 - lib/flexmock.rb
+- test/test_any_instance.rb
 - test/test_class_interception.rb
 - test/test_example.rb
 - test/test_mock.rb
@@ -48,6 +49,7 @@ files:
 - doc/releases/flexmock-0.4.1.rdoc
 - doc/releases/flexmock-0.4.2.rdoc
 - doc/releases/flexmock-0.4.3.rdoc
+- doc/releases/flexmock-0.5.0.rdoc
 test_files: []
 
 rdoc_options: 
@@ -63,6 +65,7 @@ extra_rdoc_files:
 - doc/releases/flexmock-0.4.1.rdoc
 - doc/releases/flexmock-0.4.2.rdoc
 - doc/releases/flexmock-0.4.3.rdoc
+- doc/releases/flexmock-0.5.0.rdoc
 executables: []
 
 extensions: []