flexmock 0.5.1 → 0.6.0

data/CHANGELOG

@@ -2,7 +2,16 @@
 
 = Changes for FlexMock
 
-== Pre Version 0.5.1
+== Version 0.6.0
+
+* Dropped class interception.
+* Refactored into more granular classes.
+* Added RSpec integration.
+* Added hash expectations to flexmock() and should_expect().
+* Integrated partial mocks into the flexmock() methods.
+* Allow non-block configuration of new_instances.
+
+== Version 0.5.1
 
 * Changed the name of any_instance to new_instances.  
   Deprecated any_instance.

data/README

@@ -3,13 +3,13 @@
 FlexMock is a simple, but flexible, mock object library for Ruby unit
 testing.
 
-Version :: 0.5.1
+Version :: 0.6.0
 
 = Links
 
-<b>Documents</b>   :: http://onestepback.org/software/flexmock
+<b>Documents</b>   :: http://flexmock.rubyforge.org
 <b>RubyGems</b>    :: Install with: <b>gem install flexmock</b>
-<b>Download</b>    :: Download from RubyForge at http://rubyforge.org/frs/?group_id=170
+<b>Download</b>    :: Download from RubyForge at http://rubyforge.org/frs/?group_id=3433 (pre 0.6.0 versions may be found at http://rubyforge.org/frs/?group_id=170)
 
 == Installation
 
@@ -27,7 +27,7 @@ mock object that responds to the +read_temperature+ message.
 Here's the complete example:
 
   require 'test/unit'
-  require 'flexmock'
+  require 'flexmock/test_unit'
 
   class TemperatureSampler
     def initialize(sensor)
@@ -35,149 +35,299 @@ Here's the complete example:
     end
 
     def average_temp
-      total = (0...3).collect { @sensor.read_temperature }.inject { |i, s| i + s }
+      total = (0...3).collect { 
+        @sensor.read_temperature 
+      }.inject { |i, s| i + s }
       total / 3.0
     end
   end
 
   class TestTemperatureSampler < Test::Unit::TestCase
-    include FlexMock::TestCase
-
-    def test_temperature_sampler
+    def test_sensor_can_average_three_temperature_readings
       sensor = flexmock("temp")
-      sensor.should_receive(:read_temperature).times(3).and_return(10, 12, 14)
+      sensor.should_receive(:read_temperature).times(3).
+        and_return(10, 12, 14)
 
       sampler = TemperatureSampler.new(sensor)
       assert_equal 12, sampler.average_temp
