Mock - Mocking and Testing Library — Mock v0.7.0rc1 documentation

### Navigation

- index
- next |
- Mock v0.7.0rc1 documentation »

# Mock - Mocking and Testing Library

Author: | Michael Foord
Co-maintainer: | Konrad Delong
Version: | 0.7.0rc1
Date: | 2010/11/12
Homepage: | Mock Homepage
Download: | Mock on PyPI
Documentation: | PDF Documentation
License: | BSD License
Support: | Testing in Python Email List
Issue tracker: | Google code project

mock is a Python module that provides a core `Mock` class. It removes the need to create a host of 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 needed attributes in the normal way.

The mock module 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. See the quick guide for some examples of how to use `Mock`, `MagicMock` and `patch()`.

Mock is very easy to use and is designed for use with unittest. Mock is based on the ‘action -> assertion’ pattern instead of ‘record -> replay’ used by many mocking frameworks.

mock is tested on Python versions 2.4-2.7 and Python 3.

## API Documentation

- The Mock Class
  - Methods
  - Calling
  - Attributes
- Patch Decorators
  - patch
  - patch.object
  - patch_object
  - patch.dict
  - Nesting Patch Decorators
  - Patching Descriptors
- Sentinel
  - Sentinel Example
- Mocking Magic Methods
- Magic Mock
- mocksignature
  - Example use
  - mocksignature argument to patch

## User Guide

- Getting Started with Mock
  - Using Mock
  - Sentinel
  - Patch Decorators
- Examples
  - Mock Examples
  - Patch Decorator Examples
- TODO and Limitations
- CHANGELOG
  - 2011/XX/XX Version 0.7.0
  - 2010/11/12 Version 0.7.0 beta 4
  - 2010/09/18 Version 0.7.0 beta 3
  - 2010/06/23 Version 0.7.0 beta 2
  - 2010/06/22 Version 0.7.0 beta 1
  - 2009/08/22 Version 0.6.0
  - 2009/04/17 Version 0.5.0
  - 2008/10/12 Version 0.4.0
  - 2007/12/03 Version 0.3.1
  - 2007/11/30 Version 0.3.0
  - 2007/11/21 Version 0.2.1
  - 2007/11/20 Version 0.2.0
  - 2007/11/19 Version 0.1.0

## Installing

The current version is 0.7.0rc1, dated 2010/11/12. Mock is still experimental; the API may change (although we are moving towards a 1.0 release when the API will stabilise). If you find bugs or have suggestions for improvements / extensions then please contact us.

- mock on PyPI
- mock documentation as PDF
- Google Code Home & Mercurial Repository

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

> `hg clone https://mock.googlecode.com/hg/ mock`

If you have pip, setuptools or distribute you can install mock with:

> `easy_install -U mock`
> `pip install -U mock`

Alternatively you can download the mock distribution from PyPI and after unpacking run:

> `python setup.py install`

## Quick Guide

`Mock` objects create all attributes and methods as you access them and store details of how they have been used. You can configure them, to specify return values or limit what attributes are available, and then make assertions about how they have been used:

    >>> from mock import Mock
    >>> real = ProductionClass()
    >>> real.method = Mock(return_value=3)
    >>> real.method(3, 4, 5, key='value')
    3
    >>> real.method.assert_called_with(3, 4, 5, key='value')

`side_effect` allows you to perform side effects, return different values or raise an exception when a mock is called:

    >>> from mock import Mock
    >>> mock = Mock(side_effect=KeyError('foo'))
    >>> mock()
    Traceback (most recent call last):
     ...
    KeyError: 'foo'
    >>> values = [1, 2, 3]
    >>> def side_effect():
    ...     return values.pop()
    ...
    >>> mock.side_effect = side_effect
    >>> mock(), mock(), mock()
    (3, 2, 1)

Mock has many other ways you can configure it and control its behaviour. For example the `spec` argument configures the mock to take its specification from another object. Attempting to access attributes or methods on the mock that don’t exist on the spec will fail with an `AttributeError`.

