blob: 8e1e88a147c099e3c0bd3d84b6ae10e05f4dc1fd [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
31Once our mock has been used (`real.method` in this example) it has methods
32and 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
37 are interchangeable. As the `MagicMock` is the more capable class it makes
38 a sensible one to use by default.
39
40Once the mock has been called its :attr:`~Mock.called` attribute is set to
41`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
45This example tests that calling `ProductionClass().method` results in a call to
46the `something` method:
47
48 >>> class ProductionClass(object):
49 ... 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
69The simple `ProductionClass` below has a `closer` method. If it is called with
70an object then it calls `close` on it.
71
72 >>> class ProductionClass(object):
73 ... def closer(self, something):
74 ... something.close()
75 ...
76
77So to test it we need to pass in an object with a `close` method and check
78that 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
99In the example below we have a function `some_function` that instantiates `Foo`
100and calls a method on it. The call to `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
144If you make an assertion about `mock_calls` and any unexpected methods
145have 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
150`mock_calls`:
151
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
188`mock.connection.cursor().execute("SELECT 1")`. If we wanted this call to
189return 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
205It is the call to `.call_list()` that turns our call object into a list of
206calls 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
226`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
228times, and you want each call to return a different value. When you set
229`side_effect` to an iterable every call to the mock returns the next value
230from 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
242depending on what the mock is called with, `side_effect` can be a function.
243The 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
262class 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
265your tests will continue to pass even though your code is now broken!
266
267`Mock` allows you to provide an object as a specification for the mock,
268using the `spec` keyword argument. Accessing methods / attributes on the
269mock 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
280If you want a stronger form of specification that prevents the setting
281of arbitrary attributes as well as the getting of them then you can use
282`spec_set` instead of `spec`.
283
284
285
286Patch Decorators
287----------------
288
289.. note::
290
291 With `patch` it matters that you patch objects in the namespace where they
292 are looked up. This is normally straightforward, but for a quick guide
293 read :ref:`where to patch <where-to-patch>`.
294
295
296A common need in tests is to patch a class attribute or a module attribute,
297for example patching a builtin or patching a class in a module to test that it
298is instantiated. Modules and classes are effectively global, so patching on
299them has to be undone after the test or the patch will persist into other
300tests and cause hard to diagnose problems.
301
302mock provides three convenient decorators for this: `patch`, `patch.object` and
303`patch.dict`. `patch` takes a single string, of the form
304`package.module.Class.attribute` to specify the attribute you are patching. It
305also optionally takes a value that you want the attribute (or class or
306whatever) to be replaced with. 'patch.object' takes an object and the name of
307the attribute you would like patched, plus optionally the value to patch it
308with.
309
310`patch.object`:
311
312 >>> original = SomeClass.attribute
313 >>> @patch.object(SomeClass, 'attribute', sentinel.attribute)
314 ... def test():
315 ... assert SomeClass.attribute == sentinel.attribute
316 ...
317 >>> test()
318 >>> assert SomeClass.attribute == original
319
320 >>> @patch('package.module.attribute', sentinel.attribute)
321 ... def test():
322 ... from package.module import attribute
323 ... assert attribute is sentinel.attribute
324 ...
325 >>> test()
326
327If you are patching a module (including `__builtin__`) then use `patch`
328instead of `patch.object`:
329
330 >>> mock = MagicMock(return_value = sentinel.file_handle)
331 >>> with patch('__builtin__.open', mock):
332 ... handle = open('filename', 'r')
333 ...
334 >>> mock.assert_called_with('filename', 'r')
335 >>> assert handle == sentinel.file_handle, "incorrect file handle returned"
336
337The module name can be 'dotted', in the form `package.module` if needed:
338
339 >>> @patch('package.module.ClassName.attribute', sentinel.attribute)
340 ... def test():
341 ... from package.module import ClassName
342 ... assert ClassName.attribute == sentinel.attribute
343 ...
344 >>> test()
345
346A nice pattern is to actually decorate test methods themselves:
347
348 >>> class MyTest(unittest2.TestCase):
349 ... @patch.object(SomeClass, 'attribute', sentinel.attribute)
350 ... def test_something(self):
351 ... self.assertEqual(SomeClass.attribute, sentinel.attribute)
352 ...
353 >>> original = SomeClass.attribute
354 >>> MyTest('test_something').test_something()
355 >>> assert SomeClass.attribute == original
356
357If you want to patch with a Mock, you can use `patch` with only one argument
358(or `patch.object` with two arguments). The mock will be created for you and
359passed into the test function / method:
360
361 >>> class MyTest(unittest2.TestCase):
362 ... @patch.object(SomeClass, 'static_method')
363 ... def test_something(self, mock_method):
364 ... SomeClass.static_method()
365 ... mock_method.assert_called_with()
366 ...
367 >>> MyTest('test_something').test_something()
368
369You can stack up multiple patch decorators using this pattern:
370
371 >>> class MyTest(unittest2.TestCase):
372 ... @patch('package.module.ClassName1')
373 ... @patch('package.module.ClassName2')
374 ... def test_something(self, MockClass2, MockClass1):
375 ... self.assertTrue(package.module.ClassName1 is MockClass1)
376 ... self.assertTrue(package.module.ClassName2 is MockClass2)
377 ...
378 >>> MyTest('test_something').test_something()
379
380When you nest patch decorators the mocks are passed in to the decorated
381function in the same order they applied (the normal *python* order that
382decorators are applied). This means from the bottom up, so in the example
383above the mock for `test_module.ClassName2` is passed in first.
384
385There is also :func:`patch.dict` for setting values in a dictionary just
386during a scope and restoring the dictionary to its original state when the test
387ends:
388
389 >>> foo = {'key': 'value'}
390 >>> original = foo.copy()
391 >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
392 ... assert foo == {'newkey': 'newvalue'}
393 ...
394 >>> assert foo == original
395
396`patch`, `patch.object` and `patch.dict` can all be used as context managers.
397
398Where you use `patch` to create a mock for you, you can get a reference to the
399mock using the "as" form of the with statement:
400
401 >>> class ProductionClass(object):
402 ... def method(self):
403 ... pass
404 ...
405 >>> with patch.object(ProductionClass, 'method') as mock_method:
406 ... mock_method.return_value = None
407 ... real = ProductionClass()
408 ... real.method(1, 2, 3)
409 ...
410 >>> mock_method.assert_called_with(1, 2, 3)
411
412
413As an alternative `patch`, `patch.object` and `patch.dict` can be used as
414class decorators. When used in this way it is the same as applying the
415decorator indvidually to every method whose name starts with "test".
416
417
418.. _further-examples:
419
420Further Examples
421================
422
423
424Here are some more examples for some slightly more advanced scenarios.
Michael Foord944e02d2012-03-25 23:12:55 +0100425
426
427Mocking chained calls
428---------------------
429
430Mocking chained calls is actually straightforward with mock once you
431understand the :attr:`~Mock.return_value` attribute. When a mock is called for
432the first time, or you fetch its `return_value` before it has been called, a
433new `Mock` is created.
434
435This means that you can see how the object returned from a call to a mocked
436object has been used by interrogating the `return_value` mock:
437
438 >>> mock = Mock()
439 >>> mock().foo(a=2, b=3)
440 <Mock name='mock().foo()' id='...'>
441 >>> mock.return_value.foo.assert_called_with(a=2, b=3)
442
443From here it is a simple step to configure and then make assertions about
444chained calls. Of course another alternative is writing your code in a more
445testable way in the first place...
446
447So, suppose we have some code that looks a little bit like this:
448
449 >>> class Something(object):
450 ... def __init__(self):
451 ... self.backend = BackendProvider()
452 ... def method(self):
453 ... response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
454 ... # more code
455
456Assuming that `BackendProvider` is already well tested, how do we test
457`method()`? Specifically, we want to test that the code section `# more
458code` uses the response object in the correct way.
459
460As this chain of calls is made from an instance attribute we can monkey patch
461the `backend` attribute on a `Something` instance. In this particular case
462we are only interested in the return value from the final call to
463`start_call` so we don't have much configuration to do. Let's assume the
464object it returns is 'file-like', so we'll ensure that our response object
465uses the builtin `file` as its `spec`.
466
467To do this we create a mock instance as our mock backend and create a mock
468response object for it. To set the response as the return value for that final
469`start_call` we could do this:
470
471 `mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response`.
472
473We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock`
474method to directly set the return value for us:
475
476 >>> something = Something()
477 >>> mock_response = Mock(spec=file)
478 >>> mock_backend = Mock()
479 >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response}
480 >>> mock_backend.configure_mock(**config)
481
482With these we monkey patch the "mock backend" in place and can make the real
483call:
484
485 >>> something.backend = mock_backend
486 >>> something.method()
487
488Using :attr:`~Mock.mock_calls` we can check the chained call with a single
489assert. A chained call is several calls in one line of code, so there will be
490several entries in `mock_calls`. We can use :meth:`call.call_list` to create
491this list of calls for us:
492
493 >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
494 >>> call_list = chained.call_list()
495 >>> assert mock_backend.mock_calls == call_list
496
497
498Partial mocking
499---------------
500
501In some tests I wanted to mock out a call to `datetime.date.today()
502<http://docs.python.org/library/datetime.html#datetime.date.today>`_ to return
503a known date, but I didn't want to prevent the code under test from
504creating new date objects. Unfortunately `datetime.date` is written in C, and
505so I couldn't just monkey-patch out the static `date.today` method.
506
507I found a simple way of doing this that involved effectively wrapping the date
508class with a mock, but passing through calls to the constructor to the real
509class (and returning real instances).
510
511The :func:`patch decorator <patch>` is used here to
512mock out the `date` class in the module under test. The :attr:`side_effect`
513attribute on the mock date class is then set to a lambda function that returns
514a real date. When the mock date class is called a real date will be
515constructed and returned by `side_effect`.
516
517 >>> from datetime import date
518 >>> with patch('mymodule.date') as mock_date:
519 ... mock_date.today.return_value = date(2010, 10, 8)
520 ... mock_date.side_effect = lambda *args, **kw: date(*args, **kw)
521 ...
522 ... assert mymodule.date.today() == date(2010, 10, 8)
523 ... assert mymodule.date(2009, 6, 8) == date(2009, 6, 8)
524 ...
525
526Note that we don't patch `datetime.date` globally, we patch `date` in the
527module that *uses* it. See :ref:`where to patch <where-to-patch>`.
528
529When `date.today()` is called a known date is returned, but calls to the
530`date(...)` constructor still return normal dates. Without this you can find
531yourself having to calculate an expected result using exactly the same
532algorithm as the code under test, which is a classic testing anti-pattern.
533
534Calls to the date constructor are recorded in the `mock_date` attributes
535(`call_count` and friends) which may also be useful for your tests.
536
537An alternative way of dealing with mocking dates, or other builtin classes,
538is discussed in `this blog entry
539<http://williamjohnbert.com/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/>`_.
540
541
542Mocking a Generator Method
543--------------------------
544
545A Python generator is a function or method that uses the `yield statement
546<http://docs.python.org/reference/simple_stmts.html#the-yield-statement>`_ to
547return a series of values when iterated over [#]_.
548
549A generator method / function is called to return the generator object. It is
550the generator object that is then iterated over. The protocol method for
551iteration is `__iter__
552<http://docs.python.org/library/stdtypes.html#container.__iter__>`_, so we can
553mock this using a `MagicMock`.
554
555Here's an example class with an "iter" method implemented as a generator:
556
557 >>> class Foo(object):
558 ... def iter(self):
559 ... for i in [1, 2, 3]:
560 ... yield i
561 ...
562 >>> foo = Foo()
563 >>> list(foo.iter())
564 [1, 2, 3]
565
566
567How would we mock this class, and in particular its "iter" method?
568
569To configure the values returned from the iteration (implicit in the call to
570`list`), we need to configure the object returned by the call to `foo.iter()`.
571
572 >>> mock_foo = MagicMock()
573 >>> mock_foo.iter.return_value = iter([1, 2, 3])
574 >>> list(mock_foo.iter())
575 [1, 2, 3]
576
577.. [#] There are also generator expressions and more `advanced uses
578 <http://www.dabeaz.com/coroutines/index.html>`_ of generators, but we aren't
579 concerned about them here. A very good introduction to generators and how
580 powerful they are is: `Generator Tricks for Systems Programmers
581 <http://www.dabeaz.com/generators/>`_.
582
583
584Applying the same patch to every test method
585--------------------------------------------
586
587If you want several patches in place for multiple test methods the obvious way
588is to apply the patch decorators to every method. This can feel like unnecessary
589repetition. For Python 2.6 or more recent you can use `patch` (in all its
590various forms) as a class decorator. This applies the patches to all test
591methods on the class. A test method is identified by methods whose names start
592with `test`:
593
594 >>> @patch('mymodule.SomeClass')
595 ... class MyTest(TestCase):
596 ...
597 ... def test_one(self, MockSomeClass):
598 ... self.assertTrue(mymodule.SomeClass is MockSomeClass)
599 ...
600 ... def test_two(self, MockSomeClass):
601 ... self.assertTrue(mymodule.SomeClass is MockSomeClass)
602 ...
603 ... def not_a_test(self):
604 ... return 'something'
605 ...
606 >>> MyTest('test_one').test_one()
607 >>> MyTest('test_two').test_two()
608 >>> MyTest('test_two').not_a_test()
609 'something'
610
611An alternative way of managing patches is to use the :ref:`start-and-stop`.
612These allow you to move the patching into your `setUp` and `tearDown` methods.
613
614 >>> class MyTest(TestCase):
615 ... def setUp(self):
616 ... self.patcher = patch('mymodule.foo')
617 ... self.mock_foo = self.patcher.start()
618 ...
619 ... def test_foo(self):
620 ... self.assertTrue(mymodule.foo is self.mock_foo)
621 ...
622 ... def tearDown(self):
623 ... self.patcher.stop()
624 ...
625 >>> MyTest('test_foo').run()
626
627If you use this technique you must ensure that the patching is "undone" by
628calling `stop`. This can be fiddlier than you might think, because if an
629exception is raised in the setUp then tearDown is not called.
630:meth:`unittest.TestCase.addCleanup` makes this easier:
631
632 >>> class MyTest(TestCase):
633 ... def setUp(self):
634 ... patcher = patch('mymodule.foo')
635 ... self.addCleanup(patcher.stop)
636 ... self.mock_foo = patcher.start()
637 ...
638 ... def test_foo(self):
639 ... self.assertTrue(mymodule.foo is self.mock_foo)
640 ...
641 >>> MyTest('test_foo').run()
642
643
644Mocking Unbound Methods
645-----------------------
646
647Whilst writing tests today I needed to patch an *unbound method* (patching the
648method on the class rather than on the instance). I needed self to be passed
649in as the first argument because I want to make asserts about which objects
650were calling this particular method. The issue is that you can't patch with a
651mock for this, because if you replace an unbound method with a mock it doesn't
652become a bound method when fetched from the instance, and so it doesn't get
653self passed in. The workaround is to patch the unbound method with a real
654function instead. The :func:`patch` decorator makes it so simple to
655patch out methods with a mock that having to create a real function becomes a
656nuisance.
657
658If you pass `autospec=True` to patch then it does the patching with a
659*real* function object. This function object has the same signature as the one
660it is replacing, but delegates to a mock under the hood. You still get your
661mock auto-created in exactly the same way as before. What it means though, is
662that if you use it to patch out an unbound method on a class the mocked
663function will be turned into a bound method if it is fetched from an instance.
664It will have `self` passed in as the first argument, which is exactly what I
665wanted:
666
667 >>> class Foo(object):
668 ... def foo(self):
669 ... pass
670 ...
671 >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo:
672 ... mock_foo.return_value = 'foo'
673 ... foo = Foo()
674 ... foo.foo()
675 ...
676 'foo'
677 >>> mock_foo.assert_called_once_with(foo)
678
679If we don't use `autospec=True` then the unbound method is patched out
680with a Mock instance instead, and isn't called with `self`.
681
682
683Checking multiple calls with mock
684---------------------------------
685
686mock has a nice API for making assertions about how your mock objects are used.
687
688 >>> mock = Mock()
689 >>> mock.foo_bar.return_value = None
690 >>> mock.foo_bar('baz', spam='eggs')
691 >>> mock.foo_bar.assert_called_with('baz', spam='eggs')
692
693If your mock is only being called once you can use the
694:meth:`assert_called_once_with` method that also asserts that the
695:attr:`call_count` is one.
696
697 >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
698 >>> mock.foo_bar()
699 >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
700 Traceback (most recent call last):
701 ...
702 AssertionError: Expected to be called once. Called 2 times.
703
704Both `assert_called_with` and `assert_called_once_with` make assertions about
705the *most recent* call. If your mock is going to be called several times, and
706you want to make assertions about *all* those calls you can use
707:attr:`~Mock.call_args_list`:
708
709 >>> mock = Mock(return_value=None)
710 >>> mock(1, 2, 3)
711 >>> mock(4, 5, 6)
712 >>> mock()
713 >>> mock.call_args_list
714 [call(1, 2, 3), call(4, 5, 6), call()]
715
716The :data:`call` helper makes it easy to make assertions about these calls. You
717can build up a list of expected calls and compare it to `call_args_list`. This
718looks remarkably similar to the repr of the `call_args_list`:
719
720 >>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
721 >>> mock.call_args_list == expected
722 True
723
724
725Coping with mutable arguments
726-----------------------------
727
728Another situation is rare, but can bite you, is when your mock is called with
729mutable arguments. `call_args` and `call_args_list` store *references* to the
730arguments. If the arguments are mutated by the code under test then you can no
731longer make assertions about what the values were when the mock was called.
732
733Here's some example code that shows the problem. Imagine the following functions
734defined in 'mymodule'::
735
736 def frob(val):
737 pass
738
739 def grob(val):
740 "First frob and then clear val"
741 frob(val)
742 val.clear()
743
744When we try to test that `grob` calls `frob` with the correct argument look
745what happens:
746
747 >>> with patch('mymodule.frob') as mock_frob:
748 ... val = set([6])
749 ... mymodule.grob(val)
750 ...
751 >>> val
752 set([])
753 >>> mock_frob.assert_called_with(set([6]))
754 Traceback (most recent call last):
755 ...
756 AssertionError: Expected: ((set([6]),), {})
757 Called with: ((set([]),), {})
758
759One possibility would be for mock to copy the arguments you pass in. This
760could then cause problems if you do assertions that rely on object identity
761for equality.
762
763Here's one solution that uses the :attr:`side_effect`
764functionality. If you provide a `side_effect` function for a mock then
765`side_effect` will be called with the same args as the mock. This gives us an
766opportunity to copy the arguments and store them for later assertions. In this
767example I'm using *another* mock to store the arguments so that I can use the
768mock methods for doing the assertion. Again a helper function sets this up for
769me.
770
771 >>> from copy import deepcopy
772 >>> from unittest.mock import Mock, patch, DEFAULT
773 >>> def copy_call_args(mock):
774 ... new_mock = Mock()
775 ... def side_effect(*args, **kwargs):
776 ... args = deepcopy(args)
777 ... kwargs = deepcopy(kwargs)
778 ... new_mock(*args, **kwargs)
779 ... return DEFAULT
780 ... mock.side_effect = side_effect
781 ... return new_mock
782 ...
783 >>> with patch('mymodule.frob') as mock_frob:
784 ... new_mock = copy_call_args(mock_frob)
785 ... val = set([6])
786 ... mymodule.grob(val)
787 ...
788 >>> new_mock.assert_called_with(set([6]))
789 >>> new_mock.call_args
790 call(set([6]))
791
792`copy_call_args` is called with the mock that will be called. It returns a new
793mock that we do the assertion on. The `side_effect` function makes a copy of
794the args and calls our `new_mock` with the copy.
795
796.. note::
797
798 If your mock is only going to be used once there is an easier way of
799 checking arguments at the point they are called. You can simply do the
800 checking inside a `side_effect` function.
801
802 >>> def side_effect(arg):
803 ... assert arg == set([6])
804 ...
805 >>> mock = Mock(side_effect=side_effect)
806 >>> mock(set([6]))
807 >>> mock(set())
808 Traceback (most recent call last):
809 ...
810 AssertionError
811
812An alternative approach is to create a subclass of `Mock` or `MagicMock` that
813copies (using :func:`copy.deepcopy`) the arguments.
814Here's an example implementation:
815
816 >>> from copy import deepcopy
817 >>> class CopyingMock(MagicMock):
818 ... def __call__(self, *args, **kwargs):
819 ... args = deepcopy(args)
820 ... kwargs = deepcopy(kwargs)
821 ... return super(CopyingMock, self).__call__(*args, **kwargs)
822 ...
823 >>> c = CopyingMock(return_value=None)
824 >>> arg = set()
825 >>> c(arg)
826 >>> arg.add(1)
827 >>> c.assert_called_with(set())
828 >>> c.assert_called_with(arg)
829 Traceback (most recent call last):
830 ...
831 AssertionError: Expected call: mock(set([1]))
832 Actual call: mock(set([]))
833 >>> c.foo
834 <CopyingMock name='mock.foo' id='...'>
835
836When you subclass `Mock` or `MagicMock` all dynamically created attributes,
837and the `return_value` will use your subclass automatically. That means all
838children of a `CopyingMock` will also have the type `CopyingMock`.
839
840
Michael Foord944e02d2012-03-25 23:12:55 +0100841Nesting Patches
842---------------
843
844Using patch as a context manager is nice, but if you do multiple patches you
845can end up with nested with statements indenting further and further to the
846right:
847
848 >>> class MyTest(TestCase):
849 ...
850 ... def test_foo(self):
851 ... with patch('mymodule.Foo') as mock_foo:
852 ... with patch('mymodule.Bar') as mock_bar:
853 ... with patch('mymodule.Spam') as mock_spam:
854 ... assert mymodule.Foo is mock_foo
855 ... assert mymodule.Bar is mock_bar
856 ... assert mymodule.Spam is mock_spam
857 ...
858 >>> original = mymodule.Foo
859 >>> MyTest('test_foo').test_foo()
860 >>> assert mymodule.Foo is original
861
862With unittest `cleanup` functions and the :ref:`start-and-stop` we can
863achieve the same effect without the nested indentation. A simple helper
864method, `create_patch`, puts the patch in place and returns the created mock
865for us:
866
867 >>> class MyTest(TestCase):
868 ...
869 ... def create_patch(self, name):
870 ... patcher = patch(name)
871 ... thing = patcher.start()
872 ... self.addCleanup(patcher.stop)
873 ... return thing
874 ...
875 ... def test_foo(self):
876 ... mock_foo = self.create_patch('mymodule.Foo')
877 ... mock_bar = self.create_patch('mymodule.Bar')
878 ... mock_spam = self.create_patch('mymodule.Spam')
879 ...
880 ... assert mymodule.Foo is mock_foo
881 ... assert mymodule.Bar is mock_bar
882 ... assert mymodule.Spam is mock_spam
883 ...
884 >>> original = mymodule.Foo
885 >>> MyTest('test_foo').run()
886 >>> assert mymodule.Foo is original
887
888
889Mocking a dictionary with MagicMock
890-----------------------------------
891
892You may want to mock a dictionary, or other container object, recording all
893access to it whilst having it still behave like a dictionary.
894
895We can do this with :class:`MagicMock`, which will behave like a dictionary,
896and using :data:`~Mock.side_effect` to delegate dictionary access to a real
897underlying dictionary that is under our control.
898
899When the `__getitem__` and `__setitem__` methods of our `MagicMock` are called
900(normal dictionary access) then `side_effect` is called with the key (and in
901the case of `__setitem__` the value too). We can also control what is returned.
902
903After the `MagicMock` has been used we can use attributes like
904:data:`~Mock.call_args_list` to assert about how the dictionary was used:
905
906 >>> my_dict = {'a': 1, 'b': 2, 'c': 3}
907 >>> def getitem(name):
908 ... return my_dict[name]
909 ...
910 >>> def setitem(name, val):
911 ... my_dict[name] = val
912 ...
913 >>> mock = MagicMock()
914 >>> mock.__getitem__.side_effect = getitem
915 >>> mock.__setitem__.side_effect = setitem
916
917.. note::
918
919 An alternative to using `MagicMock` is to use `Mock` and *only* provide
920 the magic methods you specifically want:
921
922 >>> mock = Mock()
923 >>> mock.__setitem__ = Mock(side_effect=getitem)
924 >>> mock.__getitem__ = Mock(side_effect=setitem)
925
926 A *third* option is to use `MagicMock` but passing in `dict` as the `spec`
927 (or `spec_set`) argument so that the `MagicMock` created only has
928 dictionary magic methods available:
929
930 >>> mock = MagicMock(spec_set=dict)
931 >>> mock.__getitem__.side_effect = getitem
932 >>> mock.__setitem__.side_effect = setitem
933
934With these side effect functions in place, the `mock` will behave like a normal
935dictionary but recording the access. It even raises a `KeyError` if you try
936to access a key that doesn't exist.
937
938 >>> mock['a']
939 1
940 >>> mock['c']
941 3
942 >>> mock['d']
943 Traceback (most recent call last):
944 ...
945 KeyError: 'd'
946 >>> mock['b'] = 'fish'
947 >>> mock['d'] = 'eggs'
948 >>> mock['b']
949 'fish'
950 >>> mock['d']
951 'eggs'
952
953After it has been used you can make assertions about the access using the normal
954mock methods and attributes:
955
956 >>> mock.__getitem__.call_args_list
957 [call('a'), call('c'), call('d'), call('b'), call('d')]
958 >>> mock.__setitem__.call_args_list
959 [call('b', 'fish'), call('d', 'eggs')]
960 >>> my_dict
961 {'a': 1, 'c': 3, 'b': 'fish', 'd': 'eggs'}
962
963
964Mock subclasses and their attributes
965------------------------------------
966
967There are various reasons why you might want to subclass `Mock`. One reason
968might be to add helper methods. Here's a silly example:
969
970 >>> class MyMock(MagicMock):
971 ... def has_been_called(self):
972 ... return self.called
973 ...
974 >>> mymock = MyMock(return_value=None)
975 >>> mymock
976 <MyMock id='...'>
977 >>> mymock.has_been_called()
978 False
979 >>> mymock()
980 >>> mymock.has_been_called()
981 True
982
983The standard behaviour for `Mock` instances is that attributes and the return
984value mocks are of the same type as the mock they are accessed on. This ensures
985that `Mock` attributes are `Mocks` and `MagicMock` attributes are `MagicMocks`
986[#]_. So if you're subclassing to add helper methods then they'll also be
987available on the attributes and return value mock of instances of your
988subclass.
989
990 >>> mymock.foo
991 <MyMock name='mock.foo' id='...'>
992 >>> mymock.foo.has_been_called()
993 False
994 >>> mymock.foo()
995 <MyMock name='mock.foo()' id='...'>
996 >>> mymock.foo.has_been_called()
997 True
998
999Sometimes this is inconvenient. For example, `one user
1000<https://code.google.com/p/mock/issues/detail?id=105>`_ is subclassing mock to
1001created a `Twisted adaptor
1002<http://twistedmatrix.com/documents/11.0.0/api/twisted.python.components.html>`_.
1003Having this applied to attributes too actually causes errors.
1004
1005`Mock` (in all its flavours) uses a method called `_get_child_mock` to create
1006these "sub-mocks" for attributes and return values. You can prevent your
1007subclass being used for attributes by overriding this method. The signature is
1008that it takes arbitrary keyword arguments (`**kwargs`) which are then passed
1009onto the mock constructor:
1010
1011 >>> class Subclass(MagicMock):
1012 ... def _get_child_mock(self, **kwargs):
1013 ... return MagicMock(**kwargs)
1014 ...
1015 >>> mymock = Subclass()
1016 >>> mymock.foo
1017 <MagicMock name='mock.foo' id='...'>
1018 >>> assert isinstance(mymock, Subclass)
1019 >>> assert not isinstance(mymock.foo, Subclass)
1020 >>> assert not isinstance(mymock(), Subclass)
1021
1022.. [#] An exception to this rule are the non-callable mocks. Attributes use the
1023 callable variant because otherwise non-callable mocks couldn't have callable
1024 methods.
1025
1026
1027Mocking imports with patch.dict
1028-------------------------------
1029
1030One situation where mocking can be hard is where you have a local import inside
1031a function. These are harder to mock because they aren't using an object from
1032the module namespace that we can patch out.
1033
1034Generally local imports are to be avoided. They are sometimes done to prevent
1035circular dependencies, for which there is *usually* a much better way to solve
1036the problem (refactor the code) or to prevent "up front costs" by delaying the
1037import. This can also be solved in better ways than an unconditional local
1038import (store the module as a class or module attribute and only do the import
1039on first use).
1040
1041That aside there is a way to use `mock` to affect the results of an import.
1042Importing fetches an *object* from the `sys.modules` dictionary. Note that it
1043fetches an *object*, which need not be a module. Importing a module for the
1044first time results in a module object being put in `sys.modules`, so usually
1045when you import something you get a module back. This need not be the case
1046however.
1047
1048This means you can use :func:`patch.dict` to *temporarily* put a mock in place
1049in `sys.modules`. Any imports whilst this patch is active will fetch the mock.
1050When the patch is complete (the decorated function exits, the with statement
1051body is complete or `patcher.stop()` is called) then whatever was there
1052previously will be restored safely.
1053
1054Here's an example that mocks out the 'fooble' module.
1055
1056 >>> mock = Mock()
1057 >>> with patch.dict('sys.modules', {'fooble': mock}):
1058 ... import fooble
1059 ... fooble.blob()
1060 ...
1061 <Mock name='mock.blob()' id='...'>
1062 >>> assert 'fooble' not in sys.modules
1063 >>> mock.blob.assert_called_once_with()
1064
1065As you can see the `import fooble` succeeds, but on exit there is no 'fooble'
1066left in `sys.modules`.
1067
1068This also works for the `from module import name` form:
1069
1070 >>> mock = Mock()
1071 >>> with patch.dict('sys.modules', {'fooble': mock}):
1072 ... from fooble import blob
1073 ... blob.blip()
1074 ...
1075 <Mock name='mock.blob.blip()' id='...'>
1076 >>> mock.blob.blip.assert_called_once_with()
1077
1078With slightly more work you can also mock package imports:
1079
1080 >>> mock = Mock()
1081 >>> modules = {'package': mock, 'package.module': mock.module}
1082 >>> with patch.dict('sys.modules', modules):
1083 ... from package.module import fooble
1084 ... fooble()
1085 ...
1086 <Mock name='mock.module.fooble()' id='...'>
1087 >>> mock.module.fooble.assert_called_once_with()
1088
1089
1090Tracking order of calls and less verbose call assertions
1091--------------------------------------------------------
1092
1093The :class:`Mock` class allows you to track the *order* of method calls on
1094your mock objects through the :attr:`~Mock.method_calls` attribute. This
1095doesn't allow you to track the order of calls between separate mock objects,
1096however we can use :attr:`~Mock.mock_calls` to achieve the same effect.
1097
1098Because mocks track calls to child mocks in `mock_calls`, and accessing an
1099arbitrary attribute of a mock creates a child mock, we can create our separate
1100mocks from a parent one. Calls to those child mock will then all be recorded,
1101in order, in the `mock_calls` of the parent:
1102
1103 >>> manager = Mock()
1104 >>> mock_foo = manager.foo
1105 >>> mock_bar = manager.bar
1106
1107 >>> mock_foo.something()
1108 <Mock name='mock.foo.something()' id='...'>
1109 >>> mock_bar.other.thing()
1110 <Mock name='mock.bar.other.thing()' id='...'>
1111
1112 >>> manager.mock_calls
1113 [call.foo.something(), call.bar.other.thing()]
1114
1115We can then assert about the calls, including the order, by comparing with
1116the `mock_calls` attribute on the manager mock:
1117
1118 >>> expected_calls = [call.foo.something(), call.bar.other.thing()]
1119 >>> manager.mock_calls == expected_calls
1120 True
1121
1122If `patch` is creating, and putting in place, your mocks then you can attach
1123them to a manager mock using the :meth:`~Mock.attach_mock` method. After
1124attaching calls will be recorded in `mock_calls` of the manager.
1125
1126 >>> manager = MagicMock()
1127 >>> with patch('mymodule.Class1') as MockClass1:
1128 ... with patch('mymodule.Class2') as MockClass2:
1129 ... manager.attach_mock(MockClass1, 'MockClass1')
1130 ... manager.attach_mock(MockClass2, 'MockClass2')
1131 ... MockClass1().foo()
1132 ... MockClass2().bar()
1133 ...
1134 <MagicMock name='mock.MockClass1().foo()' id='...'>
1135 <MagicMock name='mock.MockClass2().bar()' id='...'>
1136 >>> manager.mock_calls
1137 [call.MockClass1(),
1138 call.MockClass1().foo(),
1139 call.MockClass2(),
1140 call.MockClass2().bar()]
1141
1142If many calls have been made, but you're only interested in a particular
1143sequence of them then an alternative is to use the
1144:meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed
1145with the :data:`call` object). If that sequence of calls are in
1146:attr:`~Mock.mock_calls` then the assert succeeds.
1147
1148 >>> m = MagicMock()
1149 >>> m().foo().bar().baz()
1150 <MagicMock name='mock().foo().bar().baz()' id='...'>
1151 >>> m.one().two().three()
1152 <MagicMock name='mock.one().two().three()' id='...'>
1153 >>> calls = call.one().two().three().call_list()
1154 >>> m.assert_has_calls(calls)
1155
1156Even though the chained call `m.one().two().three()` aren't the only calls that
1157have been made to the mock, the assert still succeeds.
1158
1159Sometimes a mock may have several calls made to it, and you are only interested
1160in asserting about *some* of those calls. You may not even care about the
1161order. In this case you can pass `any_order=True` to `assert_has_calls`:
1162
1163 >>> m = MagicMock()
1164 >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50')
1165 (...)
1166 >>> calls = [call.fifty('50'), call(1), call.seven(7)]
1167 >>> m.assert_has_calls(calls, any_order=True)
1168
1169
1170More complex argument matching
1171------------------------------
1172
1173Using the same basic concept as :data:`ANY` we can implement matchers to do more
1174complex assertions on objects used as arguments to mocks.
1175
1176Suppose we expect some object to be passed to a mock that by default
1177compares equal based on object identity (which is the Python default for user
1178defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass
1179in the exact same object. If we are only interested in some of the attributes
1180of this object then we can create a matcher that will check these attributes
1181for us.
1182
1183You can see in this example how a 'standard' call to `assert_called_with` isn't
1184sufficient:
1185
1186 >>> class Foo(object):
1187 ... def __init__(self, a, b):
1188 ... self.a, self.b = a, b
1189 ...
1190 >>> mock = Mock(return_value=None)
1191 >>> mock(Foo(1, 2))
1192 >>> mock.assert_called_with(Foo(1, 2))
1193 Traceback (most recent call last):
1194 ...
1195 AssertionError: Expected: call(<__main__.Foo object at 0x...>)
1196 Actual call: call(<__main__.Foo object at 0x...>)
1197
1198A comparison function for our `Foo` class might look something like this:
1199
1200 >>> def compare(self, other):
1201 ... if not type(self) == type(other):
1202 ... return False
1203 ... if self.a != other.a:
1204 ... return False
1205 ... if self.b != other.b:
1206 ... return False
1207 ... return True
1208 ...
1209
1210And a matcher object that can use comparison functions like this for its
1211equality operation would look something like this:
1212
1213 >>> class Matcher(object):
1214 ... def __init__(self, compare, some_obj):
1215 ... self.compare = compare
1216 ... self.some_obj = some_obj
1217 ... def __eq__(self, other):
1218 ... return self.compare(self.some_obj, other)
1219 ...
1220
1221Putting all this together:
1222
1223 >>> match_foo = Matcher(compare, Foo(1, 2))
1224 >>> mock.assert_called_with(match_foo)
1225
1226The `Matcher` is instantiated with our compare function and the `Foo` object
1227we want to compare against. In `assert_called_with` the `Matcher` equality
1228method will be called, which compares the object the mock was called with
1229against the one we created our matcher with. If they match then
1230`assert_called_with` passes, and if they don't an `AssertionError` is raised:
1231
1232 >>> match_wrong = Matcher(compare, Foo(3, 4))
1233 >>> mock.assert_called_with(match_wrong)
1234 Traceback (most recent call last):
1235 ...
1236 AssertionError: Expected: ((<Matcher object at 0x...>,), {})
1237 Called with: ((<Foo object at 0x...>,), {})
1238
1239With a bit of tweaking you could have the comparison function raise the
1240`AssertionError` directly and provide a more useful failure message.
1241
1242As of version 1.5, the Python testing library `PyHamcrest
1243<http://pypi.python.org/pypi/PyHamcrest>`_ provides similar functionality,
1244that may be useful here, in the form of its equality matcher
1245(`hamcrest.library.integration.match_equality
1246<http://packages.python.org/PyHamcrest/integration.html#hamcrest.library.integration.match_equality>`_).