psq / flexmock Goto Github PK

examples= Flex Mock -- Making Mock Easy

FlexMock is a simple, but flexible, mock object library for Ruby unit
testing.

Version :: 0.8.0.2

= Links

<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=3433 (pre 0.6.0 versions may be found at http://rubyforge.org/frs/?group_id=170)

== Installation

You can install FlexMock with the following command.

 $ gem install flexmock

== Simple Example

We have a data acquisition class (+TemperatureSampler+) that reads a
temperature sensor and returns an average of 3 readings.  We don't
have a _real_ temperature to use for testing, so we mock one up with a
mock object that responds to the +read_temperature+ message.

Here's the complete example:

  require 'test/unit'
  require 'flexmock/test_unit'

  class TemperatureSampler
    def initialize(sensor)
      @sensor = sensor
    end

    def average_temp
      total = (0...3).collect { 
        @sensor.read_temperature 
      }.inject { |i, s| i + s }
      total / 3.0
    end
  end

  class TestTemperatureSampler < Test::Unit::TestCase
    def test_sensor_can_average_three_temperature_readings
      sensor = flexmock("temp")
      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:

  require 'flexmock/test_unit'

  class TestDog < Test::Unit::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>mock = flexmock("joe")</b>

  Create a mock object named "joe" (the name is used in reporting errors).  

* <b>mock = 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>mock = flexmock("joe", :foo => :bar, :bar => :froz)</b>

  You can combine the mock name and an expectation hash in the same call to
  flexmock.

* <b>partial_mock = 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>partial_mock = flexmock(real_object, "name", :foo => :baz)</b>

  Names and expectation hashes may be used with partial mocks as well.

* <b>partial_mock = 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>partial_mock = flexmock(:safe, real_object) { |mock| mock.should_receive(...) }</b>

  When mocking real objects (i.e. "partial mocks"), FlexMock will add
  a handful of mock related methods to the actual object (see below
  for list of method names).  If one or more of these added methods
  collide with an existing method on the partial mock, then there are problems.

  FlexMock offers a "safe" mode for partial mocks that does not add
  these methods.  Indicate safe mode by passing the symbol :safe as
  the first argument of flexmock.  A block <em>is required</em> when
  using safe mode (the partial_mock returned in safe mode does not
  have a +should_receive+ method).

  The methods added to partial mocks in non-safe mode are:

  * should_receive
  * new_instances
  * any_instance  (note: deprecated)
  * mock
  * mock_teardown
  * mock_setup    

* <b>mock = 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>mock_model = flexmock(:model, YourModel, ...) { |mock| mock.should_receive(...) }</b>

  When given :model, flexmock() will return a pure mock (not a partial
  mock) that will have some ActiveRecord specific methods defined.
  YourModel should be the class of an ActiveRecord model.  These
  predefined methods make it a bit easier to mock out ActiveRecord
  model objects in a Rails application.  Other that the predefined
  mocked methods, the mock returned is a standard FlexMock mock
  object.

  The predefined mocked methods are:

  * id -- returns a unique ID for each mocked model.
  * to_params -- returns a stringified version of the id.
  * new_record? -- returns false.
  * errors -- returns an empty (mocked) errors object.
  * is_a?(other) -- returns true if other == YourModel.
  * instance_of?(class) -- returns true if class == YourModel
  * kind_of?(class) -- returns true if class is YourModel or one of its ancestors
  * class -- returns YourModel.

<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

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.

For example, the following code:

    mock.should_receive(: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>and_return(<em>value1</em>, <em>value2</em>, ...)</b>

  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>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>and_raise(exception, *args)</b>

  Declares that the expected messsage will raise the specified
  exception.  If +exception+ is an exception class, then the raised
  exception will be constructed from the class with +new+ given the
  supplied arguments.  If +exception+ is an instance of an exception
  class, then it will be raised directly.

* <b>raises( ... )</b>

  Alias for <tt>and_raise</tt>.

* <b>and_throw(symbol)</b>
* <b>and_throw(symbol, value)</b>

  Declares that the expected messsage will throw the specified symbol.
  If an optional value is included, then it will be the value returned
  from the corresponding catch statement.

* <b>throws( ... )</b>

  Alias for <tt>and_throw</tt>.

* <b>and_yield(values, ...)</b>

  Declares that the mocked method will receive a block, and the mock
  will call that block with the values given.  Not providing a block
  will be an error.  Providing more than one +and_yield+ clause one a
  single expectation will mean that subsquent mock method calls will
  yield the values provided by the additional +and_yield+ clause.

* <b>yields( ... )</b>

  Alias for <tt>and_yield( ... )</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>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.

  Normally ordering is performed only against calls in the same mock
  object.  If the "globally" adjective is used, then ordering is
  performed against the other globally ordered method calls.

* <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

  Normally ordering is performed only against calls in the same mock
  object.  If the "globally" adjective is used, then ordering is
  performed against the other globally ordered method calls.

* <b>globally.ordered</b>
* <b>globally.ordered(<em>group_name</em>)</b>

  When modified by the "globally" adjective, the mock call will be
  ordered against other globally ordered methods in any of the mock
  objects in the same container (i.e. same test).  All the options of
  the per-mock ordering are available in the globally ordered method
  calls.

* <b>by_default</b>

  Marks the expectation as a default.  Default expectations act as
  normal as long as there are no non-default expectations for the same
  method name.  As soon as a non-default expectation is defined, all
  default expectations for that method name are ignored.

  Default expectations allow you to setup a set of default behaviors
  for various methods in the setup of a test suite, and then override
  only the methods that need special handling in any given test.

* <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

  <b>NOTE:</b> <em>Using <b>mock</b> when specifying a Demeter mock
  chain will return the last mock of the chain, which might not be
  what you expect.

=== 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 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.

  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.

  Examples:

    with(/^src/)      will match    f("src_object")
    with(/^3\./)      will match    f(3.1415972)

* Most other objects will match based on equal values.

  Examples:

      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.

  Examples:

      with(eq(Integer))             will match       f(Integer)
      with(eq(Integer))             will NOT match   f(3)

  Note: If you do not use the FlexMock::TestCase Test Unit integration
  module, or the FlexMock::ArgumentTypes module, you will have to
  fully qualify the +eq+ method:

      with(FlexMock.eq(Integer))    will match       f(Integer)
      with(FlexMock.eq(Integer))    will NOT match   f(3)

* 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):

      with(any)             will match       f(3)
      with(any)             will match       f("hello")
      with(any)             will match       f(Integer)
      with(any)             will match       f(nil)

* If you wish to specify a complex matching criteria, use the
  <tt>FlexMock.on(&block)</tt> with the logic contained in the block.

  Examples (assumes FlexMock::ArguementTypes has been included):

      with(on { |arg| (arg % 2) == 0 } )

  will match any even integer.

* If you wish to match a method call where a block is given, add
  <tt>Proc</tt> as the last argument to <tt>with</tt>.

  Example:

      m.should_receive(:foo).with(Integer,Proc).and_return(:got_block)
      m.should_receive(:foo).with(Integer).and_return(:no_block)

  will cause the mock to return the following:

     m.foo(1) { } => returns :got_block
     m.foo(1)     => returns :no_block

=== 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. 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):

  class Dog
    def initialize
      @woofer = Woofer.new
    end
    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).

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 mocking the +new+ method of 
    # Woofer and return a mock woofer.
    def setup
      @dog = Dog.new
      flexmock(@dog, :bark => :grrr)
    end

    def test_dog
      assert_equal :grrr, @dog.bark   # Mocked Method
      assert_equal :happy, @dog.wag    # Normal Method
    end
  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.

