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