Mock - Mocking and Test Utilities

A Mock Library for Use With unittest

Author: Michael Foord
Version: Mock 0.4.0
Date: 2008/10/12
Homepage:Mock Homepage
License:BSD License
Support:fuzzyman@voidspace.org.uk

The Mock Manual

1   Introduction

There are already several Python mocking libraries available, so why another one?

Most mocking libraries follow the 'record -> replay' pattern of mocking. I prefer the 'action -> assertion' pattern, which is more readable and intuitive particularly when working with the Python unittest module. For a discussion of the merits of the two approaches, see Mocking, Patching, Stubbing: all that Stuff.

mock provides a core Mock class that is intended to reduce the need to create a host of trivial stubs throughout your test suite. After performing an action, you can make assertions about which methods / attributes were used and arguments they were called with. You can also specify return values and set specific attributes in the normal way.

It also provides a patch decorator that handles patching module and class level attributes within the scope of a test, along with sentinel for creating unique objects.

2   Downloading

The current version is 0.4.0, dated 12th October 2008. Mock is still experimental. The API may change or it may never get used! If you find bugs or have suggestions for improvements / extensions then please email me.

You can checkout the latest development version from the Google Code Subversion repository with the following command:

svn checkout http://mock.googlecode.com/svn/trunk/ mock-read-only

The are now eggs (for Python 2.4-2.6) up on the Mock Cheeseshop Page. This means that if you have setuptools you should be able to install mock with:

easy_install mock

3   Getting Started

Mock objects can be used for:

>>> from mock import Mock
>>>
>>> real = ProductionClass()
>>> real.method = Mock()
>>>
>>> real.method(3, 4, 5, key='value')
>>>
>>> real.method.assert_called_with(3, 4, 5, key='value')
>>> real.method.called
True
>>> real.method.call_args
((3, 4, 5), {'key': 'value'})
>>>
>>> mock = Mock()
>>> mock.something()
>>> mock.method_calls
[('something', (), {})]
>>>
>>> mock = Mock(methods=['something'])
>>> mock.something()
>>> mock.something_else()
Traceback (most recent call last):
   ...
AttributeError: object has no attribute 'something_else'

There are various ways of configuring the mock, including setting return values on the mock and its methods. A useful attribute is side_effect. If you set this to a callable then it will be called whenever the mock is called. This allows you to raise an exception or return members of a sequence from repeated calls:

>>> from mock import Mock
>>> mock = Mock()
>>> def side_effect():
...     raise Exception('Boom!')
...
>>> mock.side_effect = side_effect
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

>>> results = [1, 2, 3]
>>> def side_effect():
...     mock.return_value = results.pop()
...
>>> mock.side_effect = side_effect
>>> mock(), mock(), mock()
(3, 2, 1)

sentinel is a useful object for providing unique objects in your tests:

>>> from mock import sentinel
>>> real = ProductionClass()
>>> real.method = Mock()
>>>
>>> real.method.return_value = sentinel.ReturnValue
>>> real.method()
<SentinelObject "ReturnValue">

There are also decorators for doing module and class level patching. As modules and classes are effectively globals any patching has to be undone (or it persists into other tests). These decorators do the unpatching for you, making it easier to test with module and class level patching.

The two decorators are 'patch' and 'patch_object'. 'patch' takes a single string, of the form package.module.Class.attribute to specify the attribute you are patching. It also optionally takes a value that you want the attribute (or class or whatever) to be replaced with. 'patch_object' takes an object and the name of the attribute you would like patched, plus optionally the value to patch it with.

from mock import patch, sentinel

original = SomeClass.attribute
@patch_object(SomeClass, 'attribute', sentinel.Attribute)
def test():
    self.assertEquals(SomeClass.attribute, sentinel.Attribute, "class attribute not patched")
test()

self.assertEquals(SomeClass.attribute, original, "attribute not restored")


@patch('Package.Module.attribute', sentinel.Attribute)
def test():
    # do something
