Flex Mock – Making Mock Easy

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

Version

0.6.0

Links

Documents

flexmock.rubyforge.org

RubyGems

Install with: gem install flexmock

Download

Download from RubyForge at rubyforge.org/frs/?group_id=3433 (pre 0.6.0 versions may be found at 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.

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::Case::TestCase
  def test_dog_wags
    tail_mock = flexmock(:wag => :happy)
    assert_equal :happy, tail_mock.wag
  end
end

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

  • m = flexmock(“joe”)

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

  • m = flexmock(:foo => :bar, :baz => :froz)

    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.

  • m = flexmock(“joe”, :foo => :bar, :bar => :froz)

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

  • m = flexmock(real_object)

    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.

  • m = flexmock(real_object, “name”, :foo => :baz)

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

  • m = flexmock(:base, real_string_object)

    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.

  • m = flexmock(…) { |mock| mock.should_receive(…) }

    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.

NOTE: 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_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.

  • should_receive(method_name)

    Declares that a message named method_name will be sent to the mock object. Constraints on this expected message (called expectations) may be chained to the should_receive call.

  • should_receive(method_name1, method_name2, …)

    Define a number of expected messages that have the same constraints.

  • should_receive(meth1 => result1, meth2 => result2, …)

    Define a number of expected messages that have the same constrants, but return different values.

  • should_expect { |recorder| … }

    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.

  • with(arglist)

    Declares that this expectation matches messages that match the given argument list. The === 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.

  • with_any_args

    Declares that this expectation matches the message with any argument (default)

  • with_no_args

    Declares that this expectation matches messages with no arguments

  • and_return(value)

    Declares that the expected message will return the given value.

  • and_return(value1, value2, …)

    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.

  • and_return { |args, …| code … }

    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.

  • returns( … )

    Alias for and_return.

  • zero_or_more_times

    Declares that the expected message is may be sent zero or more times (default, equivalent to at_least.never).

  • once

    Declares that the expected message is only sent once. at_least / at_most modifiers are allowed.

  • twice

    Declares that the expected message is only sent twice. at_least / at_most modifiers are allowed.

  • never

    Declares that the expected message is never sent. at_least / at_most modifiers are allowed.

  • times(n)

    Declares that the expected message is sent n times. at_least / at_most modifiers are allowed.

  • at_least

    Modifies the immediately following message count constraint so that it means the message is sent at least that number of times. E.g. at_least.once means the message is sent at least once during the test, but may be sent more often. Both at_least and at_most may be specified on the same expectation.

  • at_most

    Similar to at_least, but puts an upper limit on the number of messages. Both at_least and at_most may be specified on the same expectation.

  • ordered

    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.

  • ordered(group)

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

    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 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 FlexMock.any 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 FlexMock.on(&block) 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.

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 :grrrr, @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.

NOTE: 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 Mocks Aren’t Stubs (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 every 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

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

Note: 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_recieve(:an_important_message).and_return(1).once
  m.should_ignore_missing
  # test code here
end

Note: The original mock_ignore_missing is now an alias for should_ignore_missing.

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

www.deveiate.org/code/Test-Unit-Mock.shtml

mocha/stubba

mocha.rubyforge.org/

Schmock

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.