The `patch()` decorator / context manager makes it easy to mock classes or objects in a module under test. The object you specify will be replaced with a mock (or other object) during the test and restored when the test ends:

    >>> from mock import patch
    >>> @patch('test_module.ClassName1')
    ... @patch('test_module.ClassName2')
    ... def test(MockClass1, MockClass2):
    ...     test_module.ClassName1()
    ...     test_module.ClassName2()

    ...     assert MockClass1.called
    ...     assert MockClass2.called
    ...
    >>> test()

    >>> with patch.object(ProductionClass, 'method') as mock_method:
    ...     mock_method.return_value = None
    ...     real = ProductionClass()
    ...     real.method(1, 2, 3)
    ...
    >>> mock_method.assert_called_with(1, 2, 3)

There is also `patch.dict()` for setting values in a dictionary just during a scope and restoring the dictionary to its original state when the test ends:

    >>> foo = {'key': 'value'}
    >>> original = foo.copy()
    >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
    ...     assert foo == {'newkey': 'newvalue'}
    ...
    >>> assert foo == original

Mock supports the mocking of Python magic methods. The easiest way of using magic methods is with the `MagicMock` class. It allows you to do things like:

    >>> from mock import MagicMock
    >>> mock = MagicMock()
    >>> mock.__str__.return_value = 'foobarbaz'
    >>> str(mock)
    'foobarbaz'
    >>> mock.__str__.assert_called_with()

Mock allows you to assign functions (or other Mock instances) to magic methods and they will be called appropriately. The MagicMock class is just a Mock variant that has all of the magic methods pre-created for you (well - all the useful ones anyway).

The following is an example of using magic methods with the ordinary Mock class:

    >>> from mock import Mock
    >>> mock = Mock()
    >>> mock.__str__ = Mock()
    >>> mock.__str__.return_value = 'wheeeeee'
    >>> str(mock)
    'wheeeeee'

`mocksignature()` is a useful companion to Mock and patch. It creates copies of functions that delegate to a mock, but have the same signature as the original function. This ensures that your mocks will fail in the same way as your production code if they are called incorrectly:

    >>> from mock import mocksignature
    >>> def function(a, b, c):
    ...     pass
    ...
    >>> function2 = mocksignature(function)
    >>> function2.mock.return_value = 'fishy'
    >>> function2(1, 2, 3)
    'fishy'
    >>> function2.mock.assert_called_with(1, 2, 3)
    >>> function2('wrong arguments')
    Traceback (most recent call last):
     ...
    TypeError: <lambda>() takes exactly 3 arguments (1 given)

mocksignature can also be used on classes, where it copies the signature of the __init__ method, and on callable objects where it copies the signature of the __call__ method.

## References

Articles and blog entries on testing with Mock:

- Checking multiple calls with mock and coping with mutable arguments
- Mocking unbound methods and properties
- Mocking patterns: chained calls, partial mocking and open as context manager
- Mock recipes
- Mockity mock mock - some love for the mock module
- Python Unit Testing with Mock
- Python mock testing techniques and tools
- How To Test Django Template Tags
- A presentation on Unit Testing with Mock
- Mocking with Django and Google AppEngine

## Tests

Mock uses unittest2 for its own test suite. In order to run it, use the `unit2` script that comes with `unittest2` module on a checkout of the source repository:

> `unit2 discover`

If you have setuptools as well as unittest2 you can run:

> `python setup.py test`

On Python 3.2 you can use `unittest` module from the standard library.

> `python3.2 -m unittest discover`

On Python 2.4 you will see one error; testwith.py will fail to import as it uses the `with` statement which is invalid syntax under Python 2.4.

On Python 3 the tests for unicode are skipped as they are not relevant.

## Older Versions

Documentation for older versions of mock:

- mock 0.6.0

### Navigation

- index
- next |
- Mock v0.7.0rc1 documentation »