test()

If you don't want to call the decorated test function yourself, you can add apply as a decorator on top:

@apply
@patch('Package.Module', 'attribute', sentinel.Attribute)
def test():
    # do something

A nice pattern is to actually decorate test methods themselves:

@patch('Package.Module', 'attribute', sentinel.Attribute)
def testMethod(self):
    # do something

If you want to patch with a Mock, you can use patch with only one argument (or patch_object with two arguments). The mock will be created for you and passed into the test function / method:

@patch('Package.Module.Class')
def testMethod(self, mockClass):
    # do something

4   API Documentation

4.1   Mock

4.1.1   Initialisation

class Mock(object):
    def __init__(self, methods=None, spec=None,
                 return_value=None, side_effect=None)

Mock has several optional arguments:

  • methods: a list of strings. Attempting to access attributes or methods not in this list will raise an AttributeError. If this argument is not passed in then all attribute access will return a new mock object.
  • spec: This takes an existing object as the specification for the mock object. All attributes on the object (whether a class or an instance) are allowed, but accessing any other attributes will raise an AttributeError. Passing in an object as the spec argument is the equivalent of passing in a list of strings to method with all the attributes on the object.
  • return_value: The value returned when the mock is called. By default this is a new Mock (created on first access). See the return_value attribute.
  • side_effect: A function to be called whenever the Mock is called. See the side_effect attribute.

4.1.2   Calling

def __call__(self, *args, **keywargs):

Mock objects are callable. The call will return the value set as the return_value attribute. The default return value is a new Mock object; it is created the first time the return value is accessed (either explicitly or by calling the Mock) - but it is stored and the same one returned each time.

Calls made to the object will be recorded in the attributes.

If side_effect is set then it will be called after the call has been recorded but before any value is returned.

4.1.3   reset

def reset(self):

The reset method resets all the call attributes on a mock object.

>>> mock = Mock()
>>> mock('hello')
>>> mock.called
True
>>> mock.reset()
>>> mock.called
False

This can be useful where you want to make a series of assertions that reuse the same object. Note that reset doesn't clear the return value or any child attributes. Attributes you have set using normal assignment are also left in place. Child mocks and the return value mock (if any) are reset as well.

4.1.4   assert_called_with

This method is a convenient way of asserting that calls are made in a particular way:

>>> mock = Mock()
>>> mock.method(1, 2, 3, test='wow')
>>> mock.method.assert_called_with(1, 2, 3, test='wow')

4.1.5   Attributes

4.1.5.1   called

A boolean representing whether or not the mock object has been called.

>>> mock = Mock()
>>> mock.called
False
>>> mock()
>>> mock.called
True

4.1.5.2   return_value

Set this to configure the value returned by calling the mock.

>>> mock = Mock()
>>> mock.return_value = 'fish'
>>> mock()
'fish'

The default return value is a mock object and you can configure it in the normal way.

>>> mock = Mock()
>>> mock.return_value.attribute = sentinel.Attribute
>>> mock.return_value()
>>> mock.return_value.assert_called_with()

4.1.5.3   side_effect

Sometimes when a mock is called you want to raise an exception (to test exception handling of an API) or return values from a sequence instead of a single value. These can be achieved with the side_effect attribute:

>>> from mock import Mock
>>> mock = Mock()
>>> def side_effect():
...     raise Exception('Boom!')
...
>>> mock.side_effect = side_effect
>>> mock()
Traceback (most recent call last):
  ...
Exception: Boom!

>>> results = [1, 2, 3]
>>> def side_effect():
...     mock.return_value = results.pop()
...
>>> mock.side_effect = side_effect
>>> mock(), mock(), mock()
(3, 2, 1)

4.1.5.4   call_args