<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.

This partial mocking technique was inspired by the +Stuba+ library in the
+Mocha+ project.

=== Mocking Class Objects

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.

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.

  class TestDogBarking < Test::Unit::TestCase
    include FlexMock::TestCase

    # 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

    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

=== Default Expectations on Mocks

Sometimes you want to setup a bunch of default expectations that are
pretty much for a number of different tests.  Then in the individual
tests, you would like to override the default behavior on just that
one method you are testing at the moment.  You can do that by using
the <tt>by_default</tt> modifier.

In your test setup you might have:

  def setup
    @mock_dog = flexmock("Fido")
    @mock_dog.should_receive(:tail => :a_tail, :bark => "woof").by_default
  end
    
The behaviors for :tail and :bark are good for most of the tests, but
perhaps you wish to verify that :bark is called exactly once in a
given test.  Since :bark by default has no count expectations, you can
override the default in the given test.

  def test_something_where_bark_must_be_called_once
    @mock_dog.should_receive(:bark => "woof").once

    # At this point, the default for :bark is ignored, 
    # and the "woof" value will be returned.

    # However, the default for :tail (which returns :a_tail)
    # is still active.
  end 

By setting defaults, your individual tests don't have to concern
themselves with details of all the default setup.  But the details of
the overrides are right there in the body of the test.

