| Author: | Michael Foord |
|---|---|
| Version: | 1.0.0 |
| Date: | 2012/10/07 |
| Homepage: | Mock Homepage |
| Download: | Mock on PyPI |
| Documentation: | PDF Documentation |
| License: | BSD License |
| Support: | Mailing list (testing-in-python@lists.idyll.org) |
| Issue tracker: | Google code project |
mock is a library for testing in Python. It allows you to replace parts of your system under test with mock objects and make assertions about how they have been used.
mock is now part of the Python standard library, available as unittest.mock in Python 3.3 onwards.
mock provides a core Mock class removing 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.
Additionally, mock 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, Python 3 plus the latest versions of Jython and PyPy.
The current version is 1.0.0. Mock is stable and widely used. If you do find any bugs, or have suggestions for improvements / extensions then please contact us.
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 mockpip install -U mock
Alternatively you can download the mock distribution from PyPI and after unpacking run:
python setup.py install
Mock and MagicMock 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 MagicMock
>>> thing = ProductionClass()
>>> thing.method = MagicMock(return_value=3)
>>> thing.method(3, 4, 5, key='value')
3
>>> thing.method.assert_called_with(3, 4, 5, key='value')
side_effect allows you to perform side effects, including raising an exception when a mock is called:
>>> mock = Mock(side_effect=KeyError('foo'))
>>> mock()
Traceback (most recent call last):
...
KeyError: 'foo'
>>> values = {'a': 1, 'b': 2, 'c': 3}
>>> def side_effect(arg):
... return values[arg]
...
>>> mock.side_effect = side_effect
>>> mock('a'), mock('b'), mock('c')
(1, 2, 3)
>>> mock.side_effect = [5, 4, 3, 2, 1]
>>> mock(), mock(), mock()
(5, 4, 3)
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('module.ClassName2')
... @patch('module.ClassName1')
... def test(MockClass1, MockClass2):
... module.ClassName1()
... module.ClassName2()
... assert MockClass1 is module.ClassName1
... assert MockClass2 is module.ClassName2
... assert MockClass1.called
... assert MockClass2.called
...
>>> test()
Note
When you nest patch decorators the mocks are passed in to the decorated function in the same order they applied (the normal python order that decorators are applied). This means from the bottom up, so in the example above the mock for module.ClassName1 is passed in first.
With patch it matters that you patch objects in the namespace where they are looked up. This is normally straightforward, but for a quick guide read where to patch.
As well as a decorator patch can be used as a context manager in a with statement:
>>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method:
... thing = ProductionClass()
... thing.method(1, 2, 3)
...
>>> mock_method.assert_called_once_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:
>>> 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:
>>> mock = Mock()
>>> mock.__str__ = Mock(return_value='wheeeeee')
>>> str(mock)
'wheeeeee'
For ensuring that the mock objects in your tests have the same api as the objects they are replacing, you can use auto-speccing. Auto-speccing can be done through the autospec argument to patch, or the create_autospec() function. Auto-speccing creates mock objects that have the same attributes and methods as the objects they are replacing, and any functions and methods (including constructors) have the same call signature as the real object.
This ensures that your mocks will fail in the same way as your production code if they are used incorrectly:
>>> from mock import create_autospec
>>> def function(a, b, c):
... pass
...
>>> mock_function = create_autospec(function, return_value='fishy')
>>> mock_function(1, 2, 3)
'fishy'
>>> mock_function.assert_called_once_with(1, 2, 3)
>>> mock_function('wrong arguments')
Traceback (most recent call last):
...
TypeError: <lambda>() takes exactly 3 arguments (1 given)
create_autospec 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.
Articles, blog entries and other stuff related to testing with Mock:
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 3 the tests for unicode are skipped as they are not relevant. On Python 2.4 tests that use the with statements are skipped as the with statement is invalid syntax on Python 2.4.
Documentation for older versions of mock:
Docs from the in-development version of mock can be found at mock.readthedocs.org.
Terminology for objects used to replace other ones can be confusing. Terms like double, fake, mock, stub, and spy are all used with varying meanings.
In classic mock terminology mock.Mock is a spy that allows for post-mortem examination. This is what I call the “action -> assertion” [1] pattern of testing.
I’m not however a fan of this “statically typed mocking terminology” promulgated by Martin Fowler. It confuses usage patterns with implementation and prevents you from using natural terminology when discussing mocking.
I much prefer duck typing, if an object used in your test suite looks like a mock object and quacks like a mock object then it’s fine to call it a mock, no matter what the implementation looks like.
This terminology is perhaps more useful in less capable languages where different usage patterns will require different implementations. mock.Mock() is capable of being used in most of the different roles described by Fowler, except (annoyingly / frustratingly / ironically) a Mock itself!
How about a simpler definition: a “mock object” is an object used to replace a real one in a system under test.
| [1] | This pattern is called “AAA” by some members of the testing community; “Arrange - Act - Assert”. |