blob: 055abe0de1ce4e8aa4a64a7d4eb82e69fe3369b4 [file] [log] [blame]
Michael Foorda9e6fb22012-03-28 14:36:02 +01001:mod:`unittest.mock` --- getting started
2========================================
Michael Foord944e02d2012-03-25 23:12:55 +01003
Michael Foord944e02d2012-03-25 23:12:55 +01004.. moduleauthor:: Michael Foord <michael@python.org>
5.. currentmodule:: unittest.mock
6
7.. versionadded:: 3.3
8
9
Michael Foorda9e6fb22012-03-28 14:36:02 +010010.. _getting-started:
11
12Using Mock
13----------
14
15Mock Patching Methods
16~~~~~~~~~~~~~~~~~~~~~
17
18Common uses for :class:`Mock` objects include:
19
20* Patching methods
21* Recording method calls on objects
22
23You might want to replace a method on an object to check that
24it is called with the correct arguments by another part of the system:
25
26 >>> real = SomeClass()
27 >>> real.method = MagicMock(name='method')
28 >>> real.method(3, 4, 5, key='value')
29 <MagicMock name='method()' id='...'>
30
Georg Brandl7ad3df62014-10-31 07:59:37 +010031Once our mock has been used (``real.method`` in this example) it has methods
Michael Foorda9e6fb22012-03-28 14:36:02 +010032and attributes that allow you to make assertions about how it has been used.
33
34.. note::
35
36 In most of these examples the :class:`Mock` and :class:`MagicMock` classes
Georg Brandl7ad3df62014-10-31 07:59:37 +010037 are interchangeable. As the ``MagicMock`` is the more capable class it makes
Michael Foorda9e6fb22012-03-28 14:36:02 +010038 a sensible one to use by default.
39
40Once the mock has been called its :attr:`~Mock.called` attribute is set to
Georg Brandl7ad3df62014-10-31 07:59:37 +010041``True``. More importantly we can use the :meth:`~Mock.assert_called_with` or
Georg Brandl24891672012-04-01 13:48:26 +020042:meth:`~Mock.assert_called_once_with` method to check that it was called with
Michael Foorda9e6fb22012-03-28 14:36:02 +010043the correct arguments.
44
Georg Brandl7ad3df62014-10-31 07:59:37 +010045This example tests that calling ``ProductionClass().method`` results in a call to
46the ``something`` method:
Michael Foorda9e6fb22012-03-28 14:36:02 +010047
Ezio Melottic9cfcf12013-03-11 09:42:40 +020048 >>> class ProductionClass:
Michael Foorda9e6fb22012-03-28 14:36:02 +010049 ... def method(self):
50 ... self.something(1, 2, 3)
51 ... def something(self, a, b, c):
52 ... pass
53 ...
54 >>> real = ProductionClass()
55 >>> real.something = MagicMock()
56 >>> real.method()
57 >>> real.something.assert_called_once_with(1, 2, 3)
58
59
60
61Mock for Method Calls on an Object
62~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63
64In the last example we patched a method directly on an object to check that it
65was called correctly. Another common use case is to pass an object into a
66method (or some part of the system under test) and then check that it is used
67in the correct way.
68
Georg Brandl7ad3df62014-10-31 07:59:37 +010069The simple ``ProductionClass`` below has a ``closer`` method. If it is called with
70an object then it calls ``close`` on it.
Michael Foorda9e6fb22012-03-28 14:36:02 +010071
Ezio Melottic9cfcf12013-03-11 09:42:40 +020072 >>> class ProductionClass:
Michael Foorda9e6fb22012-03-28 14:36:02 +010073 ... def closer(self, something):
74 ... something.close()
75 ...
76
Georg Brandl7ad3df62014-10-31 07:59:37 +010077So to test it we need to pass in an object with a ``close`` method and check
Michael Foorda9e6fb22012-03-28 14:36:02 +010078that it was called correctly.
79
80 >>> real = ProductionClass()
81 >>> mock = Mock()
82 >>> real.closer(mock)
83 >>> mock.close.assert_called_with()
84
85We don't have to do any work to provide the 'close' method on our mock.
86Accessing close creates it. So, if 'close' hasn't already been called then
87accessing it in the test will create it, but :meth:`~Mock.assert_called_with`
88will raise a failure exception.
89
90
91Mocking Classes
92~~~~~~~~~~~~~~~
93
94A common use case is to mock out classes instantiated by your code under test.
95When you patch a class, then that class is replaced with a mock. Instances
96are created by *calling the class*. This means you access the "mock instance"
97by looking at the return value of the mocked class.
98
Georg Brandl7ad3df62014-10-31 07:59:37 +010099In the example below we have a function ``some_function`` that instantiates ``Foo``
100and calls a method on it. The call to :func:`patch` replaces the class ``Foo`` with a
101mock. The ``Foo`` instance is the result of calling the mock, so it is configured
Michael Foord0682a0c2012-04-13 20:51:20 +0100102by modifying the mock :attr:`~Mock.return_value`.
Michael Foorda9e6fb22012-03-28 14:36:02 +0100103
104 >>> def some_function():
105 ... instance = module.Foo()
106 ... return instance.method()
107 ...
108 >>> with patch('module.Foo') as mock:
109 ... instance = mock.return_value
110 ... instance.method.return_value = 'the result'
111 ... result = some_function()
112 ... assert result == 'the result'
113
114
115Naming your mocks
116~~~~~~~~~~~~~~~~~
117
118It can be useful to give your mocks a name. The name is shown in the repr of
119the mock and can be helpful when the mock appears in test failure messages. The
120name is also propagated to attributes or methods of the mock:
121
122 >>> mock = MagicMock(name='foo')
123 >>> mock
124 <MagicMock name='foo' id='...'>
125 >>> mock.method
126 <MagicMock name='foo.method' id='...'>
127
128
129Tracking all Calls
130~~~~~~~~~~~~~~~~~~
131
132Often you want to track more than a single call to a method. The
133:attr:`~Mock.mock_calls` attribute records all calls
134to child attributes of the mock - and also to their children.
135
136 >>> mock = MagicMock()
137 >>> mock.method()
138 <MagicMock name='mock.method()' id='...'>
139 >>> mock.attribute.method(10, x=53)
140 <MagicMock name='mock.attribute.method()' id='...'>
141 >>> mock.mock_calls
142 [call.method(), call.attribute.method(10, x=53)]
143
Georg Brandl7ad3df62014-10-31 07:59:37 +0100144If you make an assertion about ``mock_calls`` and any unexpected methods
Michael Foorda9e6fb22012-03-28 14:36:02 +0100145have been called, then the assertion will fail. This is useful because as well
146as asserting that the calls you expected have been made, you are also checking
147that they were made in the right order and with no additional calls:
148
149You use the :data:`call` object to construct lists for comparing with
Georg Brandl7ad3df62014-10-31 07:59:37 +0100150``mock_calls``:
Michael Foorda9e6fb22012-03-28 14:36:02 +0100151
152 >>> expected = [call.method(), call.attribute.method(10, x=53)]
153 >>> mock.mock_calls == expected
154 True
155
156
157Setting Return Values and Attributes
158~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
159
160Setting the return values on a mock object is trivially easy:
161
162 >>> mock = Mock()
163 >>> mock.return_value = 3
164 >>> mock()
165 3
166
167Of course you can do the same for methods on the mock:
168
169 >>> mock = Mock()
170 >>> mock.method.return_value = 3
171 >>> mock.method()
172 3
173
174The return value can also be set in the constructor:
175
176 >>> mock = Mock(return_value=3)
177 >>> mock()
178 3
179
180If you need an attribute setting on your mock, just do it:
181
182 >>> mock = Mock()
183 >>> mock.x = 3
184 >>> mock.x
185 3
186
187Sometimes you want to mock up a more complex situation, like for example
Georg Brandl7ad3df62014-10-31 07:59:37 +0100188``mock.connection.cursor().execute("SELECT 1")``. If we wanted this call to
Michael Foorda9e6fb22012-03-28 14:36:02 +0100189return a list, then we have to configure the result of the nested call.
190
191We can use :data:`call` to construct the set of calls in a "chained call" like
192this for easy assertion afterwards:
193
194 >>> mock = Mock()
195 >>> cursor = mock.connection.cursor.return_value
196 >>> cursor.execute.return_value = ['foo']
197 >>> mock.connection.cursor().execute("SELECT 1")
198 ['foo']
199 >>> expected = call.connection.cursor().execute("SELECT 1").call_list()
200 >>> mock.mock_calls
201 [call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]
202 >>> mock.mock_calls == expected
203 True
204
Georg Brandl7ad3df62014-10-31 07:59:37 +0100205It is the call to ``.call_list()`` that turns our call object into a list of
Michael Foorda9e6fb22012-03-28 14:36:02 +0100206calls representing the chained calls.
207
208
209Raising exceptions with mocks
210~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
211
212A useful attribute is :attr:`~Mock.side_effect`. If you set this to an
213exception class or instance then the exception will be raised when the mock
214is called.
215
216 >>> mock = Mock(side_effect=Exception('Boom!'))
217 >>> mock()
218 Traceback (most recent call last):
219 ...
220 Exception: Boom!
221
222
223Side effect functions and iterables
224~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
225
Georg Brandl7ad3df62014-10-31 07:59:37 +0100226``side_effect`` can also be set to a function or an iterable. The use case for
227``side_effect`` as an iterable is where your mock is going to be called several
Michael Foorda9e6fb22012-03-28 14:36:02 +0100228times, and you want each call to return a different value. When you set
Georg Brandl7ad3df62014-10-31 07:59:37 +0100229``side_effect`` to an iterable every call to the mock returns the next value
Michael Foorda9e6fb22012-03-28 14:36:02 +0100230from the iterable:
231
232 >>> mock = MagicMock(side_effect=[4, 5, 6])
233 >>> mock()
234 4
235 >>> mock()
236 5
237 >>> mock()
238 6
239
240
241For more advanced use cases, like dynamically varying the return values
Georg Brandl7ad3df62014-10-31 07:59:37 +0100242depending on what the mock is called with, ``side_effect`` can be a function.
Michael Foorda9e6fb22012-03-28 14:36:02 +0100243The function will be called with the same arguments as the mock. Whatever the
244function returns is what the call returns:
245
246 >>> vals = {(1, 2): 1, (2, 3): 2}
247 >>> def side_effect(*args):
248 ... return vals[args]
249 ...
250 >>> mock = MagicMock(side_effect=side_effect)
251 >>> mock(1, 2)
252 1
253 >>> mock(2, 3)
254 2
255
256
257Creating a Mock from an Existing Object
258~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
259
260One problem with over use of mocking is that it couples your tests to the
261implementation of your mocks rather than your real code. Suppose you have a
Georg Brandl7ad3df62014-10-31 07:59:37 +0100262class that implements ``some_method``. In a test for another class, you
263provide a mock of this object that *also* provides ``some_method``. If later
264you refactor the first class, so that it no longer has ``some_method`` - then
Michael Foorda9e6fb22012-03-28 14:36:02 +0100265your tests will continue to pass even though your code is now broken!
266
Georg Brandl7ad3df62014-10-31 07:59:37 +0100267:class:`Mock` allows you to provide an object as a specification for the mock,
268using the *spec* keyword argument. Accessing methods / attributes on the
Michael Foorda9e6fb22012-03-28 14:36:02 +0100269mock that don't exist on your specification object will immediately raise an
270attribute error. If you change the implementation of your specification, then
271tests that use that class will start failing immediately without you having to
272instantiate the class in those tests.
273
274 >>> mock = Mock(spec=SomeClass)
275 >>> mock.old_method()
276 Traceback (most recent call last):
277 ...
278 AttributeError: object has no attribute 'old_method'
279
Antoine Pitrou5c64df72013-02-03 00:23:58 +0100280Using a specification also enables a smarter matching of calls made to the
281mock, regardless of whether some parameters were passed as positional or
282named arguments::
283
284 >>> def f(a, b, c): pass
285 ...
286 >>> mock = Mock(spec=f)
287 >>> mock(1, 2, 3)
288 <Mock name='mock()' id='140161580456576'>
289 >>> mock.assert_called_with(a=1, b=2, c=3)
290
291If you want this smarter matching to also work with method calls on the mock,
292you can use :ref:`auto-speccing <auto-speccing>`.
293
Michael Foorda9e6fb22012-03-28 14:36:02 +0100294If you want a stronger form of specification that prevents the setting
295of arbitrary attributes as well as the getting of them then you can use
Georg Brandl7ad3df62014-10-31 07:59:37 +0100296*spec_set* instead of *spec*.
Michael Foorda9e6fb22012-03-28 14:36:02 +0100297
298
299
300Patch Decorators
301----------------
302
303.. note::
304
Georg Brandl7ad3df62014-10-31 07:59:37 +0100305 With :func:`patch` it matters that you patch objects in the namespace where
306 they are looked up. This is normally straightforward, but for a quick guide
Michael Foorda9e6fb22012-03-28 14:36:02 +0100307 read :ref:`where to patch <where-to-patch>`.
308
309
310A common need in tests is to patch a class attribute or a module attribute,
311for example patching a builtin or patching a class in a module to test that it
312is instantiated. Modules and classes are effectively global, so patching on
313them has to be undone after the test or the patch will persist into other
314tests and cause hard to diagnose problems.
315
Georg Brandl7ad3df62014-10-31 07:59:37 +0100316mock provides three convenient decorators for this: :func:`patch`, :func:`patch.object` and
317:func:`patch.dict`. ``patch`` takes a single string, of the form
318``package.module.Class.attribute`` to specify the attribute you are patching. It
Michael Foorda9e6fb22012-03-28 14:36:02 +0100319also optionally takes a value that you want the attribute (or class or
320whatever) to be replaced with. 'patch.object' takes an object and the name of
321the attribute you would like patched, plus optionally the value to patch it
322with.
323
Georg Brandl7ad3df62014-10-31 07:59:37 +0100324``patch.object``:
Michael Foorda9e6fb22012-03-28 14:36:02 +0100325
326 >>> original = SomeClass.attribute
327 >>> @patch.object(SomeClass, 'attribute', sentinel.attribute)
328 ... def test():
329 ... assert SomeClass.attribute == sentinel.attribute
330 ...
331 >>> test()
332 >>> assert SomeClass.attribute == original
333
334 >>> @patch('package.module.attribute', sentinel.attribute)
335 ... def test():
336 ... from package.module import attribute
337 ... assert attribute is sentinel.attribute
338 ...
339 >>> test()
340
Georg Brandl7ad3df62014-10-31 07:59:37 +0100341If you are patching a module (including :mod:`builtins`) then use :func:`patch`
342instead of :func:`patch.object`:
Michael Foorda9e6fb22012-03-28 14:36:02 +0100343
Ezio Melottib40a2202013-03-30 05:55:52 +0200344 >>> mock = MagicMock(return_value=sentinel.file_handle)
345 >>> with patch('builtins.open', mock):
Michael Foorda9e6fb22012-03-28 14:36:02 +0100346 ... handle = open('filename', 'r')
347 ...
348 >>> mock.assert_called_with('filename', 'r')
349 >>> assert handle == sentinel.file_handle, "incorrect file handle returned"
350
Georg Brandl7ad3df62014-10-31 07:59:37 +0100351The module name can be 'dotted', in the form ``package.module`` if needed:
Michael Foorda9e6fb22012-03-28 14:36:02 +0100352
353 >>> @patch('package.module.ClassName.attribute', sentinel.attribute)
354 ... def test():
355 ... from package.module import ClassName
356 ... assert ClassName.attribute == sentinel.attribute
357 ...
358 >>> test()
359
360A nice pattern is to actually decorate test methods themselves:
361
362 >>> class MyTest(unittest2.TestCase):
363 ... @patch.object(SomeClass, 'attribute', sentinel.attribute)
364 ... def test_something(self):
365 ... self.assertEqual(SomeClass.attribute, sentinel.attribute)
366 ...
367 >>> original = SomeClass.attribute
368 >>> MyTest('test_something').test_something()
369 >>> assert SomeClass.attribute == original
370
Georg Brandl7ad3df62014-10-31 07:59:37 +0100371If you want to patch with a Mock, you can use :func:`patch` with only one argument
372(or :func:`patch.object` with two arguments). The mock will be created for you and
Michael Foorda9e6fb22012-03-28 14:36:02 +0100373passed into the test function / method:
374
375 >>> class MyTest(unittest2.TestCase):
376 ... @patch.object(SomeClass, 'static_method')
377 ... def test_something(self, mock_method):
378 ... SomeClass.static_method()
379 ... mock_method.assert_called_with()
380 ...
381 >>> MyTest('test_something').test_something()
382
383You can stack up multiple patch decorators using this pattern:
384
385 >>> class MyTest(unittest2.TestCase):
386 ... @patch('package.module.ClassName1')
387 ... @patch('package.module.ClassName2')
388 ... def test_something(self, MockClass2, MockClass1):
Ezio Melottie2123702013-01-10 03:43:33 +0200389 ... self.assertIs(package.module.ClassName1, MockClass1)
390 ... self.assertIs(package.module.ClassName2, MockClass2)
Michael Foorda9e6fb22012-03-28 14:36:02 +0100391 ...
392 >>> MyTest('test_something').test_something()
393
394When you nest patch decorators the mocks are passed in to the decorated
395function in the same order they applied (the normal *python* order that
396decorators are applied). This means from the bottom up, so in the example
Georg Brandl7ad3df62014-10-31 07:59:37 +0100397above the mock for ``test_module.ClassName2`` is passed in first.
Michael Foorda9e6fb22012-03-28 14:36:02 +0100398
399There is also :func:`patch.dict` for setting values in a dictionary just
400during a scope and restoring the dictionary to its original state when the test
401ends:
402
403 >>> foo = {'key': 'value'}
404 >>> original = foo.copy()
405 >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
406 ... assert foo == {'newkey': 'newvalue'}
407 ...
408 >>> assert foo == original
409
Georg Brandl7ad3df62014-10-31 07:59:37 +0100410``patch``, ``patch.object`` and ``patch.dict`` can all be used as context managers.
Michael Foorda9e6fb22012-03-28 14:36:02 +0100411
Georg Brandl7ad3df62014-10-31 07:59:37 +0100412Where you use :func:`patch` to create a mock for you, you can get a reference to the
Michael Foorda9e6fb22012-03-28 14:36:02 +0100413mock using the "as" form of the with statement:
414
Ezio Melottic9cfcf12013-03-11 09:42:40 +0200415 >>> class ProductionClass:
Michael Foorda9e6fb22012-03-28 14:36:02 +0100416 ... def method(self):
417 ... pass
418 ...
419 >>> with patch.object(ProductionClass, 'method') as mock_method:
420 ... mock_method.return_value = None
421 ... real = ProductionClass()
422 ... real.method(1, 2, 3)
423 ...
424 >>> mock_method.assert_called_with(1, 2, 3)
425
426
Georg Brandl7ad3df62014-10-31 07:59:37 +0100427As an alternative ``patch``, ``patch.object`` and ``patch.dict`` can be used as
Michael Foorda9e6fb22012-03-28 14:36:02 +0100428class decorators. When used in this way it is the same as applying the
Larry Hastings3732ed22014-03-15 21:13:56 -0700429decorator individually to every method whose name starts with "test".
Michael Foorda9e6fb22012-03-28 14:36:02 +0100430
431
432.. _further-examples:
433
434Further Examples
Georg Brandl7fc972a2013-02-03 14:00:04 +0100435----------------
Michael Foorda9e6fb22012-03-28 14:36:02 +0100436
437
438Here are some more examples for some slightly more advanced scenarios.
Michael Foord944e02d2012-03-25 23:12:55 +0100439
440
441Mocking chained calls
Georg Brandl7fc972a2013-02-03 14:00:04 +0100442~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100443
444Mocking chained calls is actually straightforward with mock once you
445understand the :attr:`~Mock.return_value` attribute. When a mock is called for
Georg Brandl7ad3df62014-10-31 07:59:37 +0100446the first time, or you fetch its ``return_value`` before it has been called, a
447new :class:`Mock` is created.
Michael Foord944e02d2012-03-25 23:12:55 +0100448
449This means that you can see how the object returned from a call to a mocked
Georg Brandl7ad3df62014-10-31 07:59:37 +0100450object has been used by interrogating the ``return_value`` mock:
Michael Foord944e02d2012-03-25 23:12:55 +0100451
452 >>> mock = Mock()
453 >>> mock().foo(a=2, b=3)
454 <Mock name='mock().foo()' id='...'>
455 >>> mock.return_value.foo.assert_called_with(a=2, b=3)
456
457From here it is a simple step to configure and then make assertions about
458chained calls. Of course another alternative is writing your code in a more
459testable way in the first place...
460
461So, suppose we have some code that looks a little bit like this:
462
Ezio Melottic9cfcf12013-03-11 09:42:40 +0200463 >>> class Something:
Michael Foord944e02d2012-03-25 23:12:55 +0100464 ... def __init__(self):
465 ... self.backend = BackendProvider()
466 ... def method(self):
467 ... response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
468 ... # more code
469
Georg Brandl7ad3df62014-10-31 07:59:37 +0100470Assuming that ``BackendProvider`` is already well tested, how do we test
471``method()``? Specifically, we want to test that the code section ``# more
472code`` uses the response object in the correct way.
Michael Foord944e02d2012-03-25 23:12:55 +0100473
474As this chain of calls is made from an instance attribute we can monkey patch
Georg Brandl7ad3df62014-10-31 07:59:37 +0100475the ``backend`` attribute on a ``Something`` instance. In this particular case
Michael Foord944e02d2012-03-25 23:12:55 +0100476we are only interested in the return value from the final call to
Georg Brandl7ad3df62014-10-31 07:59:37 +0100477``start_call`` so we don't have much configuration to do. Let's assume the
Michael Foord944e02d2012-03-25 23:12:55 +0100478object it returns is 'file-like', so we'll ensure that our response object
Georg Brandl7ad3df62014-10-31 07:59:37 +0100479uses the builtin :func:`open` as its ``spec``.
Michael Foord944e02d2012-03-25 23:12:55 +0100480
481To do this we create a mock instance as our mock backend and create a mock
482response object for it. To set the response as the return value for that final
Georg Brandl7ad3df62014-10-31 07:59:37 +0100483``start_call`` we could do this::
Michael Foord944e02d2012-03-25 23:12:55 +0100484
Georg Brandl7ad3df62014-10-31 07:59:37 +0100485 mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response
Michael Foord944e02d2012-03-25 23:12:55 +0100486
487We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock`
488method to directly set the return value for us:
489
490 >>> something = Something()
Terry Jan Reedy30ffe7e2014-01-21 00:01:51 -0500491 >>> mock_response = Mock(spec=open)
Michael Foord944e02d2012-03-25 23:12:55 +0100492 >>> mock_backend = Mock()
493 >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response}
494 >>> mock_backend.configure_mock(**config)
495
496With these we monkey patch the "mock backend" in place and can make the real
497call:
498
499 >>> something.backend = mock_backend
500 >>> something.method()
501
502Using :attr:`~Mock.mock_calls` we can check the chained call with a single
503assert. A chained call is several calls in one line of code, so there will be
Georg Brandl7ad3df62014-10-31 07:59:37 +0100504several entries in ``mock_calls``. We can use :meth:`call.call_list` to create
Michael Foord944e02d2012-03-25 23:12:55 +0100505this list of calls for us:
506
507 >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
508 >>> call_list = chained.call_list()
509 >>> assert mock_backend.mock_calls == call_list
510
511
512Partial mocking
Georg Brandl7fc972a2013-02-03 14:00:04 +0100513~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100514
Georg Brandl7ad3df62014-10-31 07:59:37 +0100515In some tests I wanted to mock out a call to :meth:`datetime.date.today`
Georg Brandl728e4de2014-10-29 09:00:30 +0100516to return a known date, but I didn't want to prevent the code under test from
Georg Brandl7ad3df62014-10-31 07:59:37 +0100517creating new date objects. Unfortunately :class:`datetime.date` is written in C, and
518so I couldn't just monkey-patch out the static :meth:`date.today` method.
Michael Foord944e02d2012-03-25 23:12:55 +0100519
520I found a simple way of doing this that involved effectively wrapping the date
521class with a mock, but passing through calls to the constructor to the real
522class (and returning real instances).
523
524The :func:`patch decorator <patch>` is used here to
Georg Brandl7ad3df62014-10-31 07:59:37 +0100525mock out the ``date`` class in the module under test. The :attr:`side_effect`
Michael Foord944e02d2012-03-25 23:12:55 +0100526attribute on the mock date class is then set to a lambda function that returns
527a real date. When the mock date class is called a real date will be
Georg Brandl7ad3df62014-10-31 07:59:37 +0100528constructed and returned by ``side_effect``.
Michael Foord944e02d2012-03-25 23:12:55 +0100529
530 >>> from datetime import date
531 >>> with patch('mymodule.date') as mock_date:
532 ... mock_date.today.return_value = date(2010, 10, 8)
533 ... mock_date.side_effect = lambda *args, **kw: date(*args, **kw)
534 ...
535 ... assert mymodule.date.today() == date(2010, 10, 8)
536 ... assert mymodule.date(2009, 6, 8) == date(2009, 6, 8)
537 ...
538
Georg Brandl7ad3df62014-10-31 07:59:37 +0100539Note that we don't patch :class:`datetime.date` globally, we patch ``date`` in the
Michael Foord944e02d2012-03-25 23:12:55 +0100540module that *uses* it. See :ref:`where to patch <where-to-patch>`.
541
Georg Brandl7ad3df62014-10-31 07:59:37 +0100542When ``date.today()`` is called a known date is returned, but calls to the
543``date(...)`` constructor still return normal dates. Without this you can find
Michael Foord944e02d2012-03-25 23:12:55 +0100544yourself having to calculate an expected result using exactly the same
545algorithm as the code under test, which is a classic testing anti-pattern.
546
Georg Brandl7ad3df62014-10-31 07:59:37 +0100547Calls to the date constructor are recorded in the ``mock_date`` attributes
548(``call_count`` and friends) which may also be useful for your tests.
Michael Foord944e02d2012-03-25 23:12:55 +0100549
550An alternative way of dealing with mocking dates, or other builtin classes,
551is discussed in `this blog entry
Georg Brandl525d3552014-10-29 10:26:56 +0100552<http://www.williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/>`_.
Michael Foord944e02d2012-03-25 23:12:55 +0100553
554
555Mocking a Generator Method
Georg Brandl7fc972a2013-02-03 14:00:04 +0100556~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100557
Georg Brandl728e4de2014-10-29 09:00:30 +0100558A Python generator is a function or method that uses the :keyword:`yield` statement
559to return a series of values when iterated over [#]_.
Michael Foord944e02d2012-03-25 23:12:55 +0100560
561A generator method / function is called to return the generator object. It is
562the generator object that is then iterated over. The protocol method for
Georg Brandl728e4de2014-10-29 09:00:30 +0100563iteration is :meth:`~container.__iter__`, so we can
Georg Brandl7ad3df62014-10-31 07:59:37 +0100564mock this using a :class:`MagicMock`.
Michael Foord944e02d2012-03-25 23:12:55 +0100565
566Here's an example class with an "iter" method implemented as a generator:
567
Ezio Melottic9cfcf12013-03-11 09:42:40 +0200568 >>> class Foo:
Michael Foord944e02d2012-03-25 23:12:55 +0100569 ... def iter(self):
570 ... for i in [1, 2, 3]:
571 ... yield i
572 ...
573 >>> foo = Foo()
574 >>> list(foo.iter())
575 [1, 2, 3]
576
577
578How would we mock this class, and in particular its "iter" method?
579
580To configure the values returned from the iteration (implicit in the call to
Georg Brandl7ad3df62014-10-31 07:59:37 +0100581:class:`list`), we need to configure the object returned by the call to ``foo.iter()``.
Michael Foord944e02d2012-03-25 23:12:55 +0100582
583 >>> mock_foo = MagicMock()
584 >>> mock_foo.iter.return_value = iter([1, 2, 3])
585 >>> list(mock_foo.iter())
586 [1, 2, 3]
587
588.. [#] There are also generator expressions and more `advanced uses
589 <http://www.dabeaz.com/coroutines/index.html>`_ of generators, but we aren't
590 concerned about them here. A very good introduction to generators and how
591 powerful they are is: `Generator Tricks for Systems Programmers
592 <http://www.dabeaz.com/generators/>`_.
593
594
595Applying the same patch to every test method
Georg Brandl7fc972a2013-02-03 14:00:04 +0100596~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100597
598If you want several patches in place for multiple test methods the obvious way
599is to apply the patch decorators to every method. This can feel like unnecessary
Georg Brandl7ad3df62014-10-31 07:59:37 +0100600repetition. For Python 2.6 or more recent you can use :func:`patch` (in all its
Michael Foord944e02d2012-03-25 23:12:55 +0100601various forms) as a class decorator. This applies the patches to all test
602methods on the class. A test method is identified by methods whose names start
Georg Brandl7ad3df62014-10-31 07:59:37 +0100603with ``test``:
Michael Foord944e02d2012-03-25 23:12:55 +0100604
605 >>> @patch('mymodule.SomeClass')
606 ... class MyTest(TestCase):
607 ...
608 ... def test_one(self, MockSomeClass):
Ezio Melottie2123702013-01-10 03:43:33 +0200609 ... self.assertIs(mymodule.SomeClass, MockSomeClass)
Michael Foord944e02d2012-03-25 23:12:55 +0100610 ...
611 ... def test_two(self, MockSomeClass):
Ezio Melottie2123702013-01-10 03:43:33 +0200612 ... self.assertIs(mymodule.SomeClass, MockSomeClass)
Michael Foord944e02d2012-03-25 23:12:55 +0100613 ...
614 ... def not_a_test(self):
615 ... return 'something'
616 ...
617 >>> MyTest('test_one').test_one()
618 >>> MyTest('test_two').test_two()
619 >>> MyTest('test_two').not_a_test()
620 'something'
621
622An alternative way of managing patches is to use the :ref:`start-and-stop`.
Georg Brandl7ad3df62014-10-31 07:59:37 +0100623These allow you to move the patching into your ``setUp`` and ``tearDown`` methods.
Michael Foord944e02d2012-03-25 23:12:55 +0100624
625 >>> class MyTest(TestCase):
626 ... def setUp(self):
627 ... self.patcher = patch('mymodule.foo')
628 ... self.mock_foo = self.patcher.start()
629 ...
630 ... def test_foo(self):
Ezio Melottie2123702013-01-10 03:43:33 +0200631 ... self.assertIs(mymodule.foo, self.mock_foo)
Michael Foord944e02d2012-03-25 23:12:55 +0100632 ...
633 ... def tearDown(self):
634 ... self.patcher.stop()
635 ...
636 >>> MyTest('test_foo').run()
637
638If you use this technique you must ensure that the patching is "undone" by
Georg Brandl7ad3df62014-10-31 07:59:37 +0100639calling ``stop``. This can be fiddlier than you might think, because if an
Michael Foord944e02d2012-03-25 23:12:55 +0100640exception is raised in the setUp then tearDown is not called.
641:meth:`unittest.TestCase.addCleanup` makes this easier:
642
643 >>> class MyTest(TestCase):
644 ... def setUp(self):
645 ... patcher = patch('mymodule.foo')
646 ... self.addCleanup(patcher.stop)
647 ... self.mock_foo = patcher.start()
648 ...
649 ... def test_foo(self):
Ezio Melottie2123702013-01-10 03:43:33 +0200650 ... self.assertIs(mymodule.foo, self.mock_foo)
Michael Foord944e02d2012-03-25 23:12:55 +0100651 ...
652 >>> MyTest('test_foo').run()
653
654
655Mocking Unbound Methods
Georg Brandl7fc972a2013-02-03 14:00:04 +0100656~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100657
658Whilst writing tests today I needed to patch an *unbound method* (patching the
659method on the class rather than on the instance). I needed self to be passed
660in as the first argument because I want to make asserts about which objects
661were calling this particular method. The issue is that you can't patch with a
662mock for this, because if you replace an unbound method with a mock it doesn't
663become a bound method when fetched from the instance, and so it doesn't get
664self passed in. The workaround is to patch the unbound method with a real
665function instead. The :func:`patch` decorator makes it so simple to
666patch out methods with a mock that having to create a real function becomes a
667nuisance.
668
Georg Brandl7ad3df62014-10-31 07:59:37 +0100669If you pass ``autospec=True`` to patch then it does the patching with a
Michael Foord944e02d2012-03-25 23:12:55 +0100670*real* function object. This function object has the same signature as the one
671it is replacing, but delegates to a mock under the hood. You still get your
672mock auto-created in exactly the same way as before. What it means though, is
673that if you use it to patch out an unbound method on a class the mocked
674function will be turned into a bound method if it is fetched from an instance.
Georg Brandl7ad3df62014-10-31 07:59:37 +0100675It will have ``self`` passed in as the first argument, which is exactly what I
Michael Foord944e02d2012-03-25 23:12:55 +0100676wanted:
677
Ezio Melottic9cfcf12013-03-11 09:42:40 +0200678 >>> class Foo:
Michael Foord944e02d2012-03-25 23:12:55 +0100679 ... def foo(self):
680 ... pass
681 ...
682 >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo:
683 ... mock_foo.return_value = 'foo'
684 ... foo = Foo()
685 ... foo.foo()
686 ...
687 'foo'
688 >>> mock_foo.assert_called_once_with(foo)
689
Georg Brandl7ad3df62014-10-31 07:59:37 +0100690If we don't use ``autospec=True`` then the unbound method is patched out
691with a Mock instance instead, and isn't called with ``self``.
Michael Foord944e02d2012-03-25 23:12:55 +0100692
693
694Checking multiple calls with mock
Georg Brandl7fc972a2013-02-03 14:00:04 +0100695~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100696
697mock has a nice API for making assertions about how your mock objects are used.
698
699 >>> mock = Mock()
700 >>> mock.foo_bar.return_value = None
701 >>> mock.foo_bar('baz', spam='eggs')
702 >>> mock.foo_bar.assert_called_with('baz', spam='eggs')
703
704If your mock is only being called once you can use the
705:meth:`assert_called_once_with` method that also asserts that the
706:attr:`call_count` is one.
707
708 >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
709 >>> mock.foo_bar()
710 >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
711 Traceback (most recent call last):
712 ...
713 AssertionError: Expected to be called once. Called 2 times.
714
Georg Brandl7ad3df62014-10-31 07:59:37 +0100715Both ``assert_called_with`` and ``assert_called_once_with`` make assertions about
Michael Foord944e02d2012-03-25 23:12:55 +0100716the *most recent* call. If your mock is going to be called several times, and
717you want to make assertions about *all* those calls you can use
718:attr:`~Mock.call_args_list`:
719
720 >>> mock = Mock(return_value=None)
721 >>> mock(1, 2, 3)
722 >>> mock(4, 5, 6)
723 >>> mock()
724 >>> mock.call_args_list
725 [call(1, 2, 3), call(4, 5, 6), call()]
726
727The :data:`call` helper makes it easy to make assertions about these calls. You
Georg Brandl7ad3df62014-10-31 07:59:37 +0100728can build up a list of expected calls and compare it to ``call_args_list``. This
729looks remarkably similar to the repr of the ``call_args_list``:
Michael Foord944e02d2012-03-25 23:12:55 +0100730
731 >>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
732 >>> mock.call_args_list == expected
733 True
734
735
736Coping with mutable arguments
Georg Brandl7fc972a2013-02-03 14:00:04 +0100737~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100738
739Another situation is rare, but can bite you, is when your mock is called with
Georg Brandl7ad3df62014-10-31 07:59:37 +0100740mutable arguments. ``call_args`` and ``call_args_list`` store *references* to the
Michael Foord944e02d2012-03-25 23:12:55 +0100741arguments. If the arguments are mutated by the code under test then you can no
742longer make assertions about what the values were when the mock was called.
743
744Here's some example code that shows the problem. Imagine the following functions
745defined in 'mymodule'::
746
747 def frob(val):
748 pass
749
750 def grob(val):
751 "First frob and then clear val"
752 frob(val)
753 val.clear()
754
Georg Brandl7ad3df62014-10-31 07:59:37 +0100755When we try to test that ``grob`` calls ``frob`` with the correct argument look
Michael Foord944e02d2012-03-25 23:12:55 +0100756what happens:
757
758 >>> with patch('mymodule.frob') as mock_frob:
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200759 ... val = {6}
Michael Foord944e02d2012-03-25 23:12:55 +0100760 ... mymodule.grob(val)
761 ...
762 >>> val
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200763 set()
764 >>> mock_frob.assert_called_with({6})
Michael Foord944e02d2012-03-25 23:12:55 +0100765 Traceback (most recent call last):
766 ...
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200767 AssertionError: Expected: (({6},), {})
768 Called with: ((set(),), {})
Michael Foord944e02d2012-03-25 23:12:55 +0100769
770One possibility would be for mock to copy the arguments you pass in. This
771could then cause problems if you do assertions that rely on object identity
772for equality.
773
774Here's one solution that uses the :attr:`side_effect`
Georg Brandl7ad3df62014-10-31 07:59:37 +0100775functionality. If you provide a ``side_effect`` function for a mock then
776``side_effect`` will be called with the same args as the mock. This gives us an
Michael Foord944e02d2012-03-25 23:12:55 +0100777opportunity to copy the arguments and store them for later assertions. In this
778example I'm using *another* mock to store the arguments so that I can use the
779mock methods for doing the assertion. Again a helper function sets this up for
780me.
781
782 >>> from copy import deepcopy
783 >>> from unittest.mock import Mock, patch, DEFAULT
784 >>> def copy_call_args(mock):
785 ... new_mock = Mock()
786 ... def side_effect(*args, **kwargs):
787 ... args = deepcopy(args)
788 ... kwargs = deepcopy(kwargs)
789 ... new_mock(*args, **kwargs)
790 ... return DEFAULT
791 ... mock.side_effect = side_effect
792 ... return new_mock
793 ...
794 >>> with patch('mymodule.frob') as mock_frob:
795 ... new_mock = copy_call_args(mock_frob)
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200796 ... val = {6}
Michael Foord944e02d2012-03-25 23:12:55 +0100797 ... mymodule.grob(val)
798 ...
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200799 >>> new_mock.assert_called_with({6})
Michael Foord944e02d2012-03-25 23:12:55 +0100800 >>> new_mock.call_args
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200801 call({6})
Michael Foord944e02d2012-03-25 23:12:55 +0100802
Georg Brandl7ad3df62014-10-31 07:59:37 +0100803``copy_call_args`` is called with the mock that will be called. It returns a new
804mock that we do the assertion on. The ``side_effect`` function makes a copy of
805the args and calls our ``new_mock`` with the copy.
Michael Foord944e02d2012-03-25 23:12:55 +0100806
807.. note::
808
809 If your mock is only going to be used once there is an easier way of
810 checking arguments at the point they are called. You can simply do the
Georg Brandl7ad3df62014-10-31 07:59:37 +0100811 checking inside a ``side_effect`` function.
Michael Foord944e02d2012-03-25 23:12:55 +0100812
813 >>> def side_effect(arg):
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200814 ... assert arg == {6}
Michael Foord944e02d2012-03-25 23:12:55 +0100815 ...
816 >>> mock = Mock(side_effect=side_effect)
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200817 >>> mock({6})
Michael Foord944e02d2012-03-25 23:12:55 +0100818 >>> mock(set())
819 Traceback (most recent call last):
820 ...
821 AssertionError
822
Georg Brandl7ad3df62014-10-31 07:59:37 +0100823An alternative approach is to create a subclass of :class:`Mock` or
824:class:`MagicMock` that copies (using :func:`copy.deepcopy`) the arguments.
Michael Foord944e02d2012-03-25 23:12:55 +0100825Here's an example implementation:
826
827 >>> from copy import deepcopy
828 >>> class CopyingMock(MagicMock):
829 ... def __call__(self, *args, **kwargs):
830 ... args = deepcopy(args)
831 ... kwargs = deepcopy(kwargs)
832 ... return super(CopyingMock, self).__call__(*args, **kwargs)
833 ...
834 >>> c = CopyingMock(return_value=None)
835 >>> arg = set()
836 >>> c(arg)
837 >>> arg.add(1)
838 >>> c.assert_called_with(set())
839 >>> c.assert_called_with(arg)
840 Traceback (most recent call last):
841 ...
Serhiy Storchakac02d1882014-12-11 10:28:14 +0200842 AssertionError: Expected call: mock({1})
843 Actual call: mock(set())
Michael Foord944e02d2012-03-25 23:12:55 +0100844 >>> c.foo
845 <CopyingMock name='mock.foo' id='...'>
846
Georg Brandl7ad3df62014-10-31 07:59:37 +0100847When you subclass ``Mock`` or ``MagicMock`` all dynamically created attributes,
848and the ``return_value`` will use your subclass automatically. That means all
849children of a ``CopyingMock`` will also have the type ``CopyingMock``.
Michael Foord944e02d2012-03-25 23:12:55 +0100850
851
Michael Foord944e02d2012-03-25 23:12:55 +0100852Nesting Patches
Georg Brandl7fc972a2013-02-03 14:00:04 +0100853~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100854
855Using patch as a context manager is nice, but if you do multiple patches you
856can end up with nested with statements indenting further and further to the
857right:
858
859 >>> class MyTest(TestCase):
860 ...
861 ... def test_foo(self):
862 ... with patch('mymodule.Foo') as mock_foo:
863 ... with patch('mymodule.Bar') as mock_bar:
864 ... with patch('mymodule.Spam') as mock_spam:
865 ... assert mymodule.Foo is mock_foo
866 ... assert mymodule.Bar is mock_bar
867 ... assert mymodule.Spam is mock_spam
868 ...
869 >>> original = mymodule.Foo
870 >>> MyTest('test_foo').test_foo()
871 >>> assert mymodule.Foo is original
872
Georg Brandl7ad3df62014-10-31 07:59:37 +0100873With unittest ``cleanup`` functions and the :ref:`start-and-stop` we can
Michael Foord944e02d2012-03-25 23:12:55 +0100874achieve the same effect without the nested indentation. A simple helper
Georg Brandl7ad3df62014-10-31 07:59:37 +0100875method, ``create_patch``, puts the patch in place and returns the created mock
Michael Foord944e02d2012-03-25 23:12:55 +0100876for us:
877
878 >>> class MyTest(TestCase):
879 ...
880 ... def create_patch(self, name):
881 ... patcher = patch(name)
882 ... thing = patcher.start()
883 ... self.addCleanup(patcher.stop)
884 ... return thing
885 ...
886 ... def test_foo(self):
887 ... mock_foo = self.create_patch('mymodule.Foo')
888 ... mock_bar = self.create_patch('mymodule.Bar')
889 ... mock_spam = self.create_patch('mymodule.Spam')
890 ...
891 ... assert mymodule.Foo is mock_foo
892 ... assert mymodule.Bar is mock_bar
893 ... assert mymodule.Spam is mock_spam
894 ...
895 >>> original = mymodule.Foo
896 >>> MyTest('test_foo').run()
897 >>> assert mymodule.Foo is original
898
899
900Mocking a dictionary with MagicMock
Georg Brandl7fc972a2013-02-03 14:00:04 +0100901~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100902
903You may want to mock a dictionary, or other container object, recording all
904access to it whilst having it still behave like a dictionary.
905
906We can do this with :class:`MagicMock`, which will behave like a dictionary,
907and using :data:`~Mock.side_effect` to delegate dictionary access to a real
908underlying dictionary that is under our control.
909
Georg Brandl7ad3df62014-10-31 07:59:37 +0100910When the :meth:`__getitem__` and :meth:`__setitem__` methods of our ``MagicMock`` are called
911(normal dictionary access) then ``side_effect`` is called with the key (and in
912the case of ``__setitem__`` the value too). We can also control what is returned.
Michael Foord944e02d2012-03-25 23:12:55 +0100913
Georg Brandl7ad3df62014-10-31 07:59:37 +0100914After the ``MagicMock`` has been used we can use attributes like
Michael Foord944e02d2012-03-25 23:12:55 +0100915:data:`~Mock.call_args_list` to assert about how the dictionary was used:
916
917 >>> my_dict = {'a': 1, 'b': 2, 'c': 3}
918 >>> def getitem(name):
919 ... return my_dict[name]
920 ...
921 >>> def setitem(name, val):
922 ... my_dict[name] = val
923 ...
924 >>> mock = MagicMock()
925 >>> mock.__getitem__.side_effect = getitem
926 >>> mock.__setitem__.side_effect = setitem
927
928.. note::
929
Georg Brandl7ad3df62014-10-31 07:59:37 +0100930 An alternative to using ``MagicMock`` is to use ``Mock`` and *only* provide
Michael Foord944e02d2012-03-25 23:12:55 +0100931 the magic methods you specifically want:
932
933 >>> mock = Mock()
Éric Araujo0b1be1a2014-03-17 16:48:13 -0400934 >>> mock.__getitem__ = Mock(side_effect=getitem)
935 >>> mock.__setitem__ = Mock(side_effect=setitem)
Michael Foord944e02d2012-03-25 23:12:55 +0100936
Georg Brandl7ad3df62014-10-31 07:59:37 +0100937 A *third* option is to use ``MagicMock`` but passing in ``dict`` as the *spec*
938 (or *spec_set*) argument so that the ``MagicMock`` created only has
Michael Foord944e02d2012-03-25 23:12:55 +0100939 dictionary magic methods available:
940
941 >>> mock = MagicMock(spec_set=dict)
942 >>> mock.__getitem__.side_effect = getitem
943 >>> mock.__setitem__.side_effect = setitem
944
Georg Brandl7ad3df62014-10-31 07:59:37 +0100945With these side effect functions in place, the ``mock`` will behave like a normal
946dictionary but recording the access. It even raises a :exc:`KeyError` if you try
Michael Foord944e02d2012-03-25 23:12:55 +0100947to access a key that doesn't exist.
948
949 >>> mock['a']
950 1
951 >>> mock['c']
952 3
953 >>> mock['d']
954 Traceback (most recent call last):
955 ...
956 KeyError: 'd'
957 >>> mock['b'] = 'fish'
958 >>> mock['d'] = 'eggs'
959 >>> mock['b']
960 'fish'
961 >>> mock['d']
962 'eggs'
963
964After it has been used you can make assertions about the access using the normal
965mock methods and attributes:
966
967 >>> mock.__getitem__.call_args_list
968 [call('a'), call('c'), call('d'), call('b'), call('d')]
969 >>> mock.__setitem__.call_args_list
970 [call('b', 'fish'), call('d', 'eggs')]
971 >>> my_dict
972 {'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'}
973
974
975Mock subclasses and their attributes
Georg Brandl7fc972a2013-02-03 14:00:04 +0100976~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +0100977
Georg Brandl7ad3df62014-10-31 07:59:37 +0100978There are various reasons why you might want to subclass :class:`Mock`. One
979reason might be to add helper methods. Here's a silly example:
Michael Foord944e02d2012-03-25 23:12:55 +0100980
981 >>> class MyMock(MagicMock):
982 ... def has_been_called(self):
983 ... return self.called
984 ...
985 >>> mymock = MyMock(return_value=None)
986 >>> mymock
987 <MyMock id='...'>
988 >>> mymock.has_been_called()
989 False
990 >>> mymock()
991 >>> mymock.has_been_called()
992 True
993
Georg Brandl7ad3df62014-10-31 07:59:37 +0100994The standard behaviour for ``Mock`` instances is that attributes and the return
Michael Foord944e02d2012-03-25 23:12:55 +0100995value mocks are of the same type as the mock they are accessed on. This ensures
Georg Brandl7ad3df62014-10-31 07:59:37 +0100996that ``Mock`` attributes are ``Mocks`` and ``MagicMock`` attributes are ``MagicMocks``
Michael Foord944e02d2012-03-25 23:12:55 +0100997[#]_. So if you're subclassing to add helper methods then they'll also be
998available on the attributes and return value mock of instances of your
999subclass.
1000
1001 >>> mymock.foo
1002 <MyMock name='mock.foo' id='...'>
1003 >>> mymock.foo.has_been_called()
1004 False
1005 >>> mymock.foo()
1006 <MyMock name='mock.foo()' id='...'>
1007 >>> mymock.foo.has_been_called()
1008 True
1009
1010Sometimes this is inconvenient. For example, `one user
1011<https://code.google.com/p/mock/issues/detail?id=105>`_ is subclassing mock to
1012created a `Twisted adaptor
1013<http://twistedmatrix.com/documents/11.0.0/api/twisted.python.components.html>`_.
1014Having this applied to attributes too actually causes errors.
1015
Georg Brandl7ad3df62014-10-31 07:59:37 +01001016``Mock`` (in all its flavours) uses a method called ``_get_child_mock`` to create
Michael Foord944e02d2012-03-25 23:12:55 +01001017these "sub-mocks" for attributes and return values. You can prevent your
1018subclass being used for attributes by overriding this method. The signature is
Georg Brandl7ad3df62014-10-31 07:59:37 +01001019that it takes arbitrary keyword arguments (``**kwargs``) which are then passed
Michael Foord944e02d2012-03-25 23:12:55 +01001020onto the mock constructor:
1021
1022 >>> class Subclass(MagicMock):
1023 ... def _get_child_mock(self, **kwargs):
1024 ... return MagicMock(**kwargs)
1025 ...
1026 >>> mymock = Subclass()
1027 >>> mymock.foo
1028 <MagicMock name='mock.foo' id='...'>
1029 >>> assert isinstance(mymock, Subclass)
1030 >>> assert not isinstance(mymock.foo, Subclass)
1031 >>> assert not isinstance(mymock(), Subclass)
1032
1033.. [#] An exception to this rule are the non-callable mocks. Attributes use the
1034 callable variant because otherwise non-callable mocks couldn't have callable
1035 methods.
1036
1037
1038Mocking imports with patch.dict
Georg Brandl7fc972a2013-02-03 14:00:04 +01001039~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +01001040
1041One situation where mocking can be hard is where you have a local import inside
1042a function. These are harder to mock because they aren't using an object from
1043the module namespace that we can patch out.
1044
1045Generally local imports are to be avoided. They are sometimes done to prevent
1046circular dependencies, for which there is *usually* a much better way to solve
1047the problem (refactor the code) or to prevent "up front costs" by delaying the
1048import. This can also be solved in better ways than an unconditional local
1049import (store the module as a class or module attribute and only do the import
1050on first use).
1051
Georg Brandl7ad3df62014-10-31 07:59:37 +01001052That aside there is a way to use ``mock`` to affect the results of an import.
1053Importing fetches an *object* from the :data:`sys.modules` dictionary. Note that it
Michael Foord944e02d2012-03-25 23:12:55 +01001054fetches an *object*, which need not be a module. Importing a module for the
1055first time results in a module object being put in `sys.modules`, so usually
1056when you import something you get a module back. This need not be the case
1057however.
1058
1059This means you can use :func:`patch.dict` to *temporarily* put a mock in place
Georg Brandl7ad3df62014-10-31 07:59:37 +01001060in :data:`sys.modules`. Any imports whilst this patch is active will fetch the mock.
Michael Foord944e02d2012-03-25 23:12:55 +01001061When the patch is complete (the decorated function exits, the with statement
Georg Brandl7ad3df62014-10-31 07:59:37 +01001062body is complete or ``patcher.stop()`` is called) then whatever was there
Michael Foord944e02d2012-03-25 23:12:55 +01001063previously will be restored safely.
1064
1065Here's an example that mocks out the 'fooble' module.
1066
1067 >>> mock = Mock()
1068 >>> with patch.dict('sys.modules', {'fooble': mock}):
1069 ... import fooble
1070 ... fooble.blob()
1071 ...
1072 <Mock name='mock.blob()' id='...'>
1073 >>> assert 'fooble' not in sys.modules
1074 >>> mock.blob.assert_called_once_with()
1075
Georg Brandl7ad3df62014-10-31 07:59:37 +01001076As you can see the ``import fooble`` succeeds, but on exit there is no 'fooble'
1077left in :data:`sys.modules`.
Michael Foord944e02d2012-03-25 23:12:55 +01001078
Georg Brandl7ad3df62014-10-31 07:59:37 +01001079This also works for the ``from module import name`` form:
Michael Foord944e02d2012-03-25 23:12:55 +01001080
1081 >>> mock = Mock()
1082 >>> with patch.dict('sys.modules', {'fooble': mock}):
1083 ... from fooble import blob
1084 ... blob.blip()
1085 ...
1086 <Mock name='mock.blob.blip()' id='...'>
1087 >>> mock.blob.blip.assert_called_once_with()
1088
1089With slightly more work you can also mock package imports:
1090
1091 >>> mock = Mock()
1092 >>> modules = {'package': mock, 'package.module': mock.module}
1093 >>> with patch.dict('sys.modules', modules):
1094 ... from package.module import fooble
1095 ... fooble()
1096 ...
1097 <Mock name='mock.module.fooble()' id='...'>
1098 >>> mock.module.fooble.assert_called_once_with()
1099
1100
1101Tracking order of calls and less verbose call assertions
Georg Brandl7fc972a2013-02-03 14:00:04 +01001102~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +01001103
1104The :class:`Mock` class allows you to track the *order* of method calls on
1105your mock objects through the :attr:`~Mock.method_calls` attribute. This
1106doesn't allow you to track the order of calls between separate mock objects,
1107however we can use :attr:`~Mock.mock_calls` to achieve the same effect.
1108
Georg Brandl7ad3df62014-10-31 07:59:37 +01001109Because mocks track calls to child mocks in ``mock_calls``, and accessing an
Michael Foord944e02d2012-03-25 23:12:55 +01001110arbitrary attribute of a mock creates a child mock, we can create our separate
1111mocks from a parent one. Calls to those child mock will then all be recorded,
Georg Brandl7ad3df62014-10-31 07:59:37 +01001112in order, in the ``mock_calls`` of the parent:
Michael Foord944e02d2012-03-25 23:12:55 +01001113
1114 >>> manager = Mock()
1115 >>> mock_foo = manager.foo
1116 >>> mock_bar = manager.bar
1117
1118 >>> mock_foo.something()
1119 <Mock name='mock.foo.something()' id='...'>
1120 >>> mock_bar.other.thing()
1121 <Mock name='mock.bar.other.thing()' id='...'>
1122
1123 >>> manager.mock_calls
1124 [call.foo.something(), call.bar.other.thing()]
1125
1126We can then assert about the calls, including the order, by comparing with
Georg Brandl7ad3df62014-10-31 07:59:37 +01001127the ``mock_calls`` attribute on the manager mock:
Michael Foord944e02d2012-03-25 23:12:55 +01001128
1129 >>> expected_calls = [call.foo.something(), call.bar.other.thing()]
1130 >>> manager.mock_calls == expected_calls
1131 True
1132
Georg Brandl7ad3df62014-10-31 07:59:37 +01001133If ``patch`` is creating, and putting in place, your mocks then you can attach
Michael Foord944e02d2012-03-25 23:12:55 +01001134them to a manager mock using the :meth:`~Mock.attach_mock` method. After
Georg Brandl7ad3df62014-10-31 07:59:37 +01001135attaching calls will be recorded in ``mock_calls`` of the manager.
Michael Foord944e02d2012-03-25 23:12:55 +01001136
1137 >>> manager = MagicMock()
1138 >>> with patch('mymodule.Class1') as MockClass1:
1139 ... with patch('mymodule.Class2') as MockClass2:
1140 ... manager.attach_mock(MockClass1, 'MockClass1')
1141 ... manager.attach_mock(MockClass2, 'MockClass2')
1142 ... MockClass1().foo()
1143 ... MockClass2().bar()
1144 ...
1145 <MagicMock name='mock.MockClass1().foo()' id='...'>
1146 <MagicMock name='mock.MockClass2().bar()' id='...'>
1147 >>> manager.mock_calls
1148 [call.MockClass1(),
1149 call.MockClass1().foo(),
1150 call.MockClass2(),
1151 call.MockClass2().bar()]
1152
1153If many calls have been made, but you're only interested in a particular
1154sequence of them then an alternative is to use the
1155:meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed
1156with the :data:`call` object). If that sequence of calls are in
1157:attr:`~Mock.mock_calls` then the assert succeeds.
1158
1159 >>> m = MagicMock()
1160 >>> m().foo().bar().baz()
1161 <MagicMock name='mock().foo().bar().baz()' id='...'>
1162 >>> m.one().two().three()
1163 <MagicMock name='mock.one().two().three()' id='...'>
1164 >>> calls = call.one().two().three().call_list()
1165 >>> m.assert_has_calls(calls)
1166
Georg Brandl7ad3df62014-10-31 07:59:37 +01001167Even though the chained call ``m.one().two().three()`` aren't the only calls that
Michael Foord944e02d2012-03-25 23:12:55 +01001168have been made to the mock, the assert still succeeds.
1169
1170Sometimes a mock may have several calls made to it, and you are only interested
1171in asserting about *some* of those calls. You may not even care about the
Georg Brandl7ad3df62014-10-31 07:59:37 +01001172order. In this case you can pass ``any_order=True`` to ``assert_has_calls``:
Michael Foord944e02d2012-03-25 23:12:55 +01001173
1174 >>> m = MagicMock()
1175 >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50')
1176 (...)
1177 >>> calls = [call.fifty('50'), call(1), call.seven(7)]
1178 >>> m.assert_has_calls(calls, any_order=True)
1179
1180
1181More complex argument matching
Georg Brandl7fc972a2013-02-03 14:00:04 +01001182~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Michael Foord944e02d2012-03-25 23:12:55 +01001183
1184Using the same basic concept as :data:`ANY` we can implement matchers to do more
1185complex assertions on objects used as arguments to mocks.
1186
1187Suppose we expect some object to be passed to a mock that by default
1188compares equal based on object identity (which is the Python default for user
1189defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass
1190in the exact same object. If we are only interested in some of the attributes
1191of this object then we can create a matcher that will check these attributes
1192for us.
1193
Georg Brandl7ad3df62014-10-31 07:59:37 +01001194You can see in this example how a 'standard' call to ``assert_called_with`` isn't
Michael Foord944e02d2012-03-25 23:12:55 +01001195sufficient:
1196
Ezio Melottic9cfcf12013-03-11 09:42:40 +02001197 >>> class Foo:
Michael Foord944e02d2012-03-25 23:12:55 +01001198 ... def __init__(self, a, b):
1199 ... self.a, self.b = a, b
1200 ...
1201 >>> mock = Mock(return_value=None)
1202 >>> mock(Foo(1, 2))
1203 >>> mock.assert_called_with(Foo(1, 2))
1204 Traceback (most recent call last):
1205 ...
1206 AssertionError: Expected: call(<__main__.Foo object at 0x...>)
1207 Actual call: call(<__main__.Foo object at 0x...>)
1208
Georg Brandl7ad3df62014-10-31 07:59:37 +01001209A comparison function for our ``Foo`` class might look something like this:
Michael Foord944e02d2012-03-25 23:12:55 +01001210
1211 >>> def compare(self, other):
1212 ... if not type(self) == type(other):
1213 ... return False
1214 ... if self.a != other.a:
1215 ... return False
1216 ... if self.b != other.b:
1217 ... return False
1218 ... return True
1219 ...
1220
1221And a matcher object that can use comparison functions like this for its
1222equality operation would look something like this:
1223
Ezio Melottic9cfcf12013-03-11 09:42:40 +02001224 >>> class Matcher:
Michael Foord944e02d2012-03-25 23:12:55 +01001225 ... def __init__(self, compare, some_obj):
1226 ... self.compare = compare
1227 ... self.some_obj = some_obj
1228 ... def __eq__(self, other):
1229 ... return self.compare(self.some_obj, other)
1230 ...
1231
1232Putting all this together:
1233
1234 >>> match_foo = Matcher(compare, Foo(1, 2))
1235 >>> mock.assert_called_with(match_foo)
1236
Georg Brandl7ad3df62014-10-31 07:59:37 +01001237The ``Matcher`` is instantiated with our compare function and the ``Foo`` object
1238we want to compare against. In ``assert_called_with`` the ``Matcher`` equality
Michael Foord944e02d2012-03-25 23:12:55 +01001239method will be called, which compares the object the mock was called with
1240against the one we created our matcher with. If they match then
Georg Brandl7ad3df62014-10-31 07:59:37 +01001241``assert_called_with`` passes, and if they don't an :exc:`AssertionError` is raised:
Michael Foord944e02d2012-03-25 23:12:55 +01001242
1243 >>> match_wrong = Matcher(compare, Foo(3, 4))
1244 >>> mock.assert_called_with(match_wrong)
1245 Traceback (most recent call last):
1246 ...
1247 AssertionError: Expected: ((<Matcher object at 0x...>,), {})
1248 Called with: ((<Foo object at 0x...>,), {})
1249
1250With a bit of tweaking you could have the comparison function raise the
Georg Brandl7ad3df62014-10-31 07:59:37 +01001251:exc:`AssertionError` directly and provide a more useful failure message.
Michael Foord944e02d2012-03-25 23:12:55 +01001252
1253As of version 1.5, the Python testing library `PyHamcrest
Georg Brandle73778c2014-10-29 08:36:35 +01001254<https://pypi.python.org/pypi/PyHamcrest>`_ provides similar functionality,
Michael Foord944e02d2012-03-25 23:12:55 +01001255that may be useful here, in the form of its equality matcher
1256(`hamcrest.library.integration.match_equality
Georg Brandl525d3552014-10-29 10:26:56 +01001257<http://pythonhosted.org/PyHamcrest/integration.html#hamcrest.library.integration.match_equality.match_equality>`_).