| 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>`_). |