=== Mocking Law of Demeter Violations

The Law of Demeter says that you should only invoke methods on objects
to which you have a direct connection, e.g. parameters, instance
variables, and local variables.  You can usually detect Law of Demeter
violations by the excessive number of periods in an expression.  For
example:

     car.chassis.axle.universal_joint.cog.turn

The Law of Demeter has a very big impact on mocking.  If you need to
mock the "turn" method on "cog", you first have to mock chassis, axle,
and universal_joint.

    # Manually mocking a Law of Demeter violation
    cog = flexmock("cog")
    cog.should_receive(:turn).once.and_return(:ok)
    joint = flexmock("gear", :cog => cog)
    axle = flexmock("axle", :universal_joint => joint)
    chassis = flexmock("chassis", :axle => axle)
    car = flexmock("car", :chassis => chassis)

Yuck!

The best course of action is to avoid Law of Demeter violations.  Then
your mocking exploits will be very simple.  However, sometimes you
have to deal with code that already has a Demeter chain of method
calls.  So for those cases where you can't avoid it, FlexMock will
allow you to easily mock Demeter method chains.

Here's an example of Demeter chain mocking:

    # Demeter chain mocking using the short form.
    car = flexmock("car")
    car.should_receive( "chassis.axle.universal_joint.cog.turn" => :ok).once

You can also use the long form:

    # Demeter chain mocking using the long form.
    car = flexmock("car")
    car.should_receive("chassis.axle.universal_joint.cog.turn").once.
      and_return(:ok)

That's it.  Anywhere FlexMock accepts a method name for mocking, you
can use a demeter chain and FlexMock will attempt to do the right
thing.

But beware, there are a few limitations.

The all the methods in the chain, except for the last one, will mocked
to return a mock object.  That mock object, in turn, will be mocked so
as to respond to the next method in the chain, returning the following
mock.  And so on. If you try to manually mock out any of the chained
methods, you could easily interfer with the mocking specified by the
Demeter chain.  FlexMock will attempt to catch problems when it can,
but there are certainly scenarios where it cannot detect the problem
beforehand.

== 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

=== Create a mock object that returns an undefined object for method calls

   require 'flexmock/test_unit'
   
   class TestUndefined < Test::Unit::TestCase
     def test_undefined_values
       m = flexmock("mock")
       m.should_receive(:divide_by).with(0).
         and_return_undefined
       assert_equal FlexMock.undefined, m.divide_by(0)
     end
   end