+    end
+  end
+
+You can find an extended example of FlexMock in {Google Example}[http://flexmock.rubyforge.org/files/doc/GoogleExample_rdoc.html].
+
+== Test::Unit Integration
+
+FlexMock integrates nicely with Test::Unit. Just require the
+'flexmock/test_unit' file at the top of your test file. The +flexmock+ method
+will be available for mock creation, and any created mocks will be
+automatically validated and closed at the end of the individual test.
+
+Your test case will look something like this:
 
-      # NOTE:
-      # all mocks created by the flexmock method will be
-      # automatically verified during the test teardown.
+  require 'flexmock/test_unit'
+
+  class TestDog < Test::Case::TestCase
+    def test_dog_wags
+      tail_mock = flexmock(:wag => :happy)
+      assert_equal :happy, tail_mock.wag
     end
   end
 
+<b>NOTE:</b> If you don't want to automatically extend every TestCase with the
+flexmock methods and overhead, then require the 'flexmock' file and explicitly
+include the FlexMock::TestCase module in each test case class where you wish
+to use mock objects. FlexMock versions prior to 0.6.0 required the explicit
+include.
+
+== RSpec Integration
+
+FlexMock also supports integration with the RSpec behavior specification framework.  Starting with version 0.9.0 of RSpec, you will be able to say:
+
+  Spec::Runner.configure do |config|
+    config.mock_with :flexmock
+  end
+
+  context "Using FlexMock with RSpec" do
+    specify "should be able to create a mock" do
+      m = flexmock(:foo => :bar)
+      m.foo.should === :bar
+    end
+  end
+
+If you wish to try this prior to the release of RSpec 0.9.0, check out the trunk of the RSpec subversion repository.
+
 == Quick Reference
 
+=== Creating Mock Objects 
+
+The +flexmock+ method is used to create mocks in various configurations.  Here's a quick rundown of the most common options.  See FlexMock::MockContainer#flexmock for more details.
+
+* <b>m = flexmock("joe")</b>
+
+  Create a mock object named "joe" (the name is used in reporting errors).  
+
+* <b>m = flexmock(:foo => :bar, :baz => :froz)</b>
+
+  Create a mock object and define two mocked methods (:foo and :baz) that
+  return the values :bar and :froz respectively. This is useful when creating
+  mock objects with just a few methods and simple return values.
+
+* <b>m = flexmock("joe", :foo => :bar, :bar => :froz)</b>
+
+  You can combine the mock name and an expectation hash in the same call to
+  flexmock.
+
+* <b>m = flexmock(real_object)</b>
+
+  If you you give +flexmock+ a real object in the argument list, it will treat
+  that real object as a base for a partial mock object. The return value +m+
+  may be used to set expectations. The real_object should be used in the
+  reference portion of the test.
+  
+* <b>m = flexmock(real_object, "name", :foo => :baz)</b>
+
+  Names and expectation hashes may be used with partial mocks as well.
+
+* <b>m = flexmock(:base, real_string_object)</b>
+
+  Since Strings (and Symbols for that matter) are used for mock names,
+  FlexMock will not recognize them as the base for a partial mock. To force a
+  string to be used as a partial mock base, proceed the string object in the
+  calling sequence with :base.
+
+* <b>m = flexmock(...) { |mock| mock.should_receive(...) }</b>
+
+  If a block is given to any of the +flexmock+ forms, the mock object will be
+  passed to the block as an argument. Code in the block can set the desired
+  expectations for the mock object.
+
+<b>NOTE:</b>  Versions of FlexMock prior to 0.6.0 used +flexstub+ to create partial mocks.  The +flexmock+ method now assumes all the functionality that was spread out between two different methods.  +flexstub+ is still available for backward compatibility.
+
 === Expectation Declarators
 
-Expectation declarators are used to specify the expectations placed
-upon received method calls.  The following declarators may be used to
-create the proper expectations on a FlexMock object.
-
-* <b><tt>should_receive(<em>symbol</em>)</tt></b> -- Declares that a
-  message named <em>symbol</em> will be sent to the mock object.
-  Further refinements on this expected message (called an expectation)
-  may be chained to the +should_receive+ call.
-
-* <b><tt>should_expect</tt></b> -- Creates a mock recording object
-  that will translate received method calls into mock expectations.
-  The recorder is passed to a block supplied with the +should_expect+
-  method.  See examples below.
-
-* <b><tt>with(<em>arglist</em>)</tt></b> -- Declares that this
-  expectation matches messages that match the given argument list.
-  The <tt>===</tt> operator is used on a argument by argument basis to
-  determine matching.  This means that most literal values match
-  literally, class values match any instance of a class and regular
-  expression match any matching string (after a +to_s+ conversion).
-  See argument validators (below) for details on argument validation
-  options.
-
-* <b><tt>with_any_args</tt></b> -- Declares that this expectation
-  matches the message with any argument (default)
-
-* <b><tt>with_no_args</tt></b> -- Declares that this expectation
-  matches messages with no arguments
-
-* <b><tt>and_return(<em>value, ...</em>)</tt></b> -- Declares 
-  that the message will return the given value.
-  * If a single value is given, it will be returned for all matching calls.
-  * If multiple values are given, they will be returned in sequence
-    for each successive matching calls.  The last value will be 
-    repeatably returned if the number of matching calls exceeds the
-    number of values.
-  * If a block is given, its yielded value will be returned. (the 
-    block will receive all the arguments given to the mocked method)
-  * The default return value is nil. 
-
-* <b><tt>returns(<em>value, ...</em>)</tt></b> -- Alias for
-  <tt>and_return</tt>.
-
-* <b><tt>returns { |args| code ... }</tt></b> -- Declares that the
-  message will return whatever the block calculates.  The actual
-  arguments in the message will be passed to the block.
-
-* <b><tt>zero_or_more_times</tt></b> -- Declares that the message is
-  may be sent zero or more times (default, equivalent to
-  <tt>at_least.never</tt>).
-
-* <b><tt>once</tt></b> -- Declares that the message is only sent once.
-  <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
+Once a mock is created, you need to define what that mock should expect to
+see. Expectation declarators are used to specify these expectations placed
+upon received method calls. A basic expectation, created with the
++should_receive+ method, just establishes the fact that a method may (or may
+not) be called on the mock object. Refinements to that expectation may be
+additionally declared. FlexMock always starts with the most general
+expectation and adds constraints to that.
 
-* <b><tt>twice</tt></b> -- Declares that the message is only sent
-  twice.  <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
+For example, the following code:
 
-* <b><tt>never</tt></b> -- Declares that the message is never sent.
-  <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
+    mock.should_recieve(:average).and_return(12)
+
+Means that the mock will now accept method calls to an +average+ method. The
+expectation will accept any arguments and may be called any number of times
+(including zero times). Strictly speaking, the +and_return+ part of the
+declaration isn't exactly a constraint, but it does specify what value the
+mock will return when the expectation is matched.
+
+If you want to be more specific, you need to add additional constraints to
+your expectation. Here are some examples:
+
+    mock.should_receive(:average).with(12).once
+
+    mock.should_receive(:average).with(Integer).
+        at_least.twice.at_most.times(10).
+        and_return { rand }
+
+The following methods may be used to create and refine expectations on a mock
+object. See theFlexMock::Expectation for more details.
+
+* <b>should_receive(<em>method_name</em>)</b>
+
+  Declares that a message named <em>method_name</em> will be sent to the mock
+  object. Constraints on this expected message (called expectations) may be
+  chained to the +should_receive+ call.
+
+* <b>should_receive(<em>method_name1</em>, <em>method_name2</em>, ...)</b>
+
+  Define a number of expected messages that have the same constraints.
+
+* <b>should_receive(<em>meth1</em> => <em>result1</em>, <em>meth2</em> => <em>result2</em>, ...)</b>
+
+  Define a number of expected messages that have the same constrants, but
+  return different values.
+
+* <b>should_expect { |recorder| ... }</b>
+
+  Creates a mock recording object that will translate received method calls
+  into mock expectations. The recorder is passed to a block supplied with the
+  +should_expect+ method. See examples below.
+
+* <b>with(<em>arglist</em>)</b>
+
+  Declares that this expectation matches messages that match the given
+  argument list. The <tt>===</tt> operator is used on a argument by argument
+  basis to determine matching. This means that most literal values match
+  literally, class values match any instance of a class and regular expression
+  match any matching string (after a +to_s+ conversion). See argument
+  validators (below) for details on argument validation options.
+
+* <b>with_any_args</b>
+
+  Declares that this expectation matches the message with any argument
+  (default)
+
+* <b>with_no_args</b>
+
+  Declares that this expectation matches messages with no arguments
+
+* <b>and_return(<em>value</em>)</b>
+
+  Declares that the expected message will return the given value.
 
-* <b><tt>times(<em>n</em>)</tt></b> -- Declares that the message is
-  sent <em>n</em> times.  <tt>at_least</tt> / <tt>at_most</tt>
-  modifiers are allowed.
+* <b>and_return(<em>value1</em>, <em>value2</em>, ...)</b>
 
-* <b><tt>at_least</tt></b> -- Modifies the immediately following
-  message count declarator so that it means the message is sent at
-  least that number of times.  E.g. <tt>at_least.once</tt> means the
-  message is sent at least once during the test, but may be sent more
-  often.  Both <tt>at_least</tt> and <tt>at_most</tt> may be specified
-  on the same expectation.
+  Declares that the expected message will return a series of values. Each
+  invocation of the message will return the next value in the series. The last
+  value will be repeatably returned if the number of matching calls exceeds
+  the number of values.
 
-* <b><tt>at_most</tt></b> -- Similar to <tt>at_least</tt>, but puts an
-  upper limit on the number of messages.  Both <tt>at_least</tt> and
+* <b>and_return { |args, ...|  code ... } </b>
+
+  Declares that the expected message will return the yielded value of the
+  block. The block will receive all the arguments in the message. If the
+  message was provided a block, it will be passed as the last parameter of the
+  block's argument list.
+
+* <b>returns( ... )</b>
+
+  Alias for <tt>and_return</tt>.
+
+* <b>zero_or_more_times</b>
+
+  Declares that the expected message is may be sent zero or more times
+  (default, equivalent to <tt>at_least.never</tt>).
+
+* <b>once</b>
+
+  Declares that the expected message is only sent once. <tt>at_least</tt> /
+  <tt>at_most</tt> modifiers are allowed.
+
+* <b>twice</b>
+
+  Declares that the expected message is only sent twice. <tt>at_least</tt> /
+  <tt>at_most</tt> modifiers are allowed.
+
+* <b>never</b>
+
+  Declares that the expected message is never sent. <tt>at_least</tt> /
+  <tt>at_most</tt> modifiers are allowed.
+
+* <b>times(<em>n</em>)</b>
+
+  Declares that the expected message is sent <em>n</em> times.
+  <tt>at_least</tt> / <tt>at_most</tt> modifiers are allowed.
+
+* <b>at_least</b>
+
+  Modifies the immediately following message count constraint so that it means
+  the message is sent at least that number of times. E.g.
+  <tt>at_least.once</tt> means the message is sent at least once during the
+  test, but may be sent more often. Both <tt>at_least</tt> and
   <tt>at_most</tt> may be specified on the same expectation.
 
-* <b><tt>ordered</tt></b> -- Declares that the message is ordered and
-  is expected to be received in a certain position in a sequence of
-  messages.  The message should arrive after and previously declared
-  ordered messages and prior to any following declared ordered
-  messages.  Unordered messages are ignored when considering the
-  message order.
-
-* <b><tt>ordered(<em>group</em>)</tt></b> -- Declare that the given
-  method belongs to an order group.  Methods within the group may be
-  received in any order.  Ordered messages outside the group must be
-  received either before or after the grouped messages.
-
-  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
-    
+* <b>at_most</b>
+
+  Similar to <tt>at_least</tt>, but puts an upper limit on the number of
+  messages. Both <tt>at_least</tt> and <tt>at_most</tt> may be specified on
+  the same expectation.
+
+* <b>ordered</b>
+
+  Declares that the expected message is ordered and is expected to be received
+  in a certain position in a sequence of messages. The message should arrive
+  after and previously declared ordered messages and prior to any following
+  declared ordered messages. Unordered messages are ignored when considering
+  the message order.
+
+* <b>ordered(<em>group</em>)</b>
+
+  Declare that the expected message belongs to an order group. Methods within
+  an order group may be received in any order. Ordered messages outside the
+  group must be received either before or after all of the grouped messages.
+
+  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()
+    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
+
+* <b>mock</b>
+
+  Expectation constraints always return the expectation so that the
+  constraints can be chained. If you wish to do a one-liner and assign the
+  mock to a variable, the +mock+ method on an expectation will return the
+  original mock object.
+  
+    m = flexmock.should_receive(:hello).once.and_return("World").mock
+
 === Argument Validation
 
-The values passed to the +with+ declarator determine the criteria for
-matching expectations.  The first expectation found that matches the
-arguments in a mock method call will be used to validate that mock
-method call.
+The values passed to the +with+ declarator determine the criteria for matching
+expectations. The first expectation found that matches the arguments in a mock
+method call will be used to validate that mock method call.
 
 The following rules are used for argument matching:
 
-* A +with+ parameter that is a class object will match any actual
-  argument that is an instance of that class.
+* A +with+ parameter that is a class object will match any actual argument
+  that is an instance of that class.
 
   Examples:
 
      with(Integer)     will match    f(3)
 
-* A regular expression will match any actual argument that matches the
-  regular expression.  Non-string actual arguments are converted to
-  strings via +to_s+ before applying the regular expression.
+* A regular expression will match any actual argument that matches the regular
+  expression. Non-string actual arguments are converted to strings via +to_s+
+  before applying the regular expression.
 
   Examples:
 
@@ -190,12 +340,11 @@ The following rules are used for argument matching:
 
       with(3)         will match    f(3)
       with("hello")   will match    f("hello")
-  
-* If you wish to override the default matching behavior and force
-  matching by equality, you can use the FlexMock.eq convenience
-  method.  This is mostly used when you wish to match class objects,
-  since the default matching behavior for class objects is to match
-  instances, not themselves.
+
+* If you wish to override the default matching behavior and force matching by
+  equality, you can use the FlexMock.eq convenience method. This is mostly
+  used when you wish to match class objects, since the default matching
+  behavior for class objects is to match instances, not themselves.
 
   Examples:
 
@@ -212,8 +361,8 @@ The following rules are used for argument matching:
 * If you wish to match _anything_, then use the <tt>FlexMock.any</tt>
   method in the with argument list.
 
-  Examples (assumes either the FlexMock::TestCase or
-  FlexMock::ArgumentTypes mix-ins has been included):
+  Examples (assumes either the FlexMock::TestCase or FlexMock::ArgumentTypes
+  mix-ins has been included):
 
       with(any)             will match       f(3)
       with(any)             will match       f("hello")
@@ -229,15 +378,17 @@ The following rules are used for argument matching:
 
   will match any even integer.
 
-=== Stubbing Behavior in Existing Objects
+=== Creating Partial Mocks
 
 Sometimes it is useful to mock the behavior of one or two methods in an
-existing object without changing the behavior of the rest of the object. By
-using the +flexstub+ method, tests can now do exactly that.
+existing object without changing the behavior of the rest of the object. If
+you pass a real object to the +flexmock+ method, it will allow you to use that
+real object in your test and will just mock out the one or two methods that
+you specify.
 
-For example, suppose that a Dog object uses a Woofer object to
-bark. The code for Dog looks like this (we will leave the code for
-Woofer to your imagination):
+For example, suppose that a Dog object uses a Woofer object to bark. The code
+for Dog looks like this (we will leave the code for Woofer to your
+imagination):
 
   class Dog
     def initialize
@@ -246,109 +397,136 @@ Woofer to your imagination):
     def bark
       @woofer.woof
     end