This is either None (if the mock hasn't been called), or the arguments that the mock was last called with. This will be in the form of a tuple: the first member is any ordered arguments the mock was called with (or an empty tuple) and the second member is any keyword arguments (or an empty dictionary):

>>> mock = Mock()
>>> print mock.call_args
None
>>> mock()
>>> mock.call_args
((), {})
>>>
>>> mock(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args
((3, 4, 5), {'key': 'fish', 'next': 'w00t!'})

4.1.5.5   call_args_list

This is a list of all the calls made to the mock object in sequence. Before any calls have been made it is an empty list.

>>> mock = Mock()
>>> mock()
>>> mock(3, 4, 5, key='fish', next='w00t!')
>>> mock.call_args_list
[((), {}), ((3, 4, 5), {'key': 'fish', 'next': 'w00t!'})]

4.1.5.6   method_calls

As well as tracking calls to themselves, mocks also track calls to methods and attributes, and their methods and attributes:

>>> mock = Mock()
>>> mock.method()
>>> mock.property.method.attribute()
>>> mock.method_calls
[('method', (), {}), ('property.method.attribute', (), {})]

4.2   Sentinel

The sentinel object provides a convenient way of providing unique objects for your tests. See Sentinel Examples.

Attributes are created on demand when you access them by name. Accessing the same attribute will always return the same object. The objects returned have a sensible repr so that test failure messages are readable.

4.3   Patch Decorators

The patch decorators are used for patching objects only within the scope of the function they decorate. They automatically handle the unpatching for you, even if exceptions are raised.

4.3.1   patch_object

patch_object patches named members on objects - usually class or module objects.

def patch_object(target, attribute, new=None):

You can either call it with three arguments or two arguments. The three argument form takes the object to be patched, the attribute name and the object to replace the attribute with.

When calling with the two argument form you omit the replacement object, and a mock is created for you and passed in as an extra argument to the decorated function:

@patch_object(SomeClass, 'classmethod')
def test_something(self, mockMethod):
    SomeClass.classmethod(3)

    mockMethod.assert_called_with(3)

4.3.2   patch

def patch(target, new=None):

patch decorates a function. Inside the body of the function, the target (specified in the form 'PackageName.ModuleName.ClassName') is patched with a new object. When the function exits the patch is undone.

If you want to perform multiple patches then you can simply stack up the decorators on a function if you particularly feel the need.

The target is imported and the specified attribute patched with the new object - so it must be importable from the environment you are calling the decorator from.

If new is omitted, then a new Mock is created and passed in as an extra argument to the decorated function:

@patch('Package.ModuleName.ClassName')
def test_something(self, mockClass):
    # ...

5   Examples

For further examples, see the unit tests included in the full source distribution.

5.1   Mock Examples

5.1.1   Mock Patching Methods

Mock is callable. If it is called then it sets a called attribute to True.

This example tests that calling method results in a call to something:

def test_method_calls_something(self):
    real = ProductionClass()
    real.something = Mock()

    real.method()

    self.assertTrue(real.something.called, "method didn't call something")

If you want to catch the arguments then there is other information exposed:

def test_method_calls_something(self):
    real = ProductionClass()
    real.something = Mock()

    real.method()

    self.assertEquals(real.something.call_count, 1, "something called incorrect number of times")

    args = ()
    keywargs = {}
    self.assertEquals(real.something.call_args, (args, keywargs), "something called with incorrect arguments")
    self.assertEquals(real.something.call_args_list, [(args, keywargs)],
                      "something called with incorrect arguments")

Checking call_args_list tests how many times the mock was called, and the arguments for each call, in a single assertion.

5.1.2   Mock for Method Calls on an Object

def test_closer_closes_something(self):
    real = ProductionClass()
    mock = Mock()

    real.closer(mock)

    self.assertTrue(mock.close.called, "closer didn't close something")

We don't have to do any work to provide the 'close' method on our mock. Accessing close creates it. So, if 'close' hasn't already been called then accessing it in the test will create it - but called will be False.

As close is a mock object is has all the attributes from the previous example.

5.1.3   Limiting Available Methods

The disadvantage of the approach above is that all method access creates a new mock. This means that you can't tell if any methods were called that shouldn't have been. There are two ways round this. The first is by restricting the methods available on your mock.

def test_closer_closes_something(self):
    real = ProductionClass()
    methods = ['close']
    mock = Mock(methods) # methods=methods is equivalent

    real.closer(mock)

    self.assertTrue(mock.close.called, "closer didn't close something")

If closer calls any methods on mock other than close, then an AttributeError will be raised.

5.1.4   Tracking all Method Calls

An alternative way to verify that only the expected methods have been accessed is to use the method_calls attribute of the mock. This records all calls to child attributes of the mock - and also to their children.

This is useful if you have a mock where you expect an attribute method to be called. You could access the attribute directly, but method_calls provides a convenient way of looking at all method calls:

>>> mock = Mock()
>>> mock.method()
>>> mock.Property.method(10, x=53)
>>> mock.method_calls
[('method', (), {}), ('Property.method', (10,), {'x': 53})]
>>>

If you make an assertion about method_calls and any unexpected methods have been called, then the assertion will fail.

5.1.5   Setting Return Values and Setting Attributes

Setting the return values on a mock object is trivially easy:

>>> mock = Mock()
>>> mock.return_value = 3
>>> mock()
3

Of course you can do the same for methods on the mock:

>>> mock = Mock()
>>> mock.method.return_value = 3
>>> mock.method()
3

If you need an attribute setting on your mock, just do it:

>>> mock = Mock()
>>> mock.x = 3
>>> mock.x
3

Sometimes you want to mock up a more complex situation, like for example mock.connection.cursor().execute("SELECT 1"):

>>> mock = Mock()
>>> cursor = mock.connection.cursor.return_value
>>>
>>> mock.connection.cursor().execute("SELECT 1")
>>> mock.method_calls
[('connection.cursor', (), {})]
>>> cursor.method_calls
[('execute', ('SELECT 1',), {})]
>>>

5.1.6   Creating a Mock from an Existing Object

One problem with over use of mocking is that it couples your tests to the implementation of your mocks rather than your real code. Suppose you have a class that implements some_method. In a test for another class, you provide a mock of this object that also provides some_method. If later you refactor the first class, so that it no longer has some_method - then your tests will continue to pass even though your code is now broken!

Mock allows you to provide an object as a specification for the mock, using the spec keyword argument. Accessing methods / attributes on the mock that don't exist on your specification object will immediately raise an attribute error. If you change the implementation of your specification, then tests that use that class will start failing immediately without you having to instantiate the class in those tests.

>>> mock = Mock(spec=SomeClass)
>>>
>>> mock.old_method()
Traceback (most recent call last):
   ...
AttributeError: object has no attribute 'old_method'

5.2   Sentinel Examples

Sometimes when testing you need to test that a specific object is passed as an argument to another method, or returned. It can be common to create named sentinel objects to test this. sentinel provides a convenient way of creating and testing the identity of objects like this.

In this example we monkey patch method to return sentinel.ReturnValue. We want to test that this is the value returned when we call something.

from mock import Mock, sentinel

real = ProductionClass()

real.method = Mock()
real.method.return_value = sentinel.ReturnValue

returned = real.something()
self.assertEquals(returned, sentinel.ReturnValue, "something returned the wrong value")

5.3   Patch Decorator Examples

A common need in tests is to patch a class attribute or a module attribute, for example patching a builtin or patching a class in a module to test that it is instantiated. Modules and classes are effectively global, so patching on them has to be undone after the test or the patch will persist into other tests and cause hard to diagnose problems.

The patch and patch_object decorators provide a convenient way of doing this.

patch_object patches attributes on objects within the scope of a function they decorate:

mock = Mock()

@patch_object(SomeClass, 'class_method', mock)
def test():
    SomeClass.class_method()
test()

self.assertTrue(mock.called, "class_method not called")

The decorator is applied to a function (called test above). The patching only applies inside the body of the function. You have to call the function explicitly, this can be useful as the test function can take arguments and be used to implement several tests, it can also return values.

They can be stacked to perform multiple simultaneous patches:

mock1 = Mock()
mock2 = Mock()

@patch_object(SomeClass, 'class_method', mock1)
@patch_object(SomeClass, 'static_method', mock2)
def test():
    SomeClass.class_method()
    SomeClass.static_method()
test()

self.assertTrue(mock1.called, "class_method not called")
self.assertTrue(mock2.called, "static_method not called")

If you are patching a module (including __builtin__) then use patch instead of patch_object:

mock = Mock()
mock.return_value = sentinel.Handle

@patch('__builtin__.open', mock)
def test():
    return open('filename', 'r')

handle = test()

self.assertEquals(mock.call_args, (('filename', 'r'), {}), "open not called correctly")
self.assertEquals(handle, sentinel.Handle, "incorrect file handle returned")

The module name can be 'dotted', in the form package.module if needed.

If you don't want to call the decorated test function yourself, you can add apply as a decorator on top:

@apply
@patch('Package.Module.attribute', sentinel.Attribute)
def test():
    # do something

A nice pattern is to actually decorate test methods themselves:

@patch_object(SomeClass, 'attribute', sentinel.Attribute)
def testMethod(self):
    self.assertEquals(SomeClass.attribute, sentinel.Attribute, "SomeClass not patched")

If you omit the second argument to patch (or the third argument to patch_object) then the attribute will be patched with a mock for you. The mock will be passed in as extra argument(s) to the function / method under test:

@patch_object(SomeClass, 'staticmethod')
def testMethod(self, mockMethod):
    SomeClass.staticmethod()
    self.assertTrue(mockMethod.called, "SomeClass not patched with a mock")

You can stack up multiple patch decorators using this pattern:

@patch('Module.ClassName1')
@patch('Module.ClassName2')
def testMethod(self, mockClass1, mockClass2):
    ClassName1()
    ClassName2()
    self.assertEquals(mockClass1.called, "ClassName1 not patched")
    self.assertEquals(mockClass2.called, "ClassName2 not patched")

6   Limitations

There are various disadvantages and things that Mock doesn't (yet) do.

7   CHANGELOG

7.1   2008/10/12 Version 0.4.0

  • Default return value is now a new mock rather than None

  • return_value added as a keyword argument to the constructor

  • New method 'assert_called_with'

  • Added 'side_effect' attribute / keyword argument called when mock is called

  • patch decorator split into two decorators:

    • patch_object which takes an object and an attribute name to patch (plus optionally a value to patch with which defaults to a mock object)
    • patch which takes a string specifying a target to patch; in the form 'package.module.Class.attribute'. (plus optionally a value to patch with which defaults to a mock object)

  • Can now patch objects with None

  • Change to patch for nose compatibility with error reporting in wrapped functions

  • Reset no longer clears children / return value etc - it just resets call count and call args. It also calls reset on all children (and the return value if it is a mock).

Thanks to Konrad Delong, Kevin Dangoor and others for patches and suggestions.

7.2   2007/12/03 Version 0.3.1

patch maintains the name of decorated functions for compatibility with nose test autodiscovery.

Tests decorated with patch that use the two argument form (implicit mock creation) will receive the mock(s) passed in as extra arguments.

Thanks to Kevin Dangoor for these changes.

7.3   2007/11/30 Version 0.3.0

Removed patch_module. patch can now take a string as the first argument for patching modules.

The third argument to patch is optional - a mock will be created by default if it is not passed in.

7.4   2007/11/21 Version 0.2.1

Bug fix, allows reuse of functions decorated with patch and patch_module.

7.5   2007/11/20 Version 0.2.0

Added spec keyword argument for creating Mock objects from a specification object.

Added patch and patch_module monkey patching decorators.

Added sentinel for convenient access to unique objects.

Distribution includes unit tests.

View document source. Generated on: 2008-10-12 22:11 UTC. Generated by Docutils from reStructuredText source.