=== Expect multiple queries and a single update

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.

   require 'flexmock/test_unit'

   class TestDb < Test::Unit::TestCase
     def test_db
       db = flexmock('db')
       db.should_receive(:query).and_return([1,2,3])
       db.should_receive(:update).with(5).and_return(nil).once
       # test code here
     end
   end

=== Expect all queries before any updates

(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.

   def test_query_and_update
     db = flexmock('db')
     db.should_receive(:query).and_return([1,2,3]).ordered
     db.should_receive(:update).and_return(nil).ordered
     # test code here
   end

=== Expect several queries with different parameters

The queries should happen after startup but before finish.  The
queries themselves may happen in any order (because they are in the
same order group).  The first two queries should happen exactly once,
but the third query (which matches any query call with a four
character parameter) may be called multiple times (but at least once).
Startup and finish must also happen exactly once.

Also note that we use the +with+ method to match different argument
values to figure out what value to return.

   def test_ordered_queries
     db = flexmock('db')
     db.should_receive(:startup).once.ordered
     db.should_receive(:query).with("CPWR").and_return(12.3).
       once.ordered(:queries)
     db.should_receive(:query).with("MSFT").and_return(10.0).
       once.ordered(:queries)
     db.should_receive(:query).with(/^....$/).and_return(3.3).
       at_least.once.ordered(:queries)
     db.should_receive(:finish).once.ordered
     # test code here
   end

=== Same as above, but using the Record Mode interface

The record mode interface offers much the same features as the
+should_receive+ interface introduced so far, but it allows the
messages to be sent directly to a recording object rather than be
specified indirectly using a symbol. 

   def test_ordered_queries_in_record_mode
     db = flexmock('db')
     db.should_expect do |rec|
       rec.startup.once.ordered
       rec.query("CPWR") { 12.3 }.once.ordered(:queries)
       rec.query("MSFT") { 10.0 }.once.ordered(:queries)
       rec.query(/^....$/) { 3.3 }.at_least.once.ordered(:queries)
       rec.finish.once.ordered
     end
     # test code here using +db+.
   end

=== Using Record Mode to record a known, good algorithm for testing

Record mode is nice when you have a known, good algorithm that can use
a recording mock object to record the steps.  Then you compare the
execution of a new algorithm to behavior of the old using the recorded
expectations in the mock.  For this you probably want to put the
recorder in _strict_ mode so that the recorded expectations use exact
matching on argument lists, and strict ordering of the method calls.

<b>Note:</b> This is most useful when there are no queries on the mock
objects, because the query responses cannot be programmed into the
recorder object.

  def test_build_xml
    builder = flexmock('builder')
    builder.should_expect do |rec|
      rec.should_be_strict
      known_good_way_to_build_xml(rec)  # record the messages
    end
    new_way_to_build_xml(builder)       # compare to new way
  end

=== Expect multiple calls, returning a different value each time

Sometimes you need to return different values for each call to a
mocked method.  This example shifts values out of a list for this
effect.

   def test_multiple_gets
     file = flexmock('file')
     file.should_receive(:gets).with_no_args.
        and_return("line 1\n", "line 2\n")
     # test code here
   end

=== Ignore uninteresting messages

Generally you need to mock only those methods that return an
interesting value or wish to assert were sent in a particular manner.
Use the +should_ignore_missing+ method to turn on missing method
ignoring.

   def test_an_important_message
     m = flexmock('m')
     m.should_receive(:an_important_message).and_return(1).once
     m.should_ignore_missing
     # test code here
   end

When +should_ignore_missing+ is enabled, ignored missing methods will
return an undefined object.  Any operation on the undefined object
will return the undefined object.

=== Mock just one method on an existing object

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 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

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, 2007 by Jim Weirich ([email protected]).
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.

= Other stuff

Author::   Jim Weirich <[email protected]>
Requires:: Ruby 1.8.x or later

== Warranty

This software is provided "as is" and without any express or
implied warranties, including, without limitation, the implied
warranties of merchantibility and fitness for a particular
purpose.