+    def wag
+      :happy
+    end
   end
 
-Now we want to test Dog, but using a real Woofer object in the test is
-a real pain (why? ... well because Woofer plays a sound file of a dog
-barking, and that's really annoying during testing).
+Now we want to test Dog, but using a real Woofer object in the test is a real
+pain (why? ... well because Woofer plays a sound file of a dog barking, and
+that's really annoying during testing).
 
-So, how can we create a Dog object with mocked Woofer?  All we need to
-do is stub out the +new+ method of the Woofer class object and tell to
-to return anything we want.
+So, how can we create a Dog object with mocked Woofer? All we need to do is
+allow FlexMock to replace the +bark+ method.
 
 Here's the test code:
 
   class TestDogBarking < Test::Unit::TestCase
     include FlexMock::TestCase
 
-    # Setup the tests by stubbing the +new+ method of 
+    # Setup the tests by mocking the +new+ method of 
     # Woofer and return a mock woofer.
     def setup
-      flexstub(Woofer).should_receive(:new).and_return {
-        flexmock("woofer") do |mock|
-          mock.should_receive(:woof).and_return(:grrrr)
-        end
-      }
+      @dog = Dog.new
+      flexmock(dog, :bark => :grrr)
     end
 
-    def test_bark
-      assert_equal :grrrr, @dog.bark
+    def test_dog
+      assert_equal :grrrr, @dog.bark   # Mocked Method
+      assert_equal :happy, @dog.wag    # Normal Method
     end
   end
 
-The nice thing about stub is that after the test is over, the stubbed
-out methods are returned to their normal state.  Outside the test
-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
+The nice thing about this technique is that after the test is over, the mocked
+out methods are returned to their normal state. Outside the test everything is
+back to normal.
 
-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.
+<b>NOTE:</b> In previous versions of FlexMock, partial mocking was called
+"stubs" and the +flexstub+ method was used to create the partial mocks.
+Although partial mocks were often used as stubs, the terminology was not quite
+correct. The current version of FlexMock uses the +flexmock+ method to create
+both regular stubs and partial stubs. A version of the +flexstub+ method is
+included for backwards compatibility. See Martin Fowler's article <em>Mocks
+Aren't Stubs</em> (http://www.martinfowler.com/articles/mocksArentStubs.html)
+for a better understanding of the difference between mocks and stubs.
 
-=== Class Interception
+This partial mocking technique was inspired by the +Stuba+ library in the
++Mocha+ project.
 
-<b>NOTE:</b> :: 
-  <em>Class Interception is now deprecated. It only worked in a
-  small number of cases. See the "Mocking Existing Objects"
-  example above for a much better approach to the same problem. 
-  Version 0.5.x will be the last version of FlexMock that supports the
-  Class Interception API.</em>
+=== Mocking Class Objects
 
-FlexMock now supports simple class interception. For the duration of a test, a
-mock class take the place of a named class inside the class to be tested.
+In the previous example we mocked out the +bark+ method of a Dog object to
+avoid invoking the Woofer object. Perhaps a better technique would be to mock
+the Woofer object directly. But Dog uses Woofer explicitly so we cannot just
+pass in a mock object for Dog to use.
 
-Example:
+But wait, we can add mock behavior to any existing object, and classes are
+objects in Ruby. So why don't we just mock out the Woofer class object to
+return mocks for us.
 
-Suppose we are testing class Foo, and Foo uses Bar internally.  We
-would like for Bar.new to return a mock object during the test.
+  class TestDogBarking < Test::Unit::TestCase
+    include FlexMock::TestCase
 
-   def test_foo_with_an_intercepted_bar
-     my_mock = flexmock("my_mock").should_receive(....).mock
-     intercept(Bar).in(Foo).with(my_mock.mock_factory)
+    # Setup the tests by mocking the +new+ method of 
+    # Woofer and return a mock woofer.
+    def setup
+      flexmock(Woofer).should_receive(:new).
+         and_return(flexmock(:woof => :grrr))
+      @dog = Dog.new
+    end
 
-     bar = Bar.new
-     bar.do_something
-   end
+    def test_dog
+      assert_equal :grrrr, @dog.bark  # Calls woof on mock object
+                                      # returned by Woofer.new
+    end
+  end
+
+=== Mocking Behavior in All Instances Created by a Class Object
+
+Sometimes returning a single mock object is not enough. Occasionally you want
+to mock <em>every</em> instance object created by a class. FlexMock makes this
+very easy.
+
+  class TestDogBarking < Test::Unit::TestCase
+    include FlexMock::TestCase
+
+    # Setup the tests by mocking Woofer to always
+    # return partial mocks.
+    def setup
+      flexmock(Woofer).new_instances.should_receive(:woof => :grrr)
+    end
+
+    def test_dog
+      assert_equal :grrrr, Dog.new.bark  # All dog objects
+      assert_equal :grrrr, Dog.new.bark  # are mocked.
+    end
+  end
+
+Note that FlexMock adds the mock 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 non-mocked version of the object.
+
+Note that +new_instances+ will accept a block if you wish to mock several
+methods at the same time. E.g.
+
+      flexmock(Woofer).new_instances do |m|
+        m.should_receive(:woof).twice.and_return(:grrr)
+        m.should_receive(:wag).at_least.once.and_return(:happy)
+      end
 
 == Examples
 
+=== Create a simple mock object that returns a value for a set of method calls
+
+   require 'flexmock/test_unit'
+   
+   class TestSimple < Test::Unit::TestCase
+     def test_simple_mock
+       m = flexmock(:pi => 3.1416, :e => 2.71)
+       assert_equal 3.1416, m.pi
+       assert_equal 2.71, m.e
+     end
+   end
+
 === Expect multiple queries and a single update
 
-The queries my have any arguments.  The update must have a specific
-argument of 5.
+Multiple calls to the query method will be allows, and calls may have any
+argument list. Each call to query will return the three element array [1, 2,
+3]. The call to update must have a specific argument of 5.
 
-   class TestDb
-     include FlexMock::TestCase         
+   require 'flexmock/test_unit'
 
+   class TestDb < Test::Unit::TestCase
      def test_db
        db = flexmock('db')
        db.should_receive(:query).and_return([1,2,3])
@@ -359,8 +537,8 @@ argument of 5.
 
 === Expect all queries before any updates
 
-(This and following examples assume that the FlexMock::TestCase module
-is being used.)
+(This and following examples assume that the 'flexmock/test_unit' file has
+been required.)
 
 All the query message must occur before any of the update messages.
 
@@ -467,25 +645,28 @@ ignoring.
 <b>Note:</b> The original +mock_ignore_missing+ is now an alias for
 +should_ignore_missing+.
 
-== Classic +mock_handle+ Interface
+=== Mock just one method on an existing object
 
-FlexMock still supports the simple +mock_handle+ interface used in the
-original version of FlexMock.  +mock_handle+ is equivalent to the
-following:
+The Portfolio class calculate the value of a set of stocks by talking to a quote service via a web service.  Since we don't want to use a real web service in our unit tests, we will mock the quote service.
 
-  def mock_handle(sym, expected_count=nil, &block)
-    self.should_receive(sym).times(expected_count).returns(&block)
+  def test_portfolio_value
+    flexmock(QuoteService).new_instances do |m|
+      m.should_receive(:quote).and_return(100)
+    end
+    port = Portfolio.new
+    value = port.value     # Portfolio calls QuoteService.quote
+    assert_equal 100, value
   end
 
 == Other Mock Objects
 
-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/
+Schmock        :: http://rubyforge.org/projects/schmock/
 
 == License
 
-Copyright 2003, 2004, 2005, 2006 by Jim Weirich (jim@weirichhouse.org).
+Copyright 2003, 2004, 2005, 2006, 2007 by Jim Weirich (jim@weirichhouse.org).
 All rights reserved.
 
 Permission is granted for use, copying, modification, distribution,