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