4
Summary: A Python Mocking and Patching Library for Testing
5
Home-page: http://www.voidspace.org.uk/python/mock/
7
Author-email: michael@voidspace.org.uk
9
Description: mock is a Python module that provides a core Mock class. It removes the need
10
to create a host of stubs throughout your test suite. After performing an
11
action, you can make assertions about which methods / attributes were used and
12
arguments they were called with. You can also specify return values and set
13
needed attributes in the normal way.
15
mock is tested on Python versions 2.4-2.7 and Python 3.
17
The mock module also provides utility functions / objects to assist with
18
testing, particularly monkey patching.
20
* `PDF documentation for 0.7.2
21
<http://www.voidspace.org.uk/downloads/mock-0.7.2.pdf>`_
22
* `mock on google code (repository and issue tracker)
23
<http://code.google.com/p/mock/>`_
25
<http://www.voidspace.org.uk/python/mock/>`_
26
* `mock on PyPI <http://pypi.python.org/pypi/mock/>`_
27
* `Mailing list (testing-in-python@lists.idyll.org)
28
<http://lists.idyll.org/listinfo/testing-in-python>`_
30
Mock is very easy to use and is designed for use with
31
`unittest <http://pypi.python.org/pypi/unittest2>`_. Mock is based on
32
the 'action -> assertion' pattern instead of 'record -> replay' used by many
33
mocking frameworks. See the
34
`mock documentation <http://www.voidspace.org.uk/python/mock/>`_ for full
37
Mock objects create all attributes and methods as you access them and store
38
details of how they have been used. You can configure them, to specify return
39
values or limit what attributes are available, and then make assertions about
40
how they have been used::
42
>>> from mock import Mock
43
>>> real = ProductionClass()
44
>>> real.method = Mock(return_value=3)
45
>>> real.method(3, 4, 5, key='value')
47
>>> real.method.assert_called_with(3, 4, 5, key='value')
49
``side_effect`` allows you to perform side effects, return different values or
50
raise an exception when a mock is called::
52
>>> from mock import Mock
53
>>> mock = Mock(side_effect=KeyError('foo'))
55
Traceback (most recent call last):
58
>>> values = [1, 2, 3]
59
>>> def side_effect():
60
... return values.pop()
62
>>> mock.side_effect = side_effect
63
>>> mock(), mock(), mock()
66
Mock has many other ways you can configure it and control its behaviour. For
67
example the ``spec`` argument configures the mock to take its specification from
68
another object. Attempting to access attributes or methods on the mock that
69
don't exist on the spec will fail with an ``AttributeError``.
71
The ``patch`` decorator / context manager makes it easy to mock classes or
72
objects in a module under test. The object you specify will be replaced with a
73
mock (or other object) during the test and restored when the test ends::
75
>>> from mock import patch
76
>>> @patch('test_module.ClassName1')
77
... @patch('test_module.ClassName2')
78
... def test(MockClass2, MockClass1):
79
... test_module.ClassName1()
80
... test_module.ClassName2()
82
... assert MockClass1.called
83
... assert MockClass2.called
89
When you nest patch decorators the mocks are passed in to the decorated
90
function in the same order they applied (the normal *python* order that
91
decorators are applied). This means from the bottom up, so in the example
92
above the mock for `test_module.ClassName2` is passed in first.
94
With `patch` it matters that you patch objects in the namespace where they
95
are looked up. This is normally straightforward, but for a quick guide
97
<http://www.voidspace.org.uk/python/mock/patch.html#where-to-patch>`_.
99
As well as a decorator `patch` can be used as a context manager in a with
102
>>> with patch.object(ProductionClass, 'method') as mock_method:
103
... mock_method.return_value = None
104
... real = ProductionClass()
105
... real.method(1, 2, 3)
107
>>> mock_method.assert_called_with(1, 2, 3)
109
There is also `patch.dict` for setting values in a dictionary just during the
110
scope of a test and restoring the dictionary to its original state when the
113
>>> foo = {'key': 'value'}
114
>>> original = foo.copy()
115
>>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
116
... assert foo == {'newkey': 'newvalue'}
118
>>> assert foo == original
120
Mock now supports the mocking of Python magic methods. The easiest way of
121
using magic methods is with the ``MagicMock`` class. It allows you to do
124
>>> from mock import MagicMock
125
>>> mock = MagicMock()
126
>>> mock.__str__.return_value = 'foobarbaz'
129
>>> mock.__str__.assert_called_with()
131
Mock allows you to assign functions (or other Mock instances) to magic methods
132
and they will be called appropriately. The MagicMock class is just a Mock
133
variant that has all of the magic methods pre-created for you (well - all the
136
The following is an example of using magic methods with the ordinary Mock
139
>>> from mock import Mock
141
>>> mock.__str__ = Mock()
142
>>> mock.__str__.return_value = 'wheeeeee'
146
`mocksignature` is a useful companion to Mock and patch. It creates
147
copies of functions that delegate to a mock, but have the same signature as the
148
original function. This ensures that your mocks will fail in the same way as
149
your production code if they are called incorrectly::
151
>>> from mock import mocksignature
152
>>> def function(a, b, c):
155
>>> function2 = mocksignature(function)
156
>>> function2.mock.return_value = 'fishy'
157
>>> function2(1, 2, 3)
159
>>> function2.mock.assert_called_with(1, 2, 3)
160
>>> function2('wrong arguments')
161
Traceback (most recent call last):
163
TypeError: <lambda>() takes exactly 3 arguments (1 given)
165
`mocksignature` can also be used on classes, where it copies the signature of
166
the `__init__` method, and on callable objects where it copies the signature of
167
the `__call__` method.
169
The distribution contains tests and documentation. The tests require
170
`unittest2 <http://pypi.python.org/pypi/unittest2>`_ to run.
172
Keywords: testing,test,mock,mocking,unittest,patching,stubs,fakes,doubles
174
Classifier: Development Status :: 5 - Production/Stable
175
Classifier: Environment :: Console
176
Classifier: Intended Audience :: Developers
177
Classifier: License :: OSI Approved :: BSD License
178
Classifier: Programming Language :: Python
179
Classifier: Programming Language :: Python :: 2
180
Classifier: Programming Language :: Python :: 3
181
Classifier: Programming Language :: Python :: 2.4
182
Classifier: Programming Language :: Python :: 2.5
183
Classifier: Programming Language :: Python :: 2.6
184
Classifier: Programming Language :: Python :: 2.7
185
Classifier: Programming Language :: Python :: 3.0
186
Classifier: Programming Language :: Python :: 3.1
187
Classifier: Programming Language :: Python :: 3.2
188
Classifier: Operating System :: OS Independent
189
Classifier: Topic :: Software Development :: Libraries
190
Classifier: Topic :: Software Development :: Libraries :: Python Modules
191
Classifier: Topic :: Software Development :: Testing
added
removed
mock.egg-info/PKG-INFO
