Debian Codegraph @

Doc/library/unittest.mock-examples.rst

raw
1 :mod:`!unittest.mock` --- getting started
2 =========================================
3
4 .. moduleauthor:: Michael Foord <[email protected]>
5 .. currentmodule:: unittest.mock
6
7 .. versionadded:: 3.3
8
9
10 .. _getting-started:
11
12
13 .. testsetup::
14
15 import asyncio
16 import unittest
17 from unittest.mock import Mock, MagicMock, AsyncMock, patch, call, sentinel
18
19 class SomeClass:
20 attribute = 'this is a doctest'
21
22 @staticmethod
23 def static_method():
24 pass
25
26 Using Mock
27 ----------
28
29 Mock patching methods
30 ~~~~~~~~~~~~~~~~~~~~~
31
32 Common uses for :class:`Mock` objects include:
33
34 * Patching methods
35 * Recording method calls on objects
36
37 You might want to replace a method on an object to check that
38 it is called with the correct arguments by another part of the system:
39
40 >>> real = SomeClass()
41 >>> real.method = MagicMock(name='method')
42 >>> real.method(3, 4, 5, key='value')
43 <MagicMock name='method()' id='...'>
44
45 Once our mock has been used (``real.method`` in this example) it has methods
46 and attributes that allow you to make assertions about how it has been used.
47
48 .. note::
49
50 In most of these examples the :class:`Mock` and :class:`MagicMock` classes
51 are interchangeable. As the ``MagicMock`` is the more capable class it makes
52 a sensible one to use by default.
53
54 Once the mock has been called its :attr:`~Mock.called` attribute is set to
55 ``True``. More importantly we can use the :meth:`~Mock.assert_called_with` or
56 :meth:`~Mock.assert_called_once_with` method to check that it was called with
57 the correct arguments.
58
59 This example tests that calling ``ProductionClass().method`` results in a call to
60 the ``something`` method:
61
62 >>> class ProductionClass:
63 ... def method(self):
64 ... self.something(1, 2, 3)
65 ... def something(self, a, b, c):
66 ... pass
67 ...
68 >>> real = ProductionClass()
69 >>> real.something = MagicMock()
70 >>> real.method()
71 >>> real.something.assert_called_once_with(1, 2, 3)
72
73
74
75 Mock for method calls on an object
76 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
77
78 In the last example we patched a method directly on an object to check that it
79 was called correctly. Another common use case is to pass an object into a
80 method (or some part of the system under test) and then check that it is used
81 in the correct way.
82
83 The simple ``ProductionClass`` below has a ``closer`` method. If it is called with
84 an object then it calls ``close`` on it.
85
86 >>> class ProductionClass:
87 ... def closer(self, something):
88 ... something.close()
89 ...
90
91 So to test it we need to pass in an object with a ``close`` method and check
92 that it was called correctly.
93
94 >>> real = ProductionClass()
95 >>> mock = Mock()
96 >>> real.closer(mock)
97 >>> mock.close.assert_called_with()
98
99 We don't have to do any work to provide the 'close' method on our mock.
100 Accessing close creates it. So, if 'close' hasn't already been called then
101 accessing it in the test will create it, but :meth:`~Mock.assert_called_with`
102 will raise a failure exception.
103
104
105 Mocking classes
106 ~~~~~~~~~~~~~~~
107
108 A common use case is to mock out classes instantiated by your code under test.
109 When you patch a class, then that class is replaced with a mock. Instances
110 are created by *calling the class*. This means you access the "mock instance"
111 by looking at the return value of the mocked class.
112
113 In the example below we have a function ``some_function`` that instantiates ``Foo``
114 and calls a method on it. The call to :func:`patch` replaces the class ``Foo`` with a
115 mock. The ``Foo`` instance is the result of calling the mock, so it is configured
116 by modifying the mock :attr:`~Mock.return_value`. ::
117
118 >>> def some_function():
119 ... instance = module.Foo()
120 ... return instance.method()
121 ...
122 >>> with patch('module.Foo') as mock:
123 ... instance = mock.return_value
124 ... instance.method.return_value = 'the result'
125 ... result = some_function()
126 ... assert result == 'the result'
127
128
129 Naming your mocks
130 ~~~~~~~~~~~~~~~~~
131
132 It can be useful to give your mocks a name. The name is shown in the repr of
133 the mock and can be helpful when the mock appears in test failure messages. The
134 name is also propagated to attributes or methods of the mock:
135
136 >>> mock = MagicMock(name='foo')
137 >>> mock
138 <MagicMock name='foo' id='...'>
139 >>> mock.method
140 <MagicMock name='foo.method' id='...'>
141
142
143 Tracking all calls
144 ~~~~~~~~~~~~~~~~~~
145
146 Often you want to track more than a single call to a method. The
147 :attr:`~Mock.mock_calls` attribute records all calls
148 to child attributes of the mock - and also to their children.
149
150 >>> mock = MagicMock()
151 >>> mock.method()
152 <MagicMock name='mock.method()' id='...'>
153 >>> mock.attribute.method(10, x=53)
154 <MagicMock name='mock.attribute.method()' id='...'>
155 >>> mock.mock_calls
156 [call.method(), call.attribute.method(10, x=53)]
157
158 If you make an assertion about ``mock_calls`` and any unexpected methods
159 have been called, then the assertion will fail. This is useful because as well
160 as asserting that the calls you expected have been made, you are also checking
161 that they were made in the right order and with no additional calls:
162
163 You use the :data:`call` object to construct lists for comparing with
164 ``mock_calls``:
165
166 >>> expected = [call.method(), call.attribute.method(10, x=53)]
167 >>> mock.mock_calls == expected
168 True
169
170 However, parameters to calls that return mocks are not recorded, which means it is not
171 possible to track nested calls where the parameters used to create ancestors are important:
172
173 >>> m = Mock()
174 >>> m.factory(important=True).deliver()
175 <Mock name='mock.factory().deliver()' id='...'>
176 >>> m.mock_calls[-1] == call.factory(important=False).deliver()
177 True
178
179
180 Setting return values and attributes
181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
182
183 Setting the return values on a mock object is trivially easy:
184
185 >>> mock = Mock()
186 >>> mock.return_value = 3
187 >>> mock()
188 3
189
190 Of course you can do the same for methods on the mock:
191
192 >>> mock = Mock()
193 >>> mock.method.return_value = 3
194 >>> mock.method()
195 3
196
197 The return value can also be set in the constructor:
198
199 >>> mock = Mock(return_value=3)
200 >>> mock()
201 3
202
203 If you need an attribute setting on your mock, just do it:
204
205 >>> mock = Mock()
206 >>> mock.x = 3
207 >>> mock.x
208 3
209
210 Sometimes you want to mock up a more complex situation, like for example
211 ``mock.connection.cursor().execute("SELECT 1")``. If we wanted this call to
212 return a list, then we have to configure the result of the nested call.
213
214 We can use :data:`call` to construct the set of calls in a "chained call" like
215 this for easy assertion afterwards:
216
217 >>> mock = Mock()
218 >>> cursor = mock.connection.cursor.return_value
219 >>> cursor.execute.return_value = ['foo']
220 >>> mock.connection.cursor().execute("SELECT 1")
221 ['foo']
222 >>> expected = call.connection.cursor().execute("SELECT 1").call_list()
223 >>> mock.mock_calls
224 [call.connection.cursor(), call.connection.cursor().execute('SELECT 1')]
225 >>> mock.mock_calls == expected
226 True
227
228 It is the call to ``.call_list()`` that turns our call object into a list of
229 calls representing the chained calls.
230
231
232 Raising exceptions with mocks
233 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234
235 A useful attribute is :attr:`~Mock.side_effect`. If you set this to an
236 exception class or instance then the exception will be raised when the mock
237 is called.
238
239 >>> mock = Mock(side_effect=Exception('Boom!'))
240 >>> mock()
241 Traceback (most recent call last):
242 ...
243 Exception: Boom!
244
245
246 Side effect functions and iterables
247 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
248
249 ``side_effect`` can also be set to a function or an iterable. The use case for
250 ``side_effect`` as an iterable is where your mock is going to be called several
251 times, and you want each call to return a different value. When you set
252 ``side_effect`` to an iterable every call to the mock returns the next value
253 from the iterable:
254
255 >>> mock = MagicMock(side_effect=[4, 5, 6])
256 >>> mock()
257 4
258 >>> mock()
259 5
260 >>> mock()
261 6
262
263
264 For more advanced use cases, like dynamically varying the return values
265 depending on what the mock is called with, ``side_effect`` can be a function.
266 The function will be called with the same arguments as the mock. Whatever the
267 function returns is what the call returns:
268
269 >>> vals = {(1, 2): 1, (2, 3): 2}
270 >>> def side_effect(*args):
271 ... return vals[args]
272 ...
273 >>> mock = MagicMock(side_effect=side_effect)
274 >>> mock(1, 2)
275 1
276 >>> mock(2, 3)
277 2
278
279
280 Mocking asynchronous iterators
281 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
282
283 Since Python 3.8, ``AsyncMock`` and ``MagicMock`` have support to mock
284 :ref:`async-iterators` through ``__aiter__``. The :attr:`~Mock.return_value`
285 attribute of ``__aiter__`` can be used to set the return values to be used for
286 iteration.
287
288 >>> mock = MagicMock() # AsyncMock also works here
289 >>> mock.__aiter__.return_value = [1, 2, 3]
290 >>> async def main():
291 ... return [i async for i in mock]
292 ...
293 >>> asyncio.run(main())
294 [1, 2, 3]
295
296
297 Mocking asynchronous context manager
298 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
299
300 Since Python 3.8, ``AsyncMock`` and ``MagicMock`` have support to mock
301 :ref:`async-context-managers` through ``__aenter__`` and ``__aexit__``.
302 By default, ``__aenter__`` and ``__aexit__`` are ``AsyncMock`` instances that
303 return an async function.
304
305 >>> class AsyncContextManager:
306 ... async def __aenter__(self):
307 ... return self
308 ... async def __aexit__(self, exc_type, exc, tb):
309 ... pass
310 ...
311 >>> mock_instance = MagicMock(AsyncContextManager()) # AsyncMock also works here
312 >>> async def main():
313 ... async with mock_instance as result:
314 ... pass
315 ...
316 >>> asyncio.run(main())
317 >>> mock_instance.__aenter__.assert_awaited_once()
318 >>> mock_instance.__aexit__.assert_awaited_once()
319
320
321 Creating a mock from an existing object
322 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
323
324 One problem with over use of mocking is that it couples your tests to the
325 implementation of your mocks rather than your real code. Suppose you have a
326 class that implements ``some_method``. In a test for another class, you
327 provide a mock of this object that *also* provides ``some_method``. If later
328 you refactor the first class, so that it no longer has ``some_method`` - then
329 your tests will continue to pass even though your code is now broken!
330
331 :class:`Mock` allows you to provide an object as a specification for the mock,
332 using the *spec* keyword argument. Accessing methods / attributes on the
333 mock that don't exist on your specification object will immediately raise an
334 attribute error. If you change the implementation of your specification, then
335 tests that use that class will start failing immediately without you having to
336 instantiate the class in those tests.
337
338 >>> mock = Mock(spec=SomeClass)
339 >>> mock.old_method()
340 Traceback (most recent call last):
341 ...
342 AttributeError: Mock object has no attribute 'old_method'. Did you mean: 'class_method'?
343
344 Using a specification also enables a smarter matching of calls made to the
345 mock, regardless of whether some parameters were passed as positional or
346 named arguments::
347
348 >>> def f(a, b, c): pass
349 ...
350 >>> mock = Mock(spec=f)
351 >>> mock(1, 2, 3)
352 <Mock name='mock()' id='140161580456576'>
353 >>> mock.assert_called_with(a=1, b=2, c=3)
354
355 If you want this smarter matching to also work with method calls on the mock,
356 you can use :ref:`auto-speccing <auto-speccing>`.
357
358 If you want a stronger form of specification that prevents the setting
359 of arbitrary attributes as well as the getting of them then you can use
360 *spec_set* instead of *spec*.
361
362
363 Using side_effect to return per file content
364 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
365
366 :func:`mock_open` is used to patch :func:`open` method. :attr:`~Mock.side_effect`
367 can be used to return a new Mock object per call. This can be used to return different
368 contents per file stored in a dictionary::
369
370 DEFAULT = "default"
371 data_dict = {"file1": "data1",
372 "file2": "data2"}
373
374 def open_side_effect(name):
375 return mock_open(read_data=data_dict.get(name, DEFAULT))()
376
377 with patch("builtins.open", side_effect=open_side_effect):
378 with open("file1") as file1:
379 assert file1.read() == "data1"
380
381 with open("file2") as file2:
382 assert file2.read() == "data2"
383
384 with open("file3") as file2:
385 assert file2.read() == "default"
386
387
388 Patch decorators
389 ----------------
390
391 .. note::
392
393 With :func:`patch` it matters that you patch objects in the namespace where
394 they are looked up. This is normally straightforward, but for a quick guide
395 read :ref:`where to patch <where-to-patch>`.
396
397
398 A common need in tests is to patch a class attribute or a module attribute,
399 for example patching a builtin or patching a class in a module to test that it
400 is instantiated. Modules and classes are effectively global, so patching on
401 them has to be undone after the test or the patch will persist into other
402 tests and cause hard to diagnose problems.
403
404 mock provides three convenient decorators for this: :func:`patch`, :func:`patch.object` and
405 :func:`patch.dict`. ``patch`` takes a single string, of the form
406 ``package.module.Class.attribute`` to specify the attribute you are patching. It
407 also optionally takes a value that you want the attribute (or class or
408 whatever) to be replaced with. 'patch.object' takes an object and the name of
409 the attribute you would like patched, plus optionally the value to patch it
410 with.
411
412 ``patch.object``::
413
414 >>> original = SomeClass.attribute
415 >>> @patch.object(SomeClass, 'attribute', sentinel.attribute)
416 ... def test():
417 ... assert SomeClass.attribute == sentinel.attribute
418 ...
419 >>> test()
420 >>> assert SomeClass.attribute == original
421
422 >>> @patch('package.module.attribute', sentinel.attribute)
423 ... def test():
424 ... from package.module import attribute
425 ... assert attribute is sentinel.attribute
426 ...
427 >>> test()
428
429 If you are patching a module (including :mod:`builtins`) then use :func:`patch`
430 instead of :func:`patch.object`:
431
432 >>> mock = MagicMock(return_value=sentinel.file_handle)
433 >>> with patch('builtins.open', mock):
434 ... handle = open('filename', 'r')
435 ...
436 >>> mock.assert_called_with('filename', 'r')
437 >>> assert handle == sentinel.file_handle, "incorrect file handle returned"
438
439 The module name can be 'dotted', in the form ``package.module`` if needed::
440
441 >>> @patch('package.module.ClassName.attribute', sentinel.attribute)
442 ... def test():
443 ... from package.module import ClassName
444 ... assert ClassName.attribute == sentinel.attribute
445 ...
446 >>> test()
447
448 A nice pattern is to actually decorate test methods themselves:
449
450 >>> class MyTest(unittest.TestCase):
451 ... @patch.object(SomeClass, 'attribute', sentinel.attribute)
452 ... def test_something(self):
453 ... self.assertEqual(SomeClass.attribute, sentinel.attribute)
454 ...
455 >>> original = SomeClass.attribute
456 >>> MyTest('test_something').test_something()
457 >>> assert SomeClass.attribute == original
458
459 If you want to patch with a Mock, you can use :func:`patch` with only one argument
460 (or :func:`patch.object` with two arguments). The mock will be created for you and
461 passed into the test function / method:
462
463 >>> class MyTest(unittest.TestCase):
464 ... @patch.object(SomeClass, 'static_method')
465 ... def test_something(self, mock_method):
466 ... SomeClass.static_method()
467 ... mock_method.assert_called_with()
468 ...
469 >>> MyTest('test_something').test_something()
470
471 You can stack up multiple patch decorators using this pattern::
472
473 >>> class MyTest(unittest.TestCase):
474 ... @patch('package.module.ClassName1')
475 ... @patch('package.module.ClassName2')
476 ... def test_something(self, MockClass2, MockClass1):
477 ... self.assertIs(package.module.ClassName1, MockClass1)
478 ... self.assertIs(package.module.ClassName2, MockClass2)
479 ...
480 >>> MyTest('test_something').test_something()
481
482 When you nest patch decorators the mocks are passed in to the decorated
483 function in the same order they applied (the normal *Python* order that
484 decorators are applied). This means from the bottom up, so in the example
485 above the mock for ``test_module.ClassName2`` is passed in first.
486
487 There is also :func:`patch.dict` for setting values in a dictionary just
488 during a scope and restoring the dictionary to its original state when the test
489 ends:
490
491 >>> foo = {'key': 'value'}
492 >>> original = foo.copy()
493 >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True):
494 ... assert foo == {'newkey': 'newvalue'}
495 ...
496 >>> assert foo == original
497
498 ``patch``, ``patch.object`` and ``patch.dict`` can all be used as context managers.
499
500 Where you use :func:`patch` to create a mock for you, you can get a reference to the
501 mock using the "as" form of the with statement:
502
503 >>> class ProductionClass:
504 ... def method(self):
505 ... pass
506 ...
507 >>> with patch.object(ProductionClass, 'method') as mock_method:
508 ... mock_method.return_value = None
509 ... real = ProductionClass()
510 ... real.method(1, 2, 3)
511 ...
512 >>> mock_method.assert_called_with(1, 2, 3)
513
514
515 As an alternative ``patch``, ``patch.object`` and ``patch.dict`` can be used as
516 class decorators. When used in this way it is the same as applying the
517 decorator individually to every method whose name starts with "test".
518
519
520 .. _further-examples:
521
522 Further examples
523 ----------------
524
525
526 Here are some more examples for some slightly more advanced scenarios.
527
528
529 Mocking chained calls
530 ~~~~~~~~~~~~~~~~~~~~~
531
532 Mocking chained calls is actually straightforward with mock once you
533 understand the :attr:`~Mock.return_value` attribute. When a mock is called for
534 the first time, or you fetch its ``return_value`` before it has been called, a
535 new :class:`Mock` is created.
536
537 This means that you can see how the object returned from a call to a mocked
538 object has been used by interrogating the ``return_value`` mock:
539
540 >>> mock = Mock()
541 >>> mock().foo(a=2, b=3)
542 <Mock name='mock().foo()' id='...'>
543 >>> mock.return_value.foo.assert_called_with(a=2, b=3)
544
545 From here it is a simple step to configure and then make assertions about
546 chained calls. Of course another alternative is writing your code in a more
547 testable way in the first place...
548
549 So, suppose we have some code that looks a little bit like this:
550
551 >>> class Something:
552 ... def __init__(self):
553 ... self.backend = BackendProvider()
554 ... def method(self):
555 ... response = self.backend.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
556 ... # more code
557
558 Assuming that ``BackendProvider`` is already well tested, how do we test
559 ``method()``? Specifically, we want to test that the code section ``# more
560 code`` uses the response object in the correct way.
561
562 As this chain of calls is made from an instance attribute we can monkey patch
563 the ``backend`` attribute on a ``Something`` instance. In this particular case
564 we are only interested in the return value from the final call to
565 ``start_call`` so we don't have much configuration to do. Let's assume the
566 object it returns is 'file-like', so we'll ensure that our response object
567 uses the builtin :func:`open` as its ``spec``.
568
569 To do this we create a mock instance as our mock backend and create a mock
570 response object for it. To set the response as the return value for that final
571 ``start_call`` we could do this::
572
573 mock_backend.get_endpoint.return_value.create_call.return_value.start_call.return_value = mock_response
574
575 We can do that in a slightly nicer way using the :meth:`~Mock.configure_mock`
576 method to directly set the return value for us::
577
578 >>> something = Something()
579 >>> mock_response = Mock(spec=open)
580 >>> mock_backend = Mock()
581 >>> config = {'get_endpoint.return_value.create_call.return_value.start_call.return_value': mock_response}
582 >>> mock_backend.configure_mock(**config)
583
584 With these we monkey patch the "mock backend" in place and can make the real
585 call::
586
587 >>> something.backend = mock_backend
588 >>> something.method()
589
590 Using :attr:`~Mock.mock_calls` we can check the chained call with a single
591 assert. A chained call is several calls in one line of code, so there will be
592 several entries in ``mock_calls``. We can use :meth:`call.call_list` to create
593 this list of calls for us::
594
595 >>> chained = call.get_endpoint('foobar').create_call('spam', 'eggs').start_call()
596 >>> call_list = chained.call_list()
597 >>> assert mock_backend.mock_calls == call_list
598
599
600 Partial mocking
601 ~~~~~~~~~~~~~~~
602
603 For some tests, you may want to mock out a call to :meth:`datetime.date.today`
604 to return a known date, but don't want to prevent the code under test from
605 creating new date objects. Unfortunately :class:`datetime.date` is written in C,
606 so you cannot just monkey-patch out the static :meth:`datetime.date.today` method.
607
608 Instead, you can effectively wrap the date
609 class with a mock, while passing through calls to the constructor to the real
610 class (and returning real instances).
611
612 The :func:`patch decorator <patch>` is used here to
613 mock out the ``date`` class in the module under test. The :attr:`~Mock.side_effect`
614 attribute on the mock date class is then set to a lambda function that returns
615 a real date. When the mock date class is called a real date will be
616 constructed and returned by ``side_effect``. ::
617
618 >>> import datetime as dt
619 >>> with patch('mymodule.date') as mock_date:
620 ... mock_date.today.return_value = dt.date(2010, 10, 8)
621 ... mock_date.side_effect = lambda *args, **kw: dt.date(*args, **kw)
622 ...
623 ... assert mymodule.date.today() == dt.date(2010, 10, 8)
624 ... assert mymodule.date(2009, 6, 8) == dt.date(2009, 6, 8)
625
626 Note that we don't patch :class:`datetime.date` globally, we patch ``date`` in the
627 module that *uses* it. See :ref:`where to patch <where-to-patch>`.
628
629 When ``date.today()`` is called a known date is returned, but calls to the
630 ``date(...)`` constructor still return normal dates. Without this you can find
631 yourself having to calculate an expected result using exactly the same
632 algorithm as the code under test, which is a classic testing anti-pattern.
633
634 Calls to the date constructor are recorded in the ``mock_date`` attributes
635 (``call_count`` and friends) which may also be useful for your tests.
636
637 An alternative way of dealing with mocking dates, or other builtin classes,
638 is discussed in `this blog entry
639 <https://williambert.online/2011/07/how-to-unit-testing-in-django-with-mocking-and-patching/>`_.
640
641
642 Mocking a generator method
643 ~~~~~~~~~~~~~~~~~~~~~~~~~~
644
645 A Python generator is a function or method that uses the :keyword:`yield` statement
646 to return a series of values when iterated over [#]_.
647
648 A generator method / function is called to return the generator object. It is
649 the generator object that is then iterated over. The protocol method for
650 iteration is :meth:`~container.__iter__`, so we can
651 mock this using a :class:`MagicMock`.
652
653 Here's an example class with an "iter" method implemented as a generator:
654
655 >>> class Foo:
656 ... def iter(self):
657 ... for i in [1, 2, 3]:
658 ... yield i
659 ...
660 >>> foo = Foo()
661 >>> list(foo.iter())
662 [1, 2, 3]
663
664
665 How would we mock this class, and in particular its "iter" method?
666
667 To configure the values returned from the iteration (implicit in the call to
668 :class:`list`), we need to configure the object returned by the call to ``foo.iter()``.
669
670 >>> mock_foo = MagicMock()
671 >>> mock_foo.iter.return_value = iter([1, 2, 3])
672 >>> list(mock_foo.iter())
673 [1, 2, 3]
674
675 .. [#] There are also generator expressions and more `advanced uses
676 <http://www.dabeaz.com/coroutines/index.html>`_ of generators, but we aren't
677 concerned about them here. A very good introduction to generators and how
678 powerful they are is: `Generator Tricks for Systems Programmers
679 <http://www.dabeaz.com/generators/>`_.
680
681
682 Applying the same patch to every test method
683 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
684
685 If you want several patches in place for multiple test methods the obvious way
686 is to apply the patch decorators to every method. This can feel like unnecessary
687 repetition. Instead, you can use :func:`patch` (in all its
688 various forms) as a class decorator. This applies the patches to all test
689 methods on the class. A test method is identified by methods whose names start
690 with ``test``::
691
692 >>> @patch('mymodule.SomeClass')
693 ... class MyTest(unittest.TestCase):
694 ...
695 ... def test_one(self, MockSomeClass):
696 ... self.assertIs(mymodule.SomeClass, MockSomeClass)
697 ...
698 ... def test_two(self, MockSomeClass):
699 ... self.assertIs(mymodule.SomeClass, MockSomeClass)
700 ...
701 ... def not_a_test(self):
702 ... return 'something'
703 ...
704 >>> MyTest('test_one').test_one()
705 >>> MyTest('test_two').test_two()
706 >>> MyTest('test_two').not_a_test()
707 'something'
708
709 An alternative way of managing patches is to use the :ref:`start-and-stop`.
710 These allow you to move the patching into your ``setUp`` and ``tearDown`` methods.
711 ::
712
713 >>> class MyTest(unittest.TestCase):
714 ... def setUp(self):
715 ... self.patcher = patch('mymodule.foo')
716 ... self.mock_foo = self.patcher.start()
717 ...
718 ... def test_foo(self):
719 ... self.assertIs(mymodule.foo, self.mock_foo)
720 ...
721 ... def tearDown(self):
722 ... self.patcher.stop()
723 ...
724 >>> MyTest('test_foo').run()
725
726 If you use this technique you must ensure that the patching is "undone" by
727 calling ``stop``. This can be fiddlier than you might think, because if an
728 exception is raised in the setUp then tearDown is not called.
729 :meth:`unittest.TestCase.addCleanup` makes this easier::
730
731 >>> class MyTest(unittest.TestCase):
732 ... def setUp(self):
733 ... patcher = patch('mymodule.foo')
734 ... self.addCleanup(patcher.stop)
735 ... self.mock_foo = patcher.start()
736 ...
737 ... def test_foo(self):
738 ... self.assertIs(mymodule.foo, self.mock_foo)
739 ...
740 >>> MyTest('test_foo').run()
741
742
743 Mocking unbound methods
744 ~~~~~~~~~~~~~~~~~~~~~~~
745
746 Sometimes a test needs to patch an *unbound method*, which means patching the
747 method on the class rather than on the instance. In order to make assertions
748 about which objects were calling this particular method, you need to pass
749 ``self`` as the first argument. The issue is that you can't patch with a mock for
750 this, because if you replace an unbound method with a mock it doesn't become
751 a bound method when fetched from the instance, and so it doesn't get ``self``
752 passed in. The workaround is to patch the unbound method with a real function
753 instead. The :func:`patch` decorator makes it so simple to patch out methods
754 with a mock that having to create a real function becomes a nuisance.
755
756 If you pass ``autospec=True`` to patch then it does the patching with a
757 *real* function object. This function object has the same signature as the one
758 it is replacing, but delegates to a mock under the hood. You still get your
759 mock auto-created in exactly the same way as before. What it means though, is
760 that if you use it to patch out an unbound method on a class the mocked
761 function will be turned into a bound method if it is fetched from an instance.
762 It will have ``self`` passed in as the first argument, which is exactly what
763 was needed:
764
765 >>> class Foo:
766 ... def foo(self):
767 ... pass
768 ...
769 >>> with patch.object(Foo, 'foo', autospec=True) as mock_foo:
770 ... mock_foo.return_value = 'foo'
771 ... foo = Foo()
772 ... foo.foo()
773 ...
774 'foo'
775 >>> mock_foo.assert_called_once_with(foo)
776
777 If we don't use ``autospec=True`` then the unbound method is patched out
778 with a Mock instance instead, and isn't called with ``self``.
779
780
781 Checking multiple calls with mock
782 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
783
784 mock has a nice API for making assertions about how your mock objects are used.
785
786 >>> mock = Mock()
787 >>> mock.foo_bar.return_value = None
788 >>> mock.foo_bar('baz', spam='eggs')
789 >>> mock.foo_bar.assert_called_with('baz', spam='eggs')
790
791 If your mock is only being called once you can use the
792 :meth:`~Mock.assert_called_once_with` method that also asserts that the
793 :attr:`~Mock.call_count` is one.
794
795 >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
796 >>> mock.foo_bar()
797 >>> mock.foo_bar.assert_called_once_with('baz', spam='eggs')
798 Traceback (most recent call last):
799 ...
800 AssertionError: Expected 'foo_bar' to be called once. Called 2 times.
801 Calls: [call('baz', spam='eggs'), call()].
802
803 Both ``assert_called_with`` and ``assert_called_once_with`` make assertions about
804 the *most recent* call. If your mock is going to be called several times, and
805 you want to make assertions about *all* those calls you can use
806 :attr:`~Mock.call_args_list`:
807
808 >>> mock = Mock(return_value=None)
809 >>> mock(1, 2, 3)
810 >>> mock(4, 5, 6)
811 >>> mock()
812 >>> mock.call_args_list
813 [call(1, 2, 3), call(4, 5, 6), call()]
814
815 The :data:`call` helper makes it easy to make assertions about these calls. You
816 can build up a list of expected calls and compare it to ``call_args_list``. This
817 looks remarkably similar to the repr of the ``call_args_list``:
818
819 >>> expected = [call(1, 2, 3), call(4, 5, 6), call()]
820 >>> mock.call_args_list == expected
821 True
822
823
824 Coping with mutable arguments
825 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
826
827 Another situation is rare, but can bite you, is when your mock is called with
828 mutable arguments. ``call_args`` and ``call_args_list`` store *references* to the
829 arguments. If the arguments are mutated by the code under test then you can no
830 longer make assertions about what the values were when the mock was called.
831
832 Here's some example code that shows the problem. Imagine the following functions
833 defined in 'mymodule'::
834
835 def frob(val):
836 pass
837
838 def grob(val):
839 "First frob and then clear val"
840 frob(val)
841 val.clear()
842
843 When we try to test that ``grob`` calls ``frob`` with the correct argument look
844 what happens::
845
846 >>> with patch('mymodule.frob') as mock_frob:
847 ... val = {6}
848 ... mymodule.grob(val)
849 ...
850 >>> val
851 set()
852 >>> mock_frob.assert_called_with({6})
853 Traceback (most recent call last):
854 ...
855 AssertionError: Expected: (({6},), {})
856 Called with: ((set(),), {})
857
858 One possibility would be for mock to copy the arguments you pass in. This
859 could then cause problems if you do assertions that rely on object identity
860 for equality.
861
862 Here's one solution that uses the :attr:`~Mock.side_effect`
863 functionality. If you provide a ``side_effect`` function for a mock then
864 ``side_effect`` will be called with the same args as the mock. This gives us an
865 opportunity to copy the arguments and store them for later assertions. In this
866 example I'm using *another* mock to store the arguments so that I can use the
867 mock methods for doing the assertion. Again a helper function sets this up for
868 me. ::
869
870 >>> from copy import deepcopy
871 >>> from unittest.mock import Mock, patch, DEFAULT
872 >>> def copy_call_args(mock):
873 ... new_mock = Mock()
874 ... def side_effect(*args, **kwargs):
875 ... args = deepcopy(args)
876 ... kwargs = deepcopy(kwargs)
877 ... new_mock(*args, **kwargs)
878 ... return DEFAULT
879 ... mock.side_effect = side_effect
880 ... return new_mock
881 ...
882 >>> with patch('mymodule.frob') as mock_frob:
883 ... new_mock = copy_call_args(mock_frob)
884 ... val = {6}
885 ... mymodule.grob(val)
886 ...
887 >>> new_mock.assert_called_with({6})
888 >>> new_mock.call_args
889 call({6})
890
891 ``copy_call_args`` is called with the mock that will be called. It returns a new
892 mock that we do the assertion on. The ``side_effect`` function makes a copy of
893 the args and calls our ``new_mock`` with the copy.
894
895 .. note::
896
897 If your mock is only going to be used once there is an easier way of
898 checking arguments at the point they are called. You can simply do the
899 checking inside a ``side_effect`` function.
900
901 >>> def side_effect(arg):
902 ... assert arg == {6}
903 ...
904 >>> mock = Mock(side_effect=side_effect)
905 >>> mock({6})
906 >>> mock(set())
907 Traceback (most recent call last):
908 ...
909 AssertionError
910
911 An alternative approach is to create a subclass of :class:`Mock` or
912 :class:`MagicMock` that copies (using :func:`copy.deepcopy`) the arguments.
913 Here's an example implementation:
914
915 >>> from copy import deepcopy
916 >>> class CopyingMock(MagicMock):
917 ... def __call__(self, /, *args, **kwargs):
918 ... args = deepcopy(args)
919 ... kwargs = deepcopy(kwargs)
920 ... return super().__call__(*args, **kwargs)
921 ...
922 >>> c = CopyingMock(return_value=None)
923 >>> arg = set()
924 >>> c(arg)
925 >>> arg.add(1)
926 >>> c.assert_called_with(set())
927 >>> c.assert_called_with(arg)
928 Traceback (most recent call last):
929 ...
930 AssertionError: expected call not found.
931 Expected: mock({1})
932 Actual: mock(set())
933 >>> c.foo
934 <CopyingMock name='mock.foo' id='...'>
935
936 When you subclass ``Mock`` or ``MagicMock`` all dynamically created attributes,
937 and the ``return_value`` will use your subclass automatically. That means all
938 children of a ``CopyingMock`` will also have the type ``CopyingMock``.
939
940
941 Nesting patches
942 ~~~~~~~~~~~~~~~
943
944 Using patch as a context manager is nice, but if you do multiple patches you
945 can end up with nested with statements indenting further and further to the
946 right::
947
948 >>> class MyTest(unittest.TestCase):
949 ...
950 ... def test_foo(self):
951 ... with patch('mymodule.Foo') as mock_foo:
952 ... with patch('mymodule.Bar') as mock_bar:
953 ... with patch('mymodule.Spam') as mock_spam:
954 ... assert mymodule.Foo is mock_foo
955 ... assert mymodule.Bar is mock_bar
956 ... assert mymodule.Spam is mock_spam
957 ...
958 >>> original = mymodule.Foo
959 >>> MyTest('test_foo').test_foo()
960 >>> assert mymodule.Foo is original
961
962 With unittest ``cleanup`` functions and the :ref:`start-and-stop` we can
963 achieve the same effect without the nested indentation. A simple helper
964 method, ``create_patch``, puts the patch in place and returns the created mock
965 for us::
966
967 >>> class MyTest(unittest.TestCase):
968 ...
969 ... def create_patch(self, name):
970 ... patcher = patch(name)
971 ... thing = patcher.start()
972 ... self.addCleanup(patcher.stop)
973 ... return thing
974 ...
975 ... def test_foo(self):
976 ... mock_foo = self.create_patch('mymodule.Foo')
977 ... mock_bar = self.create_patch('mymodule.Bar')
978 ... mock_spam = self.create_patch('mymodule.Spam')
979 ...
980 ... assert mymodule.Foo is mock_foo
981 ... assert mymodule.Bar is mock_bar
982 ... assert mymodule.Spam is mock_spam
983 ...
984 >>> original = mymodule.Foo
985 >>> MyTest('test_foo').run()
986 >>> assert mymodule.Foo is original
987
988
989 Mocking a dictionary with MagicMock
990 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
991
992 You may want to mock a dictionary, or other container object, recording all
993 access to it whilst having it still behave like a dictionary.
994
995 We can do this with :class:`MagicMock`, which will behave like a dictionary,
996 and using :data:`~Mock.side_effect` to delegate dictionary access to a real
997 underlying dictionary that is under our control.
998
999 When the :meth:`~object.__getitem__` and :meth:`~object.__setitem__` methods
1000 of our ``MagicMock`` are called
1001 (normal dictionary access) then ``side_effect`` is called with the key (and in
1002 the case of ``__setitem__`` the value too). We can also control what is returned.
1003
1004 After the ``MagicMock`` has been used we can use attributes like
1005 :data:`~Mock.call_args_list` to assert about how the dictionary was used:
1006
1007 >>> my_dict = {'a': 1, 'b': 2, 'c': 3}
1008 >>> def getitem(name):
1009 ... return my_dict[name]
1010 ...
1011 >>> def setitem(name, val):
1012 ... my_dict[name] = val
1013 ...
1014 >>> mock = MagicMock()
1015 >>> mock.__getitem__.side_effect = getitem
1016 >>> mock.__setitem__.side_effect = setitem
1017
1018 .. note::
1019
1020 An alternative to using ``MagicMock`` is to use ``Mock`` and *only* provide
1021 the magic methods you specifically want:
1022
1023 >>> mock = Mock()
1024 >>> mock.__getitem__ = Mock(side_effect=getitem)
1025 >>> mock.__setitem__ = Mock(side_effect=setitem)
1026
1027 A *third* option is to use ``MagicMock`` but passing in ``dict`` as the *spec*
1028 (or *spec_set*) argument so that the ``MagicMock`` created only has
1029 dictionary magic methods available:
1030
1031 >>> mock = MagicMock(spec_set=dict)
1032 >>> mock.__getitem__.side_effect = getitem
1033 >>> mock.__setitem__.side_effect = setitem
1034
1035 With these side effect functions in place, the ``mock`` will behave like a normal
1036 dictionary but recording the access. It even raises a :exc:`KeyError` if you try
1037 to access a key that doesn't exist.
1038
1039 >>> mock['a']
1040 1
1041 >>> mock['c']
1042 3
1043 >>> mock['d']
1044 Traceback (most recent call last):
1045 ...
1046 KeyError: 'd'
1047 >>> mock['b'] = 'fish'
1048 >>> mock['d'] = 'eggs'
1049 >>> mock['b']
1050 'fish'
1051 >>> mock['d']
1052 'eggs'
1053
1054 After it has been used you can make assertions about the access using the normal
1055 mock methods and attributes:
1056
1057 >>> mock.__getitem__.call_args_list
1058 [call('a'), call('c'), call('d'), call('b'), call('d')]
1059 >>> mock.__setitem__.call_args_list
1060 [call('b', 'fish'), call('d', 'eggs')]
1061 >>> my_dict
1062 {'a': 1, 'b': 'fish', 'c': 3, 'd': 'eggs'}
1063
1064
1065 Mock subclasses and their attributes
1066 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1067
1068 There are various reasons why you might want to subclass :class:`Mock`. One
1069 reason might be to add helper methods. Here's a silly example:
1070
1071 >>> class MyMock(MagicMock):
1072 ... def has_been_called(self):
1073 ... return self.called
1074 ...
1075 >>> mymock = MyMock(return_value=None)
1076 >>> mymock
1077 <MyMock id='...'>
1078 >>> mymock.has_been_called()
1079 False
1080 >>> mymock()
1081 >>> mymock.has_been_called()
1082 True
1083
1084 The standard behaviour for ``Mock`` instances is that attributes and the return
1085 value mocks are of the same type as the mock they are accessed on. This ensures
1086 that ``Mock`` attributes are ``Mocks`` and ``MagicMock`` attributes are ``MagicMocks``
1087 [#]_. So if you're subclassing to add helper methods then they'll also be
1088 available on the attributes and return value mock of instances of your
1089 subclass.
1090
1091 >>> mymock.foo
1092 <MyMock name='mock.foo' id='...'>
1093 >>> mymock.foo.has_been_called()
1094 False
1095 >>> mymock.foo()
1096 <MyMock name='mock.foo()' id='...'>
1097 >>> mymock.foo.has_been_called()
1098 True
1099
1100 Sometimes this is inconvenient. For example, `one user
1101 <https://code.google.com/archive/p/mock/issues/105>`_ is subclassing mock to
1102 created a `Twisted adaptor
1103 <https://twisted.org/documents/11.0.0/api/twisted.python.components.html>`_.
1104 Having this applied to attributes too actually causes errors.
1105
1106 ``Mock`` (in all its flavours) uses a method called ``_get_child_mock`` to create
1107 these "sub-mocks" for attributes and return values. You can prevent your
1108 subclass being used for attributes by overriding this method. The signature is
1109 that it takes arbitrary keyword arguments (``**kwargs``) which are then passed
1110 onto the mock constructor:
1111
1112 >>> class Subclass(MagicMock):
1113 ... def _get_child_mock(self, /, **kwargs):
1114 ... return MagicMock(**kwargs)
1115 ...
1116 >>> mymock = Subclass()
1117 >>> mymock.foo
1118 <MagicMock name='mock.foo' id='...'>
1119 >>> assert isinstance(mymock, Subclass)
1120 >>> assert not isinstance(mymock.foo, Subclass)
1121 >>> assert not isinstance(mymock(), Subclass)
1122
1123 .. [#] An exception to this rule are the non-callable mocks. Attributes use the
1124 callable variant because otherwise non-callable mocks couldn't have callable
1125 methods.
1126
1127
1128 Mocking imports with patch.dict
1129 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1130
1131 One situation where mocking can be hard is where you have a local import inside
1132 a function. These are harder to mock because they aren't using an object from
1133 the module namespace that we can patch out.
1134
1135 Generally local imports are to be avoided. They are sometimes done to prevent
1136 circular dependencies, for which there is *usually* a much better way to solve
1137 the problem (refactor the code) or to prevent "up front costs" by delaying the
1138 import. This can also be solved in better ways than an unconditional local
1139 import (store the module as a class or module attribute and only do the import
1140 on first use).
1141
1142 That aside there is a way to use ``mock`` to affect the results of an import.
1143 Importing fetches an *object* from the :data:`sys.modules` dictionary. Note that it
1144 fetches an *object*, which need not be a module. Importing a module for the
1145 first time results in a module object being put in ``sys.modules``, so usually
1146 when you import something you get a module back. This need not be the case
1147 however.
1148
1149 This means you can use :func:`patch.dict` to *temporarily* put a mock in place
1150 in :data:`sys.modules`. Any imports whilst this patch is active will fetch the mock.
1151 When the patch is complete (the decorated function exits, the with statement
1152 body is complete or ``patcher.stop()`` is called) then whatever was there
1153 previously will be restored safely.
1154
1155 Here's an example that mocks out the 'fooble' module.
1156
1157 >>> import sys
1158 >>> mock = Mock()
1159 >>> with patch.dict('sys.modules', {'fooble': mock}):
1160 ... import fooble
1161 ... fooble.blob()
1162 ...
1163 <Mock name='mock.blob()' id='...'>
1164 >>> assert 'fooble' not in sys.modules
1165 >>> mock.blob.assert_called_once_with()
1166
1167 As you can see the ``import fooble`` succeeds, but on exit there is no 'fooble'
1168 left in :data:`sys.modules`.
1169
1170 This also works for the ``from module import name`` form:
1171
1172 >>> mock = Mock()
1173 >>> with patch.dict('sys.modules', {'fooble': mock}):
1174 ... from fooble import blob
1175 ... blob.blip()
1176 ...
1177 <Mock name='mock.blob.blip()' id='...'>
1178 >>> mock.blob.blip.assert_called_once_with()
1179
1180 With slightly more work you can also mock package imports:
1181
1182 >>> mock = Mock()
1183 >>> modules = {'package': mock, 'package.module': mock.module}
1184 >>> with patch.dict('sys.modules', modules):
1185 ... from package.module import fooble
1186 ... fooble()
1187 ...
1188 <Mock name='mock.module.fooble()' id='...'>
1189 >>> mock.module.fooble.assert_called_once_with()
1190
1191
1192 Tracking order of calls and less verbose call assertions
1193 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1194
1195 The :class:`Mock` class allows you to track the *order* of method calls on
1196 your mock objects through the :attr:`~Mock.method_calls` attribute. This
1197 doesn't allow you to track the order of calls between separate mock objects,
1198 however we can use :attr:`~Mock.mock_calls` to achieve the same effect.
1199
1200 Because mocks track calls to child mocks in ``mock_calls``, and accessing an
1201 arbitrary attribute of a mock creates a child mock, we can create our separate
1202 mocks from a parent one. Calls to those child mock will then all be recorded,
1203 in order, in the ``mock_calls`` of the parent:
1204
1205 >>> manager = Mock()
1206 >>> mock_foo = manager.foo
1207 >>> mock_bar = manager.bar
1208
1209 >>> mock_foo.something()
1210 <Mock name='mock.foo.something()' id='...'>
1211 >>> mock_bar.other.thing()
1212 <Mock name='mock.bar.other.thing()' id='...'>
1213
1214 >>> manager.mock_calls
1215 [call.foo.something(), call.bar.other.thing()]
1216
1217 We can then assert about the calls, including the order, by comparing with
1218 the ``mock_calls`` attribute on the manager mock:
1219
1220 >>> expected_calls = [call.foo.something(), call.bar.other.thing()]
1221 >>> manager.mock_calls == expected_calls
1222 True
1223
1224 If ``patch`` is creating, and putting in place, your mocks then you can attach
1225 them to a manager mock using the :meth:`~Mock.attach_mock` method. After
1226 attaching calls will be recorded in ``mock_calls`` of the manager. ::
1227
1228 >>> manager = MagicMock()
1229 >>> with patch('mymodule.Class1') as MockClass1:
1230 ... with patch('mymodule.Class2') as MockClass2:
1231 ... manager.attach_mock(MockClass1, 'MockClass1')
1232 ... manager.attach_mock(MockClass2, 'MockClass2')
1233 ... MockClass1().foo()
1234 ... MockClass2().bar()
1235 <MagicMock name='mock.MockClass1().foo()' id='...'>
1236 <MagicMock name='mock.MockClass2().bar()' id='...'>
1237 >>> manager.mock_calls
1238 [call.MockClass1(),
1239 call.MockClass1().foo(),
1240 call.MockClass2(),
1241 call.MockClass2().bar()]
1242
1243 If many calls have been made, but you're only interested in a particular
1244 sequence of them then an alternative is to use the
1245 :meth:`~Mock.assert_has_calls` method. This takes a list of calls (constructed
1246 with the :data:`call` object). If that sequence of calls are in
1247 :attr:`~Mock.mock_calls` then the assert succeeds.
1248
1249 >>> m = MagicMock()
1250 >>> m().foo().bar().baz()
1251 <MagicMock name='mock().foo().bar().baz()' id='...'>
1252 >>> m.one().two().three()
1253 <MagicMock name='mock.one().two().three()' id='...'>
1254 >>> calls = call.one().two().three().call_list()
1255 >>> m.assert_has_calls(calls)
1256
1257 Even though the chained call ``m.one().two().three()`` aren't the only calls that
1258 have been made to the mock, the assert still succeeds.
1259
1260 Sometimes a mock may have several calls made to it, and you are only interested
1261 in asserting about *some* of those calls. You may not even care about the
1262 order. In this case you can pass ``any_order=True`` to ``assert_has_calls``:
1263
1264 >>> m = MagicMock()
1265 >>> m(1), m.two(2, 3), m.seven(7), m.fifty('50')
1266 (...)
1267 >>> calls = [call.fifty('50'), call(1), call.seven(7)]
1268 >>> m.assert_has_calls(calls, any_order=True)
1269
1270
1271 More complex argument matching
1272 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1273
1274 Using the same basic concept as :data:`ANY` we can implement matchers to do more
1275 complex assertions on objects used as arguments to mocks.
1276
1277 Suppose we expect some object to be passed to a mock that by default
1278 compares equal based on object identity (which is the Python default for user
1279 defined classes). To use :meth:`~Mock.assert_called_with` we would need to pass
1280 in the exact same object. If we are only interested in some of the attributes
1281 of this object then we can create a matcher that will check these attributes
1282 for us.
1283
1284 You can see in this example how a 'standard' call to ``assert_called_with`` isn't
1285 sufficient:
1286
1287 >>> class Foo:
1288 ... def __init__(self, a, b):
1289 ... self.a, self.b = a, b
1290 ...
1291 >>> mock = Mock(return_value=None)
1292 >>> mock(Foo(1, 2))
1293 >>> mock.assert_called_with(Foo(1, 2))
1294 Traceback (most recent call last):
1295 ...
1296 AssertionError: expected call not found.
1297 Expected: mock(<__main__.Foo object at 0x...>)
1298 Actual: mock(<__main__.Foo object at 0x...>)
1299
1300 A comparison function for our ``Foo`` class might look something like this:
1301
1302 >>> def compare(self, other):
1303 ... if not type(self) == type(other):
1304 ... return False
1305 ... if self.a != other.a:
1306 ... return False
1307 ... if self.b != other.b:
1308 ... return False
1309 ... return True
1310 ...
1311
1312 And a matcher object that can use comparison functions like this for its
1313 equality operation would look something like this:
1314
1315 >>> class Matcher:
1316 ... def __init__(self, compare, some_obj):
1317 ... self.compare = compare
1318 ... self.some_obj = some_obj
1319 ... def __eq__(self, other):
1320 ... return self.compare(self.some_obj, other)
1321 ...
1322
1323 Putting all this together:
1324
1325 >>> match_foo = Matcher(compare, Foo(1, 2))
1326 >>> mock.assert_called_with(match_foo)
1327
1328 The ``Matcher`` is instantiated with our compare function and the ``Foo`` object
1329 we want to compare against. In ``assert_called_with`` the ``Matcher`` equality
1330 method will be called, which compares the object the mock was called with
1331 against the one we created our matcher with. If they match then
1332 ``assert_called_with`` passes, and if they don't an :exc:`AssertionError` is raised:
1333
1334 >>> match_wrong = Matcher(compare, Foo(3, 4))
1335 >>> mock.assert_called_with(match_wrong)
1336 Traceback (most recent call last):
1337 ...
1338 AssertionError: Expected: ((<Matcher object at 0x...>,), {})
1339 Called with: ((<Foo object at 0x...>,), {})
1340
1341 With a bit of tweaking you could have the comparison function raise the
1342 :exc:`AssertionError` directly and provide a more useful failure message.
1343
1344 As of version 1.5, the Python testing library `PyHamcrest
1345 <https://pyhamcrest.readthedocs.io/>`_ provides similar functionality,
1346 that may be useful here, in the form of its equality matcher
1347 (`hamcrest.library.integration.match_equality
1348 <https://pyhamcrest.readthedocs.io/en/release-1.8/integration/#module-hamcrest.library.integration.match_equality>`_).