Michael Foord | 944e02d | 2012-03-25 23:12:55 +0100 | [diff] [blame] | 1 | :mod:`unittest.mock` --- mock object library |
| 2 | ============================================ |
| 3 | |
| 4 | .. module:: unittest.mock |
| 5 | :synopsis: Mock object library. |
| 6 | .. moduleauthor:: Michael Foord <michael@python.org> |
| 7 | .. currentmodule:: unittest.mock |
| 8 | |
| 9 | .. versionadded:: 3.3 |
| 10 | |
| 11 | :mod:`unittest.mock` is a library for testing in Python. It allows you to |
| 12 | replace parts of your system under test with mock objects and make assertions |
| 13 | about how they have been used. |
| 14 | |
| 15 | `unittest.mock` provides a core :class:`Mock` class removing the need to |
| 16 | create a host of stubs throughout your test suite. After performing an |
| 17 | action, you can make assertions about which methods / attributes were used |
| 18 | and arguments they were called with. You can also specify return values and |
| 19 | set needed attributes in the normal way. |
| 20 | |
| 21 | Additionally, mock provides a :func:`patch` decorator that handles patching |
| 22 | module and class level attributes within the scope of a test, along with |
| 23 | :const:`sentinel` for creating unique objects. See the `quick guide`_ for |
| 24 | some examples of how to use :class:`Mock`, :class:`MagicMock` and |
| 25 | :func:`patch`. |
| 26 | |
| 27 | Mock is very easy to use and is designed for use with :mod:`unittest`. Mock |
| 28 | is based on the 'action -> assertion' pattern instead of `'record -> replay'` |
| 29 | used by many mocking frameworks. |
| 30 | |
| 31 | There is a backport of `unittest.mock` for earlier versions of Python, |
| 32 | available as `mock on PyPI <http://pypi.python.org/pypi/mock>`_. |
| 33 | |
| 34 | **Source code:** :source:`Lib/unittest/mock.py` |
| 35 | |
| 36 | |
| 37 | Quick Guide |
| 38 | ----------- |
| 39 | |
| 40 | :class:`Mock` and :class:`MagicMock` objects create all attributes and |
| 41 | methods as you access them and store details of how they have been used. You |
| 42 | can configure them, to specify return values or limit what attributes are |
| 43 | available, and then make assertions about how they have been used: |
| 44 | |
| 45 | >>> from unittest.mock import MagicMock |
| 46 | >>> thing = ProductionClass() |
| 47 | >>> thing.method = MagicMock(return_value=3) |
| 48 | >>> thing.method(3, 4, 5, key='value') |
| 49 | 3 |
| 50 | >>> thing.method.assert_called_with(3, 4, 5, key='value') |
| 51 | |
| 52 | :attr:`side_effect` allows you to perform side effects, including raising an |
| 53 | exception when a mock is called: |
| 54 | |
| 55 | >>> mock = Mock(side_effect=KeyError('foo')) |
| 56 | >>> mock() |
| 57 | Traceback (most recent call last): |
| 58 | ... |
| 59 | KeyError: 'foo' |
| 60 | |
| 61 | >>> values = {'a': 1, 'b': 2, 'c': 3} |
| 62 | >>> def side_effect(arg): |
| 63 | ... return values[arg] |
| 64 | ... |
| 65 | >>> mock.side_effect = side_effect |
| 66 | >>> mock('a'), mock('b'), mock('c') |
| 67 | (1, 2, 3) |
| 68 | >>> mock.side_effect = [5, 4, 3, 2, 1] |
| 69 | >>> mock(), mock(), mock() |
| 70 | (5, 4, 3) |
| 71 | |
| 72 | Mock has many other ways you can configure it and control its behaviour. For |
| 73 | example the `spec` argument configures the mock to take its specification |
| 74 | from another object. Attempting to access attributes or methods on the mock |
| 75 | that don't exist on the spec will fail with an `AttributeError`. |
| 76 | |
| 77 | The :func:`patch` decorator / context manager makes it easy to mock classes or |
| 78 | objects in a module under test. The object you specify will be replaced with a |
| 79 | mock (or other object) during the test and restored when the test ends: |
| 80 | |
| 81 | >>> from unittest.mock import patch |
| 82 | >>> @patch('module.ClassName2') |
| 83 | ... @patch('module.ClassName1') |
| 84 | ... def test(MockClass1, MockClass2): |
| 85 | ... module.ClassName1() |
| 86 | ... module.ClassName2() |
Michael Foord | 944e02d | 2012-03-25 23:12:55 +0100 | [diff] [blame] | 87 | ... assert MockClass1 is module.ClassName1 |
| 88 | ... assert MockClass2 is module.ClassName2 |
| 89 | ... assert MockClass1.called |
| 90 | ... assert MockClass2.called |
| 91 | ... |
| 92 | >>> test() |
| 93 | |
| 94 | .. note:: |
| 95 | |
| 96 | When you nest patch decorators the mocks are passed in to the decorated |
| 97 | function in the same order they applied (the normal *python* order that |
| 98 | decorators are applied). This means from the bottom up, so in the example |
| 99 | above the mock for `module.ClassName1` is passed in first. |
| 100 | |
| 101 | With `patch` it matters that you patch objects in the namespace where they |
| 102 | are looked up. This is normally straightforward, but for a quick guide |
| 103 | read :ref:`where to patch <where-to-patch>`. |
| 104 | |
| 105 | As well as a decorator `patch` can be used as a context manager in a with |
| 106 | statement: |
| 107 | |
| 108 | >>> with patch.object(ProductionClass, 'method', return_value=None) as mock_method: |
| 109 | ... thing = ProductionClass() |
| 110 | ... thing.method(1, 2, 3) |
| 111 | ... |
| 112 | >>> mock_method.assert_called_once_with(1, 2, 3) |
| 113 | |
| 114 | |
| 115 | There is also :func:`patch.dict` for setting values in a dictionary just |
| 116 | during a scope and restoring the dictionary to its original state when the test |
| 117 | ends: |
| 118 | |
| 119 | >>> foo = {'key': 'value'} |
| 120 | >>> original = foo.copy() |
| 121 | >>> with patch.dict(foo, {'newkey': 'newvalue'}, clear=True): |
| 122 | ... assert foo == {'newkey': 'newvalue'} |
| 123 | ... |
| 124 | >>> assert foo == original |
| 125 | |
| 126 | Mock supports the mocking of Python :ref:`magic methods <magic-methods>`. The |
| 127 | easiest way of using magic methods is with the :class:`MagicMock` class. It |
| 128 | allows you to do things like: |
| 129 | |
| 130 | >>> mock = MagicMock() |
| 131 | >>> mock.__str__.return_value = 'foobarbaz' |
| 132 | >>> str(mock) |
| 133 | 'foobarbaz' |
| 134 | >>> mock.__str__.assert_called_with() |
| 135 | |
| 136 | Mock allows you to assign functions (or other Mock instances) to magic methods |
| 137 | and they will be called appropriately. The `MagicMock` class is just a Mock |
| 138 | variant that has all of the magic methods pre-created for you (well, all the |
| 139 | useful ones anyway). |
| 140 | |
| 141 | The following is an example of using magic methods with the ordinary Mock |
| 142 | class: |
| 143 | |
| 144 | >>> mock = Mock() |
| 145 | >>> mock.__str__ = Mock(return_value='wheeeeee') |
| 146 | >>> str(mock) |
| 147 | 'wheeeeee' |
| 148 | |
| 149 | For ensuring that the mock objects in your tests have the same api as the |
| 150 | objects they are replacing, you can use :ref:`auto-speccing <auto-speccing>`. |
| 151 | Auto-speccing can be done through the `autospec` argument to patch, or the |
| 152 | :func:`create_autospec` function. Auto-speccing creates mock objects that |
| 153 | have the same attributes and methods as the objects they are replacing, and |
| 154 | any functions and methods (including constructors) have the same call |
| 155 | signature as the real object. |
| 156 | |
| 157 | This ensures that your mocks will fail in the same way as your production |
| 158 | code if they are used incorrectly: |
| 159 | |
| 160 | >>> from unittest.mock import create_autospec |
| 161 | >>> def function(a, b, c): |
| 162 | ... pass |
| 163 | ... |
| 164 | >>> mock_function = create_autospec(function, return_value='fishy') |
| 165 | >>> mock_function(1, 2, 3) |
| 166 | 'fishy' |
| 167 | >>> mock_function.assert_called_once_with(1, 2, 3) |
| 168 | >>> mock_function('wrong arguments') |
| 169 | Traceback (most recent call last): |
| 170 | ... |
| 171 | TypeError: <lambda>() takes exactly 3 arguments (1 given) |
| 172 | |
| 173 | `create_autospec` can also be used on classes, where it copies the signature of |
| 174 | the `__init__` method, and on callable objects where it copies the signature of |
| 175 | the `__call__` method. |
| 176 | |
| 177 | |
| 178 | |
| 179 | The Mock Class |
| 180 | -------------- |
| 181 | |
| 182 | |
| 183 | `Mock` is a flexible mock object intended to replace the use of stubs and |
| 184 | test doubles throughout your code. Mocks are callable and create attributes as |
| 185 | new mocks when you access them [#]_. Accessing the same attribute will always |
| 186 | return the same mock. Mocks record how you use them, allowing you to make |
| 187 | assertions about what your code has done to them. |
| 188 | |
| 189 | :class:`MagicMock` is a subclass of `Mock` with all the magic methods |
| 190 | pre-created and ready to use. There are also non-callable variants, useful |
| 191 | when you are mocking out objects that aren't callable: |
| 192 | :class:`NonCallableMock` and :class:`NonCallableMagicMock` |
| 193 | |
| 194 | The :func:`patch` decorators makes it easy to temporarily replace classes |
| 195 | in a particular module with a `Mock` object. By default `patch` will create |
| 196 | a `MagicMock` for you. You can specify an alternative class of `Mock` using |
| 197 | the `new_callable` argument to `patch`. |
| 198 | |
| 199 | |
| 200 | .. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs) |
| 201 | |
| 202 | Create a new `Mock` object. `Mock` takes several optional arguments |
| 203 | that specify the behaviour of the Mock object: |
| 204 | |
| 205 | * `spec`: This can be either a list of strings or an existing object (a |
| 206 | class or instance) that acts as the specification for the mock object. If |
| 207 | you pass in an object then a list of strings is formed by calling dir on |
| 208 | the object (excluding unsupported magic attributes and methods). |
| 209 | Accessing any attribute not in this list will raise an `AttributeError`. |
| 210 | |
| 211 | If `spec` is an object (rather than a list of strings) then |
| 212 | :attr:`__class__` returns the class of the spec object. This allows mocks |
| 213 | to pass `isinstance` tests. |
| 214 | |
| 215 | * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* |
| 216 | or get an attribute on the mock that isn't on the object passed as |
| 217 | `spec_set` will raise an `AttributeError`. |
| 218 | |
| 219 | * `side_effect`: A function to be called whenever the Mock is called. See |
| 220 | the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or |
| 221 | dynamically changing return values. The function is called with the same |
| 222 | arguments as the mock, and unless it returns :data:`DEFAULT`, the return |
| 223 | value of this function is used as the return value. |
| 224 | |
| 225 | Alternatively `side_effect` can be an exception class or instance. In |
| 226 | this case the exception will be raised when the mock is called. |
| 227 | |
| 228 | If `side_effect` is an iterable then each call to the mock will return |
| 229 | the next value from the iterable. |
| 230 | |
| 231 | A `side_effect` can be cleared by setting it to `None`. |
| 232 | |
| 233 | * `return_value`: The value returned when the mock is called. By default |
| 234 | this is a new Mock (created on first access). See the |
| 235 | :attr:`return_value` attribute. |
| 236 | |
| 237 | * `wraps`: Item for the mock object to wrap. If `wraps` is not None then |
| 238 | calling the Mock will pass the call through to the wrapped object |
Michael Foord | 0682a0c | 2012-04-13 20:51:20 +0100 | [diff] [blame] | 239 | (returning the real result). Attribute access on the mock will return a |
| 240 | Mock object that wraps the corresponding attribute of the wrapped |
| 241 | object (so attempting to access an attribute that doesn't exist will |
| 242 | raise an `AttributeError`). |
Michael Foord | 944e02d | 2012-03-25 23:12:55 +0100 | [diff] [blame] | 243 | |
| 244 | If the mock has an explicit `return_value` set then calls are not passed |
| 245 | to the wrapped object and the `return_value` is returned instead. |
| 246 | |
| 247 | * `name`: If the mock has a name then it will be used in the repr of the |
| 248 | mock. This can be useful for debugging. The name is propagated to child |
| 249 | mocks. |
| 250 | |
| 251 | Mocks can also be called with arbitrary keyword arguments. These will be |
| 252 | used to set attributes on the mock after it is created. See the |
| 253 | :meth:`configure_mock` method for details. |
| 254 | |
| 255 | |
| 256 | .. method:: assert_called_with(*args, **kwargs) |
| 257 | |
| 258 | This method is a convenient way of asserting that calls are made in a |
| 259 | particular way: |
| 260 | |
| 261 | >>> mock = Mock() |
| 262 | >>> mock.method(1, 2, 3, test='wow') |
| 263 | <Mock name='mock.method()' id='...'> |
| 264 | >>> mock.method.assert_called_with(1, 2, 3, test='wow') |
| 265 | |
| 266 | |
| 267 | .. method:: assert_called_once_with(*args, **kwargs) |
| 268 | |
| 269 | Assert that the mock was called exactly once and with the specified |
| 270 | arguments. |
| 271 | |
| 272 | >>> mock = Mock(return_value=None) |
| 273 | >>> mock('foo', bar='baz') |
| 274 | >>> mock.assert_called_once_with('foo', bar='baz') |
| 275 | >>> mock('foo', bar='baz') |
| 276 | >>> mock.assert_called_once_with('foo', bar='baz') |
| 277 | Traceback (most recent call last): |
| 278 | ... |
Michael Foord | 28d591c | 2012-09-28 16:15:22 +0100 | [diff] [blame] | 279 | AssertionError: Expected 'mock' to be called once. Called 2 times. |
Michael Foord | 944e02d | 2012-03-25 23:12:55 +0100 | [diff] [blame] | 280 | |
| 281 | |
| 282 | .. method:: assert_any_call(*args, **kwargs) |
| 283 | |
| 284 | assert the mock has been called with the specified arguments. |
| 285 | |
| 286 | The assert passes if the mock has *ever* been called, unlike |
| 287 | :meth:`assert_called_with` and :meth:`assert_called_once_with` that |
| 288 | only pass if the call is the most recent one. |
| 289 | |
| 290 | >>> mock = Mock(return_value=None) |
| 291 | >>> mock(1, 2, arg='thing') |
| 292 | >>> mock('some', 'thing', 'else') |
| 293 | >>> mock.assert_any_call(1, 2, arg='thing') |
| 294 | |
| 295 | |
| 296 | .. method:: assert_has_calls(calls, any_order=False) |
| 297 | |
| 298 | assert the mock has been called with the specified calls. |
| 299 | The `mock_calls` list is checked for the calls. |
| 300 | |
| 301 | If `any_order` is False (the default) then the calls must be |
| 302 | sequential. There can be extra calls before or after the |
| 303 | specified calls. |
| 304 | |
| 305 | If `any_order` is True then the calls can be in any order, but |
| 306 | they must all appear in :attr:`mock_calls`. |
| 307 | |
| 308 | >>> mock = Mock(return_value=None) |
| 309 | >>> mock(1) |
| 310 | >>> mock(2) |
| 311 | >>> mock(3) |
| 312 | >>> mock(4) |
| 313 | >>> calls = [call(2), call(3)] |
| 314 | >>> mock.assert_has_calls(calls) |
| 315 | >>> calls = [call(4), call(2), call(3)] |
| 316 | >>> mock.assert_has_calls(calls, any_order=True) |
| 317 | |
| 318 | |
| 319 | .. method:: reset_mock() |
| 320 | |
| 321 | The reset_mock method resets all the call attributes on a mock object: |
| 322 | |
| 323 | >>> mock = Mock(return_value=None) |
| 324 | >>> mock('hello') |
| 325 | >>> mock.called |
| 326 | True |
| 327 | >>> mock.reset_mock() |
| 328 | >>> mock.called |
| 329 | False |
| 330 | |
| 331 | This can be useful where you want to make a series of assertions that |
| 332 | reuse the same object. Note that `reset_mock` *doesn't* clear the |
| 333 | return value, :attr:`side_effect` or any child attributes you have |
| 334 | set using normal assignment. Child mocks and the return value mock |
| 335 | (if any) are reset as well. |
| 336 | |
| 337 | |
| 338 | .. method:: mock_add_spec(spec, spec_set=False) |
| 339 | |
| 340 | Add a spec to a mock. `spec` can either be an object or a |
| 341 | list of strings. Only attributes on the `spec` can be fetched as |
| 342 | attributes from the mock. |
| 343 | |
| 344 | If `spec_set` is `True` then only attributes on the spec can be set. |
| 345 | |
| 346 | |
| 347 | .. method:: attach_mock(mock, attribute) |
| 348 | |
| 349 | Attach a mock as an attribute of this one, replacing its name and |
| 350 | parent. Calls to the attached mock will be recorded in the |
| 351 | :attr:`method_calls` and :attr:`mock_calls` attributes of this one. |
| 352 | |
| 353 | |
| 354 | .. method:: configure_mock(**kwargs) |
| 355 | |
| 356 | Set attributes on the mock through keyword arguments. |
| 357 | |
| 358 | Attributes plus return values and side effects can be set on child |
| 359 | mocks using standard dot notation and unpacking a dictionary in the |
| 360 | method call: |
| 361 | |
| 362 | >>> mock = Mock() |
| 363 | >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} |
| 364 | >>> mock.configure_mock(**attrs) |
| 365 | >>> mock.method() |
| 366 | 3 |
| 367 | >>> mock.other() |
| 368 | Traceback (most recent call last): |
| 369 | ... |
| 370 | KeyError |
| 371 | |
| 372 | The same thing can be achieved in the constructor call to mocks: |
| 373 | |
| 374 | >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} |
| 375 | >>> mock = Mock(some_attribute='eggs', **attrs) |
| 376 | >>> mock.some_attribute |
| 377 | 'eggs' |
| 378 | >>> mock.method() |
| 379 | 3 |
| 380 | >>> mock.other() |
| 381 | Traceback (most recent call last): |
| 382 | ... |
| 383 | KeyError |
| 384 | |
| 385 | `configure_mock` exists to make it easier to do configuration |
| 386 | after the mock has been created. |
| 387 | |
| 388 | |
| 389 | .. method:: __dir__() |
| 390 | |
| 391 | `Mock` objects limit the results of `dir(some_mock)` to useful results. |
| 392 | For mocks with a `spec` this includes all the permitted attributes |
| 393 | for the mock. |
| 394 | |
| 395 | See :data:`FILTER_DIR` for what this filtering does, and how to |
| 396 | switch it off. |
| 397 | |
| 398 | |
| 399 | .. method:: _get_child_mock(**kw) |
| 400 | |
| 401 | Create the child mocks for attributes and return value. |
| 402 | By default child mocks will be the same type as the parent. |
| 403 | Subclasses of Mock may want to override this to customize the way |
| 404 | child mocks are made. |
| 405 | |
| 406 | For non-callable mocks the callable variant will be used (rather than |
| 407 | any custom subclass). |
| 408 | |
| 409 | |
| 410 | .. attribute:: called |
| 411 | |
| 412 | A boolean representing whether or not the mock object has been called: |
| 413 | |
| 414 | >>> mock = Mock(return_value=None) |
| 415 | >>> mock.called |
| 416 | False |
| 417 | >>> mock() |
| 418 | >>> mock.called |
| 419 | True |
| 420 | |
| 421 | .. attribute:: call_count |
| 422 | |
| 423 | An integer telling you how many times the mock object has been called: |
| 424 | |
| 425 | >>> mock = Mock(return_value=None) |
| 426 | >>> mock.call_count |
| 427 | 0 |
| 428 | >>> mock() |
| 429 | >>> mock() |
| 430 | >>> mock.call_count |
| 431 | 2 |
| 432 | |
| 433 | |
| 434 | .. attribute:: return_value |
| 435 | |
| 436 | Set this to configure the value returned by calling the mock: |
| 437 | |
| 438 | >>> mock = Mock() |
| 439 | >>> mock.return_value = 'fish' |
| 440 | >>> mock() |
| 441 | 'fish' |
| 442 | |
| 443 | The default return value is a mock object and you can configure it in |
| 444 | the normal way: |
| 445 | |
| 446 | >>> mock = Mock() |
| 447 | >>> mock.return_value.attribute = sentinel.Attribute |
| 448 | >>> mock.return_value() |
| 449 | <Mock name='mock()()' id='...'> |
| 450 | >>> mock.return_value.assert_called_with() |
| 451 | |
| 452 | `return_value` can also be set in the constructor: |
| 453 | |
| 454 | >>> mock = Mock(return_value=3) |
| 455 | >>> mock.return_value |
| 456 | 3 |
| 457 | >>> mock() |
| 458 | 3 |
| 459 | |
| 460 | |
| 461 | .. attribute:: side_effect |
| 462 | |
| 463 | This can either be a function to be called when the mock is called, |
| 464 | or an exception (class or instance) to be raised. |
| 465 | |
| 466 | If you pass in a function it will be called with same arguments as the |
| 467 | mock and unless the function returns the :data:`DEFAULT` singleton the |
| 468 | call to the mock will then return whatever the function returns. If the |
| 469 | function returns :data:`DEFAULT` then the mock will return its normal |
| 470 | value (from the :attr:`return_value`. |
| 471 | |
| 472 | An example of a mock that raises an exception (to test exception |
| 473 | handling of an API): |
| 474 | |
| 475 | >>> mock = Mock() |
| 476 | >>> mock.side_effect = Exception('Boom!') |
| 477 | >>> mock() |
| 478 | Traceback (most recent call last): |
| 479 | ... |
| 480 | Exception: Boom! |
| 481 | |
| 482 | Using `side_effect` to return a sequence of values: |
| 483 | |
| 484 | >>> mock = Mock() |
| 485 | >>> mock.side_effect = [3, 2, 1] |
| 486 | >>> mock(), mock(), mock() |
| 487 | (3, 2, 1) |
| 488 | |
| 489 | The `side_effect` function is called with the same arguments as the |
| 490 | mock (so it is wise for it to take arbitrary args and keyword |
| 491 | arguments) and whatever it returns is used as the return value for |
| 492 | the call. The exception is if `side_effect` returns :data:`DEFAULT`, |
| 493 | in which case the normal :attr:`return_value` is used. |
| 494 | |
| 495 | >>> mock = Mock(return_value=3) |
| 496 | >>> def side_effect(*args, **kwargs): |
| 497 | ... return DEFAULT |
| 498 | ... |
| 499 | >>> mock.side_effect = side_effect |
| 500 | >>> mock() |
| 501 | 3 |
| 502 | |
| 503 | `side_effect` can be set in the constructor. Here's an example that |
| 504 | adds one to the value the mock is called with and returns it: |
| 505 | |
| 506 | >>> side_effect = lambda value: value + 1 |
| 507 | >>> mock = Mock(side_effect=side_effect) |
| 508 | >>> mock(3) |
| 509 | 4 |
| 510 | >>> mock(-8) |
| 511 | -7 |
| 512 | |
| 513 | Setting `side_effect` to `None` clears it: |
| 514 | |
| 515 | >>> m = Mock(side_effect=KeyError, return_value=3) |
| 516 | >>> m() |
| 517 | Traceback (most recent call last): |
| 518 | ... |
| 519 | KeyError |
| 520 | >>> m.side_effect = None |
| 521 | >>> m() |
| 522 | 3 |
| 523 | |
| 524 | |
| 525 | .. attribute:: call_args |
| 526 | |
| 527 | This is either `None` (if the mock hasn't been called), or the |
| 528 | arguments that the mock was last called with. This will be in the |
| 529 | form of a tuple: the first member is any ordered arguments the mock |
| 530 | was called with (or an empty tuple) and the second member is any |
| 531 | keyword arguments (or an empty dictionary). |
| 532 | |
| 533 | >>> mock = Mock(return_value=None) |
| 534 | >>> print mock.call_args |
| 535 | None |
| 536 | >>> mock() |
| 537 | >>> mock.call_args |
| 538 | call() |
| 539 | >>> mock.call_args == () |
| 540 | True |
| 541 | >>> mock(3, 4) |
| 542 | >>> mock.call_args |
| 543 | call(3, 4) |
| 544 | >>> mock.call_args == ((3, 4),) |
| 545 | True |
| 546 | >>> mock(3, 4, 5, key='fish', next='w00t!') |
| 547 | >>> mock.call_args |
| 548 | call(3, 4, 5, key='fish', next='w00t!') |
| 549 | |
| 550 | `call_args`, along with members of the lists :attr:`call_args_list`, |
| 551 | :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects. |
| 552 | These are tuples, so they can be unpacked to get at the individual |
| 553 | arguments and make more complex assertions. See |
| 554 | :ref:`calls as tuples <calls-as-tuples>`. |
| 555 | |
| 556 | |
| 557 | .. attribute:: call_args_list |
| 558 | |
| 559 | This is a list of all the calls made to the mock object in sequence |
| 560 | (so the length of the list is the number of times it has been |
| 561 | called). Before any calls have been made it is an empty list. The |
| 562 | :data:`call` object can be used for conveniently constructing lists of |
| 563 | calls to compare with `call_args_list`. |
| 564 | |
| 565 | >>> mock = Mock(return_value=None) |
| 566 | >>> mock() |
| 567 | >>> mock(3, 4) |
| 568 | >>> mock(key='fish', next='w00t!') |
| 569 | >>> mock.call_args_list |
| 570 | [call(), call(3, 4), call(key='fish', next='w00t!')] |
| 571 | >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] |
| 572 | >>> mock.call_args_list == expected |
| 573 | True |
| 574 | |
| 575 | Members of `call_args_list` are :data:`call` objects. These can be |
| 576 | unpacked as tuples to get at the individual arguments. See |
| 577 | :ref:`calls as tuples <calls-as-tuples>`. |
| 578 | |
| 579 | |
| 580 | .. attribute:: method_calls |
| 581 | |
| 582 | As well as tracking calls to themselves, mocks also track calls to |
| 583 | methods and attributes, and *their* methods and attributes: |
| 584 | |
| 585 | >>> mock = Mock() |
| 586 | >>> mock.method() |
| 587 | <Mock name='mock.method()' id='...'> |
| 588 | >>> mock.property.method.attribute() |
| 589 | <Mock name='mock.property.method.attribute()' id='...'> |
| 590 | >>> mock.method_calls |
| 591 | [call.method(), call.property.method.attribute()] |
| 592 | |
| 593 | Members of `method_calls` are :data:`call` objects. These can be |
| 594 | unpacked as tuples to get at the individual arguments. See |
| 595 | :ref:`calls as tuples <calls-as-tuples>`. |
| 596 | |
| 597 | |
| 598 | .. attribute:: mock_calls |
| 599 | |
| 600 | `mock_calls` records *all* calls to the mock object, its methods, magic |
| 601 | methods *and* return value mocks. |
| 602 | |
| 603 | >>> mock = MagicMock() |
| 604 | >>> result = mock(1, 2, 3) |
| 605 | >>> mock.first(a=3) |
| 606 | <MagicMock name='mock.first()' id='...'> |
| 607 | >>> mock.second() |
| 608 | <MagicMock name='mock.second()' id='...'> |
| 609 | >>> int(mock) |
| 610 | 1 |
| 611 | >>> result(1) |
| 612 | <MagicMock name='mock()()' id='...'> |
| 613 | >>> expected = [call(1, 2, 3), call.first(a=3), call.second(), |
| 614 | ... call.__int__(), call()(1)] |
| 615 | >>> mock.mock_calls == expected |
| 616 | True |
| 617 | |
| 618 | Members of `mock_calls` are :data:`call` objects. These can be |
| 619 | unpacked as tuples to get at the individual arguments. See |
| 620 | :ref:`calls as tuples <calls-as-tuples>`. |
| 621 | |
| 622 | |
| 623 | .. attribute:: __class__ |
| 624 | |
| 625 | Normally the `__class__` attribute of an object will return its type. |
| 626 | For a mock object with a `spec` `__class__` returns the spec class |
| 627 | instead. This allows mock objects to pass `isinstance` tests for the |
| 628 | object they are replacing / masquerading as: |
| 629 | |
| 630 | >>> mock = Mock(spec=3) |
| 631 | >>> isinstance(mock, int) |
| 632 | True |
| 633 | |
| 634 | `__class__` is assignable to, this allows a mock to pass an |
| 635 | `isinstance` check without forcing you to use a spec: |
| 636 | |
| 637 | >>> mock = Mock() |
| 638 | >>> mock.__class__ = dict |
| 639 | >>> isinstance(mock, dict) |
| 640 | True |
| 641 | |
| 642 | .. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs) |
| 643 | |
| 644 | A non-callable version of `Mock`. The constructor parameters have the same |
| 645 | meaning of `Mock`, with the exception of `return_value` and `side_effect` |
| 646 | which have no meaning on a non-callable mock. |
| 647 | |
| 648 | Mock objects that use a class or an instance as a `spec` or `spec_set` are able |
| 649 | to pass `isintance` tests: |
| 650 | |
| 651 | >>> mock = Mock(spec=SomeClass) |
| 652 | >>> isinstance(mock, SomeClass) |
| 653 | True |
| 654 | >>> mock = Mock(spec_set=SomeClass()) |
| 655 | >>> isinstance(mock, SomeClass) |
| 656 | True |
| 657 | |
| 658 | The `Mock` classes have support for mocking magic methods. See :ref:`magic |
| 659 | methods <magic-methods>` for the full details. |
| 660 | |
| 661 | The mock classes and the :func:`patch` decorators all take arbitrary keyword |
| 662 | arguments for configuration. For the `patch` decorators the keywords are |
| 663 | passed to the constructor of the mock being created. The keyword arguments |
| 664 | are for configuring attributes of the mock: |
| 665 | |
| 666 | >>> m = MagicMock(attribute=3, other='fish') |
| 667 | >>> m.attribute |
| 668 | 3 |
| 669 | >>> m.other |
| 670 | 'fish' |
| 671 | |
| 672 | The return value and side effect of child mocks can be set in the same way, |
| 673 | using dotted notation. As you can't use dotted names directly in a call you |
| 674 | have to create a dictionary and unpack it using `**`: |
| 675 | |
| 676 | >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} |
| 677 | >>> mock = Mock(some_attribute='eggs', **attrs) |
| 678 | >>> mock.some_attribute |
| 679 | 'eggs' |
| 680 | >>> mock.method() |
| 681 | 3 |
| 682 | >>> mock.other() |
| 683 | Traceback (most recent call last): |
| 684 | ... |
| 685 | KeyError |
| 686 | |
| 687 | |
| 688 | .. class:: PropertyMock(*args, **kwargs) |
| 689 | |
| 690 | A mock intended to be used as a property, or other descriptor, on a class. |
| 691 | `PropertyMock` provides `__get__` and `__set__` methods so you can specify |
| 692 | a return value when it is fetched. |
| 693 | |
| 694 | Fetching a `PropertyMock` instance from an object calls the mock, with |
| 695 | no args. Setting it calls the mock with the value being set. |
| 696 | |
| 697 | >>> class Foo(object): |
| 698 | ... @property |
| 699 | ... def foo(self): |
| 700 | ... return 'something' |
| 701 | ... @foo.setter |
| 702 | ... def foo(self, value): |
| 703 | ... pass |
| 704 | ... |
| 705 | >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo: |
| 706 | ... mock_foo.return_value = 'mockity-mock' |
| 707 | ... this_foo = Foo() |
| 708 | ... print this_foo.foo |
| 709 | ... this_foo.foo = 6 |
| 710 | ... |
| 711 | mockity-mock |
| 712 | >>> mock_foo.mock_calls |
| 713 | [call(), call(6)] |
| 714 | |
Michael Foord | c287062 | 2012-04-13 16:57:22 +0100 | [diff] [blame] | 715 | Because of the way mock attributes are stored you can't directly attach a |
| 716 | `PropertyMock` to a mock object. Instead you can attach it to the mock type |
| 717 | object:: |
| 718 | |
| 719 | >>> m = MagicMock() |
| 720 | >>> p = PropertyMock(return_value=3) |
| 721 | >>> type(m).foo = p |
| 722 | >>> m.foo |
| 723 | 3 |
| 724 | >>> p.assert_called_once_with() |
| 725 | |
Michael Foord | 944e02d | 2012-03-25 23:12:55 +0100 | [diff] [blame] | 726 | |
| 727 | Calling |
| 728 | ~~~~~~~ |
| 729 | |
| 730 | Mock objects are callable. The call will return the value set as the |
| 731 | :attr:`~Mock.return_value` attribute. The default return value is a new Mock |
| 732 | object; it is created the first time the return value is accessed (either |
| 733 | explicitly or by calling the Mock) - but it is stored and the same one |
| 734 | returned each time. |
| 735 | |
| 736 | Calls made to the object will be recorded in the attributes |
| 737 | like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`. |
| 738 | |
| 739 | If :attr:`~Mock.side_effect` is set then it will be called after the call has |
| 740 | been recorded, so if `side_effect` raises an exception the call is still |
| 741 | recorded. |
| 742 | |
| 743 | The simplest way to make a mock raise an exception when called is to make |
| 744 | :attr:`~Mock.side_effect` an exception class or instance: |
| 745 | |
| 746 | >>> m = MagicMock(side_effect=IndexError) |
| 747 | >>> m(1, 2, 3) |
| 748 | Traceback (most recent call last): |
| 749 | ... |
| 750 | IndexError |
| 751 | >>> m.mock_calls |
| 752 | [call(1, 2, 3)] |
| 753 | >>> m.side_effect = KeyError('Bang!') |
| 754 | >>> m('two', 'three', 'four') |
| 755 | Traceback (most recent call last): |
| 756 | ... |
| 757 | KeyError: 'Bang!' |
| 758 | >>> m.mock_calls |
| 759 | [call(1, 2, 3), call('two', 'three', 'four')] |
| 760 | |
| 761 | If `side_effect` is a function then whatever that function returns is what |
| 762 | calls to the mock return. The `side_effect` function is called with the |
| 763 | same arguments as the mock. This allows you to vary the return value of the |
| 764 | call dynamically, based on the input: |
| 765 | |
| 766 | >>> def side_effect(value): |
| 767 | ... return value + 1 |
| 768 | ... |
| 769 | >>> m = MagicMock(side_effect=side_effect) |
| 770 | >>> m(1) |
| 771 | 2 |
| 772 | >>> m(2) |
| 773 | 3 |
| 774 | >>> m.mock_calls |
| 775 | [call(1), call(2)] |
| 776 | |
| 777 | If you want the mock to still return the default return value (a new mock), or |
| 778 | any set return value, then there are two ways of doing this. Either return |
| 779 | `mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`: |
| 780 | |
| 781 | >>> m = MagicMock() |
| 782 | >>> def side_effect(*args, **kwargs): |
| 783 | ... return m.return_value |
| 784 | ... |
| 785 | >>> m.side_effect = side_effect |
| 786 | >>> m.return_value = 3 |
| 787 | >>> m() |
| 788 | 3 |
| 789 | >>> def side_effect(*args, **kwargs): |
| 790 | ... return DEFAULT |
| 791 | ... |
| 792 | >>> m.side_effect = side_effect |
| 793 | >>> m() |
| 794 | 3 |
| 795 | |
| 796 | To remove a `side_effect`, and return to the default behaviour, set the |
| 797 | `side_effect` to `None`: |
| 798 | |
| 799 | >>> m = MagicMock(return_value=6) |
| 800 | >>> def side_effect(*args, **kwargs): |
| 801 | ... return 3 |
| 802 | ... |
| 803 | >>> m.side_effect = side_effect |
| 804 | >>> m() |
| 805 | 3 |
| 806 | >>> m.side_effect = None |
| 807 | >>> m() |
| 808 | 6 |
| 809 | |
| 810 | The `side_effect` can also be any iterable object. Repeated calls to the mock |
| 811 | will return values from the iterable (until the iterable is exhausted and |
| 812 | a `StopIteration` is raised): |
| 813 | |
| 814 | >>> m = MagicMock(side_effect=[1, 2, 3]) |
| 815 | >>> m() |
| 816 | 1 |
| 817 | >>> m() |
| 818 | 2 |
| 819 | >>> m() |
| 820 | 3 |
| 821 | >>> m() |
| 822 | Traceback (most recent call last): |
| 823 | ... |
| 824 | StopIteration |
| 825 | |
Michael Foord | 2cd4873 | 2012-04-21 15:52:11 +0100 | [diff] [blame] | 826 | If any members of the iterable are exceptions they will be raised instead of |
| 827 | returned:: |
| 828 | |
| 829 | >>> iterable = (33, ValueError, 66) |
| 830 | >>> m = MagicMock(side_effect=iterable) |
| 831 | >>> m() |
| 832 | 33 |
| 833 | >>> m() |
| 834 | Traceback (most recent call last): |
| 835 | ... |
| 836 | ValueError |
| 837 | >>> m() |
| 838 | 66 |
| 839 | |
Michael Foord | 944e02d | 2012-03-25 23:12:55 +0100 | [diff] [blame] | 840 | |
| 841 | .. _deleting-attributes: |
| 842 | |
| 843 | Deleting Attributes |
| 844 | ~~~~~~~~~~~~~~~~~~~ |
| 845 | |
| 846 | Mock objects create attributes on demand. This allows them to pretend to be |
| 847 | objects of any type. |
| 848 | |
| 849 | You may want a mock object to return `False` to a `hasattr` call, or raise an |
| 850 | `AttributeError` when an attribute is fetched. You can do this by providing |
| 851 | an object as a `spec` for a mock, but that isn't always convenient. |
| 852 | |
| 853 | You "block" attributes by deleting them. Once deleted, accessing an attribute |
| 854 | will raise an `AttributeError`. |
| 855 | |
| 856 | >>> mock = MagicMock() |
| 857 | >>> hasattr(mock, 'm') |
| 858 | True |
| 859 | >>> del mock.m |
| 860 | >>> hasattr(mock, 'm') |
| 861 | False |
| 862 | >>> del mock.f |
| 863 | >>> mock.f |
| 864 | Traceback (most recent call last): |
| 865 | ... |
| 866 | AttributeError: f |
| 867 | |
| 868 | |
| 869 | Attaching Mocks as Attributes |
| 870 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 871 | |
| 872 | When you attach a mock as an attribute of another mock (or as the return |
| 873 | value) it becomes a "child" of that mock. Calls to the child are recorded in |
| 874 | the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the |
| 875 | parent. This is useful for configuring child mocks and then attaching them to |
| 876 | the parent, or for attaching mocks to a parent that records all calls to the |
| 877 | children and allows you to make assertions about the order of calls between |
| 878 | mocks: |
| 879 | |
| 880 | >>> parent = MagicMock() |
| 881 | >>> child1 = MagicMock(return_value=None) |
| 882 | >>> child2 = MagicMock(return_value=None) |
| 883 | >>> parent.child1 = child1 |
| 884 | >>> parent.child2 = child2 |
| 885 | >>> child1(1) |
| 886 | >>> child2(2) |
| 887 | >>> parent.mock_calls |
| 888 | [call.child1(1), call.child2(2)] |
| 889 | |
| 890 | The exception to this is if the mock has a name. This allows you to prevent |
| 891 | the "parenting" if for some reason you don't want it to happen. |
| 892 | |
| 893 | >>> mock = MagicMock() |
| 894 | >>> not_a_child = MagicMock(name='not-a-child') |
| 895 | >>> mock.attribute = not_a_child |
| 896 | >>> mock.attribute() |
| 897 | <MagicMock name='not-a-child()' id='...'> |
| 898 | >>> mock.mock_calls |
| 899 | [] |
| 900 | |
| 901 | Mocks created for you by :func:`patch` are automatically given names. To |
| 902 | attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock` |
| 903 | method: |
| 904 | |
| 905 | >>> thing1 = object() |
| 906 | >>> thing2 = object() |
| 907 | >>> parent = MagicMock() |
| 908 | >>> with patch('__main__.thing1', return_value=None) as child1: |
| 909 | ... with patch('__main__.thing2', return_value=None) as child2: |
| 910 | ... parent.attach_mock(child1, 'child1') |
| 911 | ... parent.attach_mock(child2, 'child2') |
| 912 | ... child1('one') |
| 913 | ... child2('two') |
| 914 | ... |
| 915 | >>> parent.mock_calls |
| 916 | [call.child1('one'), call.child2('two')] |
| 917 | |
| 918 | |
| 919 | .. [#] The only exceptions are magic methods and attributes (those that have |
| 920 | leading and trailing double underscores). Mock doesn't create these but |
| 921 | instead of raises an ``AttributeError``. This is because the interpreter |
| 922 | will often implicitly request these methods, and gets *very* confused to |
| 923 | get a new Mock object when it expects a magic method. If you need magic |
| 924 | method support see :ref:`magic methods <magic-methods>`. |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 925 | |
| 926 | |
| 927 | The patchers |
| 928 | ============ |
| 929 | |
| 930 | The patch decorators are used for patching objects only within the scope of |
| 931 | the function they decorate. They automatically handle the unpatching for you, |
| 932 | even if exceptions are raised. All of these functions can also be used in with |
| 933 | statements or as class decorators. |
| 934 | |
| 935 | |
| 936 | patch |
| 937 | ----- |
| 938 | |
| 939 | .. note:: |
| 940 | |
| 941 | `patch` is straightforward to use. The key is to do the patching in the |
| 942 | right namespace. See the section `where to patch`_. |
| 943 | |
| 944 | .. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) |
| 945 | |
| 946 | `patch` acts as a function decorator, class decorator or a context |
| 947 | manager. Inside the body of the function or with statement, the `target` |
Michael Foord | 54b3db8 | 2012-03-28 15:08:08 +0100 | [diff] [blame] | 948 | is patched with a `new` object. When the function/with statement exits |
| 949 | the patch is undone. |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 950 | |
Michael Foord | 54b3db8 | 2012-03-28 15:08:08 +0100 | [diff] [blame] | 951 | If `new` is omitted, then the target is replaced with a |
| 952 | :class:`MagicMock`. If `patch` is used as a decorator and `new` is |
| 953 | omitted, the created mock is passed in as an extra argument to the |
| 954 | decorated function. If `patch` is used as a context manager the created |
| 955 | mock is returned by the context manager. |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 956 | |
Michael Foord | 54b3db8 | 2012-03-28 15:08:08 +0100 | [diff] [blame] | 957 | `target` should be a string in the form `'package.module.ClassName'`. The |
| 958 | `target` is imported and the specified object replaced with the `new` |
| 959 | object, so the `target` must be importable from the environment you are |
| 960 | calling `patch` from. The target is imported when the decorated function |
| 961 | is executed, not at decoration time. |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 962 | |
| 963 | The `spec` and `spec_set` keyword arguments are passed to the `MagicMock` |
| 964 | if patch is creating one for you. |
| 965 | |
| 966 | In addition you can pass `spec=True` or `spec_set=True`, which causes |
| 967 | patch to pass in the object being mocked as the spec/spec_set object. |
| 968 | |
| 969 | `new_callable` allows you to specify a different class, or callable object, |
| 970 | that will be called to create the `new` object. By default `MagicMock` is |
| 971 | used. |
| 972 | |
| 973 | A more powerful form of `spec` is `autospec`. If you set `autospec=True` |
| 974 | then the mock with be created with a spec from the object being replaced. |
| 975 | All attributes of the mock will also have the spec of the corresponding |
| 976 | attribute of the object being replaced. Methods and functions being mocked |
| 977 | will have their arguments checked and will raise a `TypeError` if they are |
| 978 | called with the wrong signature. For mocks |
| 979 | replacing a class, their return value (the 'instance') will have the same |
| 980 | spec as the class. See the :func:`create_autospec` function and |
| 981 | :ref:`auto-speccing`. |
| 982 | |
| 983 | Instead of `autospec=True` you can pass `autospec=some_object` to use an |
| 984 | arbitrary object as the spec instead of the one being replaced. |
| 985 | |
| 986 | By default `patch` will fail to replace attributes that don't exist. If |
| 987 | you pass in `create=True`, and the attribute doesn't exist, patch will |
| 988 | create the attribute for you when the patched function is called, and |
| 989 | delete it again afterwards. This is useful for writing tests against |
| 990 | attributes that your production code creates at runtime. It is off by by |
| 991 | default because it can be dangerous. With it switched on you can write |
| 992 | passing tests against APIs that don't actually exist! |
| 993 | |
| 994 | Patch can be used as a `TestCase` class decorator. It works by |
| 995 | decorating each test method in the class. This reduces the boilerplate |
| 996 | code when your test methods share a common patchings set. `patch` finds |
| 997 | tests by looking for method names that start with `patch.TEST_PREFIX`. |
| 998 | By default this is `test`, which matches the way `unittest` finds tests. |
| 999 | You can specify an alternative prefix by setting `patch.TEST_PREFIX`. |
| 1000 | |
| 1001 | Patch can be used as a context manager, with the with statement. Here the |
| 1002 | patching applies to the indented block after the with statement. If you |
| 1003 | use "as" then the patched object will be bound to the name after the |
| 1004 | "as"; very useful if `patch` is creating a mock object for you. |
| 1005 | |
| 1006 | `patch` takes arbitrary keyword arguments. These will be passed to |
| 1007 | the `Mock` (or `new_callable`) on construction. |
| 1008 | |
| 1009 | `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are |
| 1010 | available for alternate use-cases. |
| 1011 | |
Michael Foord | 9015536 | 2012-03-28 15:32:08 +0100 | [diff] [blame] | 1012 | `patch` as function decorator, creating the mock for you and passing it into |
| 1013 | the decorated function: |
| 1014 | |
| 1015 | >>> @patch('__main__.SomeClass') |
Michael Foord | 324b58b | 2012-03-28 15:49:08 +0100 | [diff] [blame] | 1016 | ... def function(normal_argument, mock_class): |
Michael Foord | 9015536 | 2012-03-28 15:32:08 +0100 | [diff] [blame] | 1017 | ... print(mock_class is SomeClass) |
| 1018 | ... |
Michael Foord | 324b58b | 2012-03-28 15:49:08 +0100 | [diff] [blame] | 1019 | >>> function(None) |
Michael Foord | 9015536 | 2012-03-28 15:32:08 +0100 | [diff] [blame] | 1020 | True |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 1021 | |
| 1022 | Patching a class replaces the class with a `MagicMock` *instance*. If the |
| 1023 | class is instantiated in the code under test then it will be the |
| 1024 | :attr:`~Mock.return_value` of the mock that will be used. |
| 1025 | |
| 1026 | If the class is instantiated multiple times you could use |
| 1027 | :attr:`~Mock.side_effect` to return a new mock each time. Alternatively you |
| 1028 | can set the `return_value` to be anything you want. |
| 1029 | |
| 1030 | To configure return values on methods of *instances* on the patched class |
| 1031 | you must do this on the `return_value`. For example: |
| 1032 | |
| 1033 | >>> class Class(object): |
| 1034 | ... def method(self): |
| 1035 | ... pass |
| 1036 | ... |
| 1037 | >>> with patch('__main__.Class') as MockClass: |
| 1038 | ... instance = MockClass.return_value |
| 1039 | ... instance.method.return_value = 'foo' |
| 1040 | ... assert Class() is instance |
| 1041 | ... assert Class().method() == 'foo' |
| 1042 | ... |
| 1043 | |
| 1044 | If you use `spec` or `spec_set` and `patch` is replacing a *class*, then the |
| 1045 | return value of the created mock will have the same spec. |
| 1046 | |
| 1047 | >>> Original = Class |
| 1048 | >>> patcher = patch('__main__.Class', spec=True) |
| 1049 | >>> MockClass = patcher.start() |
| 1050 | >>> instance = MockClass() |
| 1051 | >>> assert isinstance(instance, Original) |
| 1052 | >>> patcher.stop() |
| 1053 | |
| 1054 | The `new_callable` argument is useful where you want to use an alternative |
| 1055 | class to the default :class:`MagicMock` for the created mock. For example, if |
| 1056 | you wanted a :class:`NonCallableMock` to be used: |
| 1057 | |
| 1058 | >>> thing = object() |
| 1059 | >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing: |
| 1060 | ... assert thing is mock_thing |
| 1061 | ... thing() |
| 1062 | ... |
| 1063 | Traceback (most recent call last): |
| 1064 | ... |
| 1065 | TypeError: 'NonCallableMock' object is not callable |
| 1066 | |
| 1067 | Another use case might be to replace an object with a `StringIO` instance: |
| 1068 | |
| 1069 | >>> from StringIO import StringIO |
| 1070 | >>> def foo(): |
| 1071 | ... print 'Something' |
| 1072 | ... |
| 1073 | >>> @patch('sys.stdout', new_callable=StringIO) |
| 1074 | ... def test(mock_stdout): |
| 1075 | ... foo() |
| 1076 | ... assert mock_stdout.getvalue() == 'Something\n' |
| 1077 | ... |
| 1078 | >>> test() |
| 1079 | |
| 1080 | When `patch` is creating a mock for you, it is common that the first thing |
| 1081 | you need to do is to configure the mock. Some of that configuration can be done |
| 1082 | in the call to patch. Any arbitrary keywords you pass into the call will be |
| 1083 | used to set attributes on the created mock: |
| 1084 | |
| 1085 | >>> patcher = patch('__main__.thing', first='one', second='two') |
| 1086 | >>> mock_thing = patcher.start() |
| 1087 | >>> mock_thing.first |
| 1088 | 'one' |
| 1089 | >>> mock_thing.second |
| 1090 | 'two' |
| 1091 | |
| 1092 | As well as attributes on the created mock attributes, like the |
| 1093 | :attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can |
| 1094 | also be configured. These aren't syntactically valid to pass in directly as |
| 1095 | keyword arguments, but a dictionary with these as keys can still be expanded |
| 1096 | into a `patch` call using `**`: |
| 1097 | |
| 1098 | >>> config = {'method.return_value': 3, 'other.side_effect': KeyError} |
| 1099 | >>> patcher = patch('__main__.thing', **config) |
| 1100 | >>> mock_thing = patcher.start() |
| 1101 | >>> mock_thing.method() |
| 1102 | 3 |
| 1103 | >>> mock_thing.other() |
| 1104 | Traceback (most recent call last): |
| 1105 | ... |
| 1106 | KeyError |
| 1107 | |
| 1108 | |
| 1109 | patch.object |
| 1110 | ------------ |
| 1111 | |
| 1112 | .. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) |
| 1113 | |
| 1114 | patch the named member (`attribute`) on an object (`target`) with a mock |
| 1115 | object. |
| 1116 | |
| 1117 | `patch.object` can be used as a decorator, class decorator or a context |
| 1118 | manager. Arguments `new`, `spec`, `create`, `spec_set`, `autospec` and |
| 1119 | `new_callable` have the same meaning as for `patch`. Like `patch`, |
| 1120 | `patch.object` takes arbitrary keyword arguments for configuring the mock |
| 1121 | object it creates. |
| 1122 | |
| 1123 | When used as a class decorator `patch.object` honours `patch.TEST_PREFIX` |
| 1124 | for choosing which methods to wrap. |
| 1125 | |
| 1126 | You can either call `patch.object` with three arguments or two arguments. The |
| 1127 | three argument form takes the object to be patched, the attribute name and the |
| 1128 | object to replace the attribute with. |
| 1129 | |
| 1130 | When calling with the two argument form you omit the replacement object, and a |
| 1131 | mock is created for you and passed in as an extra argument to the decorated |
| 1132 | function: |
| 1133 | |
| 1134 | >>> @patch.object(SomeClass, 'class_method') |
| 1135 | ... def test(mock_method): |
| 1136 | ... SomeClass.class_method(3) |
| 1137 | ... mock_method.assert_called_with(3) |
| 1138 | ... |
| 1139 | >>> test() |
| 1140 | |
| 1141 | `spec`, `create` and the other arguments to `patch.object` have the same |
| 1142 | meaning as they do for `patch`. |
| 1143 | |
| 1144 | |
| 1145 | patch.dict |
| 1146 | ---------- |
| 1147 | |
| 1148 | .. function:: patch.dict(in_dict, values=(), clear=False, **kwargs) |
| 1149 | |
| 1150 | Patch a dictionary, or dictionary like object, and restore the dictionary |
| 1151 | to its original state after the test. |
| 1152 | |
| 1153 | `in_dict` can be a dictionary or a mapping like container. If it is a |
| 1154 | mapping then it must at least support getting, setting and deleting items |
| 1155 | plus iterating over keys. |
| 1156 | |
| 1157 | `in_dict` can also be a string specifying the name of the dictionary, which |
| 1158 | will then be fetched by importing it. |
| 1159 | |
| 1160 | `values` can be a dictionary of values to set in the dictionary. `values` |
| 1161 | can also be an iterable of `(key, value)` pairs. |
| 1162 | |
| 1163 | If `clear` is True then the dictionary will be cleared before the new |
| 1164 | values are set. |
| 1165 | |
| 1166 | `patch.dict` can also be called with arbitrary keyword arguments to set |
| 1167 | values in the dictionary. |
| 1168 | |
| 1169 | `patch.dict` can be used as a context manager, decorator or class |
| 1170 | decorator. When used as a class decorator `patch.dict` honours |
| 1171 | `patch.TEST_PREFIX` for choosing which methods to wrap. |
| 1172 | |
| 1173 | `patch.dict` can be used to add members to a dictionary, or simply let a test |
| 1174 | change a dictionary, and ensure the dictionary is restored when the test |
| 1175 | ends. |
| 1176 | |
| 1177 | >>> foo = {} |
| 1178 | >>> with patch.dict(foo, {'newkey': 'newvalue'}): |
| 1179 | ... assert foo == {'newkey': 'newvalue'} |
| 1180 | ... |
| 1181 | >>> assert foo == {} |
| 1182 | |
| 1183 | >>> import os |
| 1184 | >>> with patch.dict('os.environ', {'newkey': 'newvalue'}): |
| 1185 | ... print os.environ['newkey'] |
| 1186 | ... |
| 1187 | newvalue |
| 1188 | >>> assert 'newkey' not in os.environ |
| 1189 | |
| 1190 | Keywords can be used in the `patch.dict` call to set values in the dictionary: |
| 1191 | |
| 1192 | >>> mymodule = MagicMock() |
| 1193 | >>> mymodule.function.return_value = 'fish' |
| 1194 | >>> with patch.dict('sys.modules', mymodule=mymodule): |
| 1195 | ... import mymodule |
| 1196 | ... mymodule.function('some', 'args') |
| 1197 | ... |
| 1198 | 'fish' |
| 1199 | |
| 1200 | `patch.dict` can be used with dictionary like objects that aren't actually |
| 1201 | dictionaries. At the very minimum they must support item getting, setting, |
| 1202 | deleting and either iteration or membership test. This corresponds to the |
| 1203 | magic methods `__getitem__`, `__setitem__`, `__delitem__` and either |
| 1204 | `__iter__` or `__contains__`. |
| 1205 | |
| 1206 | >>> class Container(object): |
| 1207 | ... def __init__(self): |
| 1208 | ... self.values = {} |
| 1209 | ... def __getitem__(self, name): |
| 1210 | ... return self.values[name] |
| 1211 | ... def __setitem__(self, name, value): |
| 1212 | ... self.values[name] = value |
| 1213 | ... def __delitem__(self, name): |
| 1214 | ... del self.values[name] |
| 1215 | ... def __iter__(self): |
| 1216 | ... return iter(self.values) |
| 1217 | ... |
| 1218 | >>> thing = Container() |
| 1219 | >>> thing['one'] = 1 |
| 1220 | >>> with patch.dict(thing, one=2, two=3): |
| 1221 | ... assert thing['one'] == 2 |
| 1222 | ... assert thing['two'] == 3 |
| 1223 | ... |
| 1224 | >>> assert thing['one'] == 1 |
| 1225 | >>> assert list(thing) == ['one'] |
| 1226 | |
| 1227 | |
| 1228 | patch.multiple |
| 1229 | -------------- |
| 1230 | |
| 1231 | .. function:: patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) |
| 1232 | |
| 1233 | Perform multiple patches in a single call. It takes the object to be |
| 1234 | patched (either as an object or a string to fetch the object by importing) |
| 1235 | and keyword arguments for the patches:: |
| 1236 | |
| 1237 | with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'): |
| 1238 | ... |
| 1239 | |
| 1240 | Use :data:`DEFAULT` as the value if you want `patch.multiple` to create |
| 1241 | mocks for you. In this case the created mocks are passed into a decorated |
| 1242 | function by keyword, and a dictionary is returned when `patch.multiple` is |
| 1243 | used as a context manager. |
| 1244 | |
| 1245 | `patch.multiple` can be used as a decorator, class decorator or a context |
| 1246 | manager. The arguments `spec`, `spec_set`, `create`, `autospec` and |
| 1247 | `new_callable` have the same meaning as for `patch`. These arguments will |
| 1248 | be applied to *all* patches done by `patch.multiple`. |
| 1249 | |
| 1250 | When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX` |
| 1251 | for choosing which methods to wrap. |
| 1252 | |
| 1253 | If you want `patch.multiple` to create mocks for you, then you can use |
| 1254 | :data:`DEFAULT` as the value. If you use `patch.multiple` as a decorator |
| 1255 | then the created mocks are passed into the decorated function by keyword. |
| 1256 | |
| 1257 | >>> thing = object() |
| 1258 | >>> other = object() |
| 1259 | |
| 1260 | >>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) |
| 1261 | ... def test_function(thing, other): |
| 1262 | ... assert isinstance(thing, MagicMock) |
| 1263 | ... assert isinstance(other, MagicMock) |
| 1264 | ... |
| 1265 | >>> test_function() |
| 1266 | |
| 1267 | `patch.multiple` can be nested with other `patch` decorators, but put arguments |
| 1268 | passed by keyword *after* any of the standard arguments created by `patch`: |
| 1269 | |
| 1270 | >>> @patch('sys.exit') |
| 1271 | ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) |
| 1272 | ... def test_function(mock_exit, other, thing): |
| 1273 | ... assert 'other' in repr(other) |
| 1274 | ... assert 'thing' in repr(thing) |
| 1275 | ... assert 'exit' in repr(mock_exit) |
| 1276 | ... |
| 1277 | >>> test_function() |
| 1278 | |
| 1279 | If `patch.multiple` is used as a context manager, the value returned by the |
| 1280 | context manger is a dictionary where created mocks are keyed by name: |
| 1281 | |
| 1282 | >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values: |
| 1283 | ... assert 'other' in repr(values['other']) |
| 1284 | ... assert 'thing' in repr(values['thing']) |
| 1285 | ... assert values['thing'] is thing |
| 1286 | ... assert values['other'] is other |
| 1287 | ... |
| 1288 | |
| 1289 | |
| 1290 | .. _start-and-stop: |
| 1291 | |
| 1292 | patch methods: start and stop |
| 1293 | ----------------------------- |
| 1294 | |
| 1295 | All the patchers have `start` and `stop` methods. These make it simpler to do |
| 1296 | patching in `setUp` methods or where you want to do multiple patches without |
| 1297 | nesting decorators or with statements. |
| 1298 | |
| 1299 | To use them call `patch`, `patch.object` or `patch.dict` as normal and keep a |
| 1300 | reference to the returned `patcher` object. You can then call `start` to put |
| 1301 | the patch in place and `stop` to undo it. |
| 1302 | |
| 1303 | If you are using `patch` to create a mock for you then it will be returned by |
| 1304 | the call to `patcher.start`. |
| 1305 | |
| 1306 | >>> patcher = patch('package.module.ClassName') |
| 1307 | >>> from package import module |
| 1308 | >>> original = module.ClassName |
| 1309 | >>> new_mock = patcher.start() |
| 1310 | >>> assert module.ClassName is not original |
| 1311 | >>> assert module.ClassName is new_mock |
| 1312 | >>> patcher.stop() |
| 1313 | >>> assert module.ClassName is original |
| 1314 | >>> assert module.ClassName is not new_mock |
| 1315 | |
| 1316 | |
| 1317 | A typical use case for this might be for doing multiple patches in the `setUp` |
| 1318 | method of a `TestCase`: |
| 1319 | |
| 1320 | >>> class MyTest(TestCase): |
| 1321 | ... def setUp(self): |
| 1322 | ... self.patcher1 = patch('package.module.Class1') |
| 1323 | ... self.patcher2 = patch('package.module.Class2') |
| 1324 | ... self.MockClass1 = self.patcher1.start() |
| 1325 | ... self.MockClass2 = self.patcher2.start() |
| 1326 | ... |
| 1327 | ... def tearDown(self): |
| 1328 | ... self.patcher1.stop() |
| 1329 | ... self.patcher2.stop() |
| 1330 | ... |
| 1331 | ... def test_something(self): |
| 1332 | ... assert package.module.Class1 is self.MockClass1 |
| 1333 | ... assert package.module.Class2 is self.MockClass2 |
| 1334 | ... |
| 1335 | >>> MyTest('test_something').run() |
| 1336 | |
| 1337 | .. caution:: |
| 1338 | |
| 1339 | If you use this technique you must ensure that the patching is "undone" by |
| 1340 | calling `stop`. This can be fiddlier than you might think, because if an |
| 1341 | exception is raised in the ``setUp`` then ``tearDown`` is not called. |
| 1342 | :meth:`unittest.TestCase.addCleanup` makes this easier: |
| 1343 | |
| 1344 | >>> class MyTest(TestCase): |
| 1345 | ... def setUp(self): |
| 1346 | ... patcher = patch('package.module.Class') |
| 1347 | ... self.MockClass = patcher.start() |
| 1348 | ... self.addCleanup(patcher.stop) |
| 1349 | ... |
| 1350 | ... def test_something(self): |
| 1351 | ... assert package.module.Class is self.MockClass |
| 1352 | ... |
| 1353 | |
| 1354 | As an added bonus you no longer need to keep a reference to the `patcher` |
| 1355 | object. |
| 1356 | |
Michael Foord | f7c4158 | 2012-06-10 20:36:32 +0100 | [diff] [blame] | 1357 | It is also possible to stop all patches which have been started by using |
| 1358 | `patch.stopall`. |
| 1359 | |
| 1360 | .. function:: patch.stopall |
| 1361 | |
Michael Foord | 911fd32 | 2012-06-10 20:38:54 +0100 | [diff] [blame] | 1362 | Stop all active patches. Only stops patches started with `start`. |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 1363 | |
| 1364 | |
| 1365 | TEST_PREFIX |
| 1366 | ----------- |
| 1367 | |
| 1368 | All of the patchers can be used as class decorators. When used in this way |
| 1369 | they wrap every test method on the class. The patchers recognise methods that |
| 1370 | start with `test` as being test methods. This is the same way that the |
| 1371 | :class:`unittest.TestLoader` finds test methods by default. |
| 1372 | |
| 1373 | It is possible that you want to use a different prefix for your tests. You can |
| 1374 | inform the patchers of the different prefix by setting `patch.TEST_PREFIX`: |
| 1375 | |
| 1376 | >>> patch.TEST_PREFIX = 'foo' |
| 1377 | >>> value = 3 |
| 1378 | >>> |
| 1379 | >>> @patch('__main__.value', 'not three') |
| 1380 | ... class Thing(object): |
| 1381 | ... def foo_one(self): |
| 1382 | ... print value |
| 1383 | ... def foo_two(self): |
| 1384 | ... print value |
| 1385 | ... |
| 1386 | >>> |
| 1387 | >>> Thing().foo_one() |
| 1388 | not three |
| 1389 | >>> Thing().foo_two() |
| 1390 | not three |
| 1391 | >>> value |
| 1392 | 3 |
| 1393 | |
| 1394 | |
| 1395 | Nesting Patch Decorators |
| 1396 | ------------------------ |
| 1397 | |
| 1398 | If you want to perform multiple patches then you can simply stack up the |
| 1399 | decorators. |
| 1400 | |
| 1401 | You can stack up multiple patch decorators using this pattern: |
| 1402 | |
| 1403 | >>> @patch.object(SomeClass, 'class_method') |
| 1404 | ... @patch.object(SomeClass, 'static_method') |
| 1405 | ... def test(mock1, mock2): |
| 1406 | ... assert SomeClass.static_method is mock1 |
| 1407 | ... assert SomeClass.class_method is mock2 |
| 1408 | ... SomeClass.static_method('foo') |
| 1409 | ... SomeClass.class_method('bar') |
| 1410 | ... return mock1, mock2 |
| 1411 | ... |
| 1412 | >>> mock1, mock2 = test() |
| 1413 | >>> mock1.assert_called_once_with('foo') |
| 1414 | >>> mock2.assert_called_once_with('bar') |
| 1415 | |
| 1416 | |
| 1417 | Note that the decorators are applied from the bottom upwards. This is the |
| 1418 | standard way that Python applies decorators. The order of the created mocks |
| 1419 | passed into your test function matches this order. |
| 1420 | |
| 1421 | |
| 1422 | .. _where-to-patch: |
| 1423 | |
| 1424 | Where to patch |
| 1425 | -------------- |
| 1426 | |
| 1427 | `patch` works by (temporarily) changing the object that a *name* points to with |
| 1428 | another one. There can be many names pointing to any individual object, so |
| 1429 | for patching to work you must ensure that you patch the name used by the system |
| 1430 | under test. |
| 1431 | |
| 1432 | The basic principle is that you patch where an object is *looked up*, which |
| 1433 | is not necessarily the same place as where it is defined. A couple of |
| 1434 | examples will help to clarify this. |
| 1435 | |
| 1436 | Imagine we have a project that we want to test with the following structure:: |
| 1437 | |
| 1438 | a.py |
| 1439 | -> Defines SomeClass |
| 1440 | |
| 1441 | b.py |
| 1442 | -> from a import SomeClass |
| 1443 | -> some_function instantiates SomeClass |
| 1444 | |
| 1445 | Now we want to test `some_function` but we want to mock out `SomeClass` using |
| 1446 | `patch`. The problem is that when we import module b, which we will have to |
| 1447 | do then it imports `SomeClass` from module a. If we use `patch` to mock out |
| 1448 | `a.SomeClass` then it will have no effect on our test; module b already has a |
| 1449 | reference to the *real* `SomeClass` and it looks like our patching had no |
| 1450 | effect. |
| 1451 | |
| 1452 | The key is to patch out `SomeClass` where it is used (or where it is looked up |
| 1453 | ). In this case `some_function` will actually look up `SomeClass` in module b, |
| 1454 | where we have imported it. The patching should look like:: |
| 1455 | |
| 1456 | @patch('b.SomeClass') |
| 1457 | |
| 1458 | However, consider the alternative scenario where instead of `from a import |
| 1459 | SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both |
| 1460 | of these import forms are common. In this case the class we want to patch is |
| 1461 | being looked up on the a module and so we have to patch `a.SomeClass` instead:: |
| 1462 | |
| 1463 | @patch('a.SomeClass') |
| 1464 | |
| 1465 | |
| 1466 | Patching Descriptors and Proxy Objects |
| 1467 | -------------------------------------- |
| 1468 | |
| 1469 | Both patch_ and patch.object_ correctly patch and restore descriptors: class |
| 1470 | methods, static methods and properties. You should patch these on the *class* |
| 1471 | rather than an instance. They also work with *some* objects |
| 1472 | that proxy attribute access, like the `django setttings object |
| 1473 | <http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_. |
| 1474 | |
| 1475 | |
Michael Foord | 2309ed8 | 2012-03-28 15:38:36 +0100 | [diff] [blame] | 1476 | MagicMock and magic method support |
| 1477 | ================================== |
| 1478 | |
| 1479 | .. _magic-methods: |
| 1480 | |
| 1481 | Mocking Magic Methods |
| 1482 | --------------------- |
| 1483 | |
| 1484 | :class:`Mock` supports mocking the Python protocol methods, also known as |
| 1485 | "magic methods". This allows mock objects to replace containers or other |
| 1486 | objects that implement Python protocols. |
| 1487 | |
| 1488 | Because magic methods are looked up differently from normal methods [#]_, this |
| 1489 | support has been specially implemented. This means that only specific magic |
| 1490 | methods are supported. The supported list includes *almost* all of them. If |
| 1491 | there are any missing that you need please let us know. |
| 1492 | |
| 1493 | You mock magic methods by setting the method you are interested in to a function |
| 1494 | or a mock instance. If you are using a function then it *must* take ``self`` as |
| 1495 | the first argument [#]_. |
| 1496 | |
| 1497 | >>> def __str__(self): |
| 1498 | ... return 'fooble' |
| 1499 | ... |
| 1500 | >>> mock = Mock() |
| 1501 | >>> mock.__str__ = __str__ |
| 1502 | >>> str(mock) |
| 1503 | 'fooble' |
| 1504 | |
| 1505 | >>> mock = Mock() |
| 1506 | >>> mock.__str__ = Mock() |
| 1507 | >>> mock.__str__.return_value = 'fooble' |
| 1508 | >>> str(mock) |
| 1509 | 'fooble' |
| 1510 | |
| 1511 | >>> mock = Mock() |
| 1512 | >>> mock.__iter__ = Mock(return_value=iter([])) |
| 1513 | >>> list(mock) |
| 1514 | [] |
| 1515 | |
| 1516 | One use case for this is for mocking objects used as context managers in a |
| 1517 | `with` statement: |
| 1518 | |
| 1519 | >>> mock = Mock() |
| 1520 | >>> mock.__enter__ = Mock(return_value='foo') |
| 1521 | >>> mock.__exit__ = Mock(return_value=False) |
| 1522 | >>> with mock as m: |
| 1523 | ... assert m == 'foo' |
| 1524 | ... |
| 1525 | >>> mock.__enter__.assert_called_with() |
| 1526 | >>> mock.__exit__.assert_called_with(None, None, None) |
| 1527 | |
| 1528 | Calls to magic methods do not appear in :attr:`~Mock.method_calls`, but they |
| 1529 | are recorded in :attr:`~Mock.mock_calls`. |
| 1530 | |
| 1531 | .. note:: |
| 1532 | |
| 1533 | If you use the `spec` keyword argument to create a mock then attempting to |
| 1534 | set a magic method that isn't in the spec will raise an `AttributeError`. |
| 1535 | |
| 1536 | The full list of supported magic methods is: |
| 1537 | |
| 1538 | * ``__hash__``, ``__sizeof__``, ``__repr__`` and ``__str__`` |
| 1539 | * ``__dir__``, ``__format__`` and ``__subclasses__`` |
| 1540 | * ``__floor__``, ``__trunc__`` and ``__ceil__`` |
| 1541 | * Comparisons: ``__cmp__``, ``__lt__``, ``__gt__``, ``__le__``, ``__ge__``, |
| 1542 | ``__eq__`` and ``__ne__`` |
| 1543 | * Container methods: ``__getitem__``, ``__setitem__``, ``__delitem__``, |
| 1544 | ``__contains__``, ``__len__``, ``__iter__``, ``__getslice__``, |
| 1545 | ``__setslice__``, ``__reversed__`` and ``__missing__`` |
| 1546 | * Context manager: ``__enter__`` and ``__exit__`` |
| 1547 | * Unary numeric methods: ``__neg__``, ``__pos__`` and ``__invert__`` |
| 1548 | * The numeric methods (including right hand and in-place variants): |
| 1549 | ``__add__``, ``__sub__``, ``__mul__``, ``__div__``, |
| 1550 | ``__floordiv__``, ``__mod__``, ``__divmod__``, ``__lshift__``, |
| 1551 | ``__rshift__``, ``__and__``, ``__xor__``, ``__or__``, and ``__pow__`` |
| 1552 | * Numeric conversion methods: ``__complex__``, ``__int__``, ``__float__``, |
| 1553 | ``__index__`` and ``__coerce__`` |
| 1554 | * Descriptor methods: ``__get__``, ``__set__`` and ``__delete__`` |
| 1555 | * Pickling: ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, |
| 1556 | ``__getnewargs__``, ``__getstate__`` and ``__setstate__`` |
| 1557 | |
| 1558 | |
| 1559 | The following methods exist but are *not* supported as they are either in use |
| 1560 | by mock, can't be set dynamically, or can cause problems: |
| 1561 | |
| 1562 | * ``__getattr__``, ``__setattr__``, ``__init__`` and ``__new__`` |
| 1563 | * ``__prepare__``, ``__instancecheck__``, ``__subclasscheck__``, ``__del__`` |
| 1564 | |
| 1565 | |
| 1566 | |
| 1567 | Magic Mock |
| 1568 | ---------- |
| 1569 | |
| 1570 | There are two `MagicMock` variants: `MagicMock` and `NonCallableMagicMock`. |
| 1571 | |
| 1572 | |
| 1573 | .. class:: MagicMock(*args, **kw) |
| 1574 | |
| 1575 | ``MagicMock`` is a subclass of :class:`Mock` with default implementations |
| 1576 | of most of the magic methods. You can use ``MagicMock`` without having to |
| 1577 | configure the magic methods yourself. |
| 1578 | |
| 1579 | The constructor parameters have the same meaning as for :class:`Mock`. |
| 1580 | |
| 1581 | If you use the `spec` or `spec_set` arguments then *only* magic methods |
| 1582 | that exist in the spec will be created. |
| 1583 | |
| 1584 | |
| 1585 | .. class:: NonCallableMagicMock(*args, **kw) |
| 1586 | |
| 1587 | A non-callable version of `MagicMock`. |
| 1588 | |
| 1589 | The constructor parameters have the same meaning as for |
| 1590 | :class:`MagicMock`, with the exception of `return_value` and |
| 1591 | `side_effect` which have no meaning on a non-callable mock. |
| 1592 | |
| 1593 | The magic methods are setup with `MagicMock` objects, so you can configure them |
| 1594 | and use them in the usual way: |
| 1595 | |
| 1596 | >>> mock = MagicMock() |
| 1597 | >>> mock[3] = 'fish' |
| 1598 | >>> mock.__setitem__.assert_called_with(3, 'fish') |
| 1599 | >>> mock.__getitem__.return_value = 'result' |
| 1600 | >>> mock[2] |
| 1601 | 'result' |
| 1602 | |
| 1603 | By default many of the protocol methods are required to return objects of a |
| 1604 | specific type. These methods are preconfigured with a default return value, so |
| 1605 | that they can be used without you having to do anything if you aren't interested |
| 1606 | in the return value. You can still *set* the return value manually if you want |
| 1607 | to change the default. |
| 1608 | |
| 1609 | Methods and their defaults: |
| 1610 | |
| 1611 | * ``__lt__``: NotImplemented |
| 1612 | * ``__gt__``: NotImplemented |
| 1613 | * ``__le__``: NotImplemented |
| 1614 | * ``__ge__``: NotImplemented |
| 1615 | * ``__int__`` : 1 |
| 1616 | * ``__contains__`` : False |
| 1617 | * ``__len__`` : 1 |
| 1618 | * ``__iter__`` : iter([]) |
| 1619 | * ``__exit__`` : False |
| 1620 | * ``__complex__`` : 1j |
| 1621 | * ``__float__`` : 1.0 |
| 1622 | * ``__bool__`` : True |
| 1623 | * ``__index__`` : 1 |
| 1624 | * ``__hash__`` : default hash for the mock |
| 1625 | * ``__str__`` : default str for the mock |
| 1626 | * ``__sizeof__``: default sizeof for the mock |
| 1627 | |
| 1628 | For example: |
| 1629 | |
| 1630 | >>> mock = MagicMock() |
| 1631 | >>> int(mock) |
| 1632 | 1 |
| 1633 | >>> len(mock) |
| 1634 | 0 |
| 1635 | >>> list(mock) |
| 1636 | [] |
| 1637 | >>> object() in mock |
| 1638 | False |
| 1639 | |
| 1640 | The two equality method, `__eq__` and `__ne__`, are special. |
| 1641 | They do the default equality comparison on identity, using a side |
| 1642 | effect, unless you change their return value to return something else: |
| 1643 | |
| 1644 | >>> MagicMock() == 3 |
| 1645 | False |
| 1646 | >>> MagicMock() != 3 |
| 1647 | True |
| 1648 | >>> mock = MagicMock() |
| 1649 | >>> mock.__eq__.return_value = True |
| 1650 | >>> mock == 3 |
| 1651 | True |
| 1652 | |
| 1653 | The return value of `MagicMock.__iter__` can be any iterable object and isn't |
| 1654 | required to be an iterator: |
| 1655 | |
| 1656 | >>> mock = MagicMock() |
| 1657 | >>> mock.__iter__.return_value = ['a', 'b', 'c'] |
| 1658 | >>> list(mock) |
| 1659 | ['a', 'b', 'c'] |
| 1660 | >>> list(mock) |
| 1661 | ['a', 'b', 'c'] |
| 1662 | |
| 1663 | If the return value *is* an iterator, then iterating over it once will consume |
| 1664 | it and subsequent iterations will result in an empty list: |
| 1665 | |
| 1666 | >>> mock.__iter__.return_value = iter(['a', 'b', 'c']) |
| 1667 | >>> list(mock) |
| 1668 | ['a', 'b', 'c'] |
| 1669 | >>> list(mock) |
| 1670 | [] |
| 1671 | |
| 1672 | ``MagicMock`` has all of the supported magic methods configured except for some |
| 1673 | of the obscure and obsolete ones. You can still set these up if you want. |
| 1674 | |
| 1675 | Magic methods that are supported but not setup by default in ``MagicMock`` are: |
| 1676 | |
| 1677 | * ``__subclasses__`` |
| 1678 | * ``__dir__`` |
| 1679 | * ``__format__`` |
| 1680 | * ``__get__``, ``__set__`` and ``__delete__`` |
| 1681 | * ``__reversed__`` and ``__missing__`` |
| 1682 | * ``__reduce__``, ``__reduce_ex__``, ``__getinitargs__``, ``__getnewargs__``, |
| 1683 | ``__getstate__`` and ``__setstate__`` |
| 1684 | * ``__getformat__`` and ``__setformat__`` |
| 1685 | |
| 1686 | |
| 1687 | |
| 1688 | .. [#] Magic methods *should* be looked up on the class rather than the |
| 1689 | instance. Different versions of Python are inconsistent about applying this |
| 1690 | rule. The supported protocol methods should work with all supported versions |
| 1691 | of Python. |
| 1692 | .. [#] The function is basically hooked up to the class, but each ``Mock`` |
| 1693 | instance is kept isolated from the others. |
| 1694 | |
| 1695 | |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 1696 | Helpers |
| 1697 | ======= |
| 1698 | |
| 1699 | sentinel |
| 1700 | -------- |
| 1701 | |
| 1702 | .. data:: sentinel |
| 1703 | |
| 1704 | The ``sentinel`` object provides a convenient way of providing unique |
| 1705 | objects for your tests. |
| 1706 | |
| 1707 | Attributes are created on demand when you access them by name. Accessing |
| 1708 | the same attribute will always return the same object. The objects |
| 1709 | returned have a sensible repr so that test failure messages are readable. |
| 1710 | |
| 1711 | Sometimes when testing you need to test that a specific object is passed as an |
| 1712 | argument to another method, or returned. It can be common to create named |
| 1713 | sentinel objects to test this. `sentinel` provides a convenient way of |
| 1714 | creating and testing the identity of objects like this. |
| 1715 | |
| 1716 | In this example we monkey patch `method` to return `sentinel.some_object`: |
| 1717 | |
| 1718 | >>> real = ProductionClass() |
| 1719 | >>> real.method = Mock(name="method") |
| 1720 | >>> real.method.return_value = sentinel.some_object |
| 1721 | >>> result = real.method() |
| 1722 | >>> assert result is sentinel.some_object |
| 1723 | >>> sentinel.some_object |
| 1724 | sentinel.some_object |
| 1725 | |
| 1726 | |
| 1727 | DEFAULT |
| 1728 | ------- |
| 1729 | |
| 1730 | |
| 1731 | .. data:: DEFAULT |
| 1732 | |
| 1733 | The `DEFAULT` object is a pre-created sentinel (actually |
| 1734 | `sentinel.DEFAULT`). It can be used by :attr:`~Mock.side_effect` |
| 1735 | functions to indicate that the normal return value should be used. |
| 1736 | |
| 1737 | |
| 1738 | |
| 1739 | call |
| 1740 | ---- |
| 1741 | |
| 1742 | .. function:: call(*args, **kwargs) |
| 1743 | |
Georg Brandl | 2489167 | 2012-04-01 13:48:26 +0200 | [diff] [blame] | 1744 | `call` is a helper object for making simpler assertions, for comparing with |
| 1745 | :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`, |
| 1746 | :attr:`~Mock.mock_calls` and :attr:`~Mock.method_calls`. `call` can also be |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 1747 | used with :meth:`~Mock.assert_has_calls`. |
| 1748 | |
| 1749 | >>> m = MagicMock(return_value=None) |
| 1750 | >>> m(1, 2, a='foo', b='bar') |
| 1751 | >>> m() |
| 1752 | >>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()] |
| 1753 | True |
| 1754 | |
| 1755 | .. method:: call.call_list() |
| 1756 | |
| 1757 | For a call object that represents multiple calls, `call_list` |
| 1758 | returns a list of all the intermediate calls as well as the |
| 1759 | final call. |
| 1760 | |
| 1761 | `call_list` is particularly useful for making assertions on "chained calls". A |
| 1762 | chained call is multiple calls on a single line of code. This results in |
| 1763 | multiple entries in :attr:`~Mock.mock_calls` on a mock. Manually constructing |
| 1764 | the sequence of calls can be tedious. |
| 1765 | |
| 1766 | :meth:`~call.call_list` can construct the sequence of calls from the same |
| 1767 | chained call: |
| 1768 | |
| 1769 | >>> m = MagicMock() |
| 1770 | >>> m(1).method(arg='foo').other('bar')(2.0) |
| 1771 | <MagicMock name='mock().method().other()()' id='...'> |
| 1772 | >>> kall = call(1).method(arg='foo').other('bar')(2.0) |
| 1773 | >>> kall.call_list() |
| 1774 | [call(1), |
| 1775 | call().method(arg='foo'), |
| 1776 | call().method().other('bar'), |
| 1777 | call().method().other()(2.0)] |
| 1778 | >>> m.mock_calls == kall.call_list() |
| 1779 | True |
| 1780 | |
| 1781 | .. _calls-as-tuples: |
| 1782 | |
| 1783 | A `call` object is either a tuple of (positional args, keyword args) or |
| 1784 | (name, positional args, keyword args) depending on how it was constructed. When |
| 1785 | you construct them yourself this isn't particularly interesting, but the `call` |
| 1786 | objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and |
| 1787 | :attr:`Mock.mock_calls` attributes can be introspected to get at the individual |
| 1788 | arguments they contain. |
| 1789 | |
| 1790 | The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list` |
| 1791 | are two-tuples of (positional args, keyword args) whereas the `call` objects |
| 1792 | in :attr:`Mock.mock_calls`, along with ones you construct yourself, are |
| 1793 | three-tuples of (name, positional args, keyword args). |
| 1794 | |
| 1795 | You can use their "tupleness" to pull out the individual arguments for more |
| 1796 | complex introspection and assertions. The positional arguments are a tuple |
| 1797 | (an empty tuple if there are no positional arguments) and the keyword |
| 1798 | arguments are a dictionary: |
| 1799 | |
| 1800 | >>> m = MagicMock(return_value=None) |
| 1801 | >>> m(1, 2, 3, arg='one', arg2='two') |
| 1802 | >>> kall = m.call_args |
| 1803 | >>> args, kwargs = kall |
| 1804 | >>> args |
| 1805 | (1, 2, 3) |
| 1806 | >>> kwargs |
| 1807 | {'arg2': 'two', 'arg': 'one'} |
| 1808 | >>> args is kall[0] |
| 1809 | True |
| 1810 | >>> kwargs is kall[1] |
| 1811 | True |
| 1812 | |
| 1813 | >>> m = MagicMock() |
| 1814 | >>> m.foo(4, 5, 6, arg='two', arg2='three') |
| 1815 | <MagicMock name='mock.foo()' id='...'> |
| 1816 | >>> kall = m.mock_calls[0] |
| 1817 | >>> name, args, kwargs = kall |
| 1818 | >>> name |
| 1819 | 'foo' |
| 1820 | >>> args |
| 1821 | (4, 5, 6) |
| 1822 | >>> kwargs |
| 1823 | {'arg2': 'three', 'arg': 'two'} |
| 1824 | >>> name is m.mock_calls[0][0] |
| 1825 | True |
| 1826 | |
| 1827 | |
| 1828 | create_autospec |
| 1829 | --------------- |
| 1830 | |
| 1831 | .. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs) |
| 1832 | |
| 1833 | Create a mock object using another object as a spec. Attributes on the |
| 1834 | mock will use the corresponding attribute on the `spec` object as their |
| 1835 | spec. |
| 1836 | |
| 1837 | Functions or methods being mocked will have their arguments checked to |
| 1838 | ensure that they are called with the correct signature. |
| 1839 | |
| 1840 | If `spec_set` is `True` then attempting to set attributes that don't exist |
| 1841 | on the spec object will raise an `AttributeError`. |
| 1842 | |
| 1843 | If a class is used as a spec then the return value of the mock (the |
| 1844 | instance of the class) will have the same spec. You can use a class as the |
| 1845 | spec for an instance object by passing `instance=True`. The returned mock |
| 1846 | will only be callable if instances of the mock are callable. |
| 1847 | |
| 1848 | `create_autospec` also takes arbitrary keyword arguments that are passed to |
| 1849 | the constructor of the created mock. |
| 1850 | |
| 1851 | See :ref:`auto-speccing` for examples of how to use auto-speccing with |
| 1852 | `create_autospec` and the `autospec` argument to :func:`patch`. |
| 1853 | |
| 1854 | |
| 1855 | ANY |
| 1856 | --- |
| 1857 | |
| 1858 | .. data:: ANY |
| 1859 | |
| 1860 | Sometimes you may need to make assertions about *some* of the arguments in a |
| 1861 | call to mock, but either not care about some of the arguments or want to pull |
| 1862 | them individually out of :attr:`~Mock.call_args` and make more complex |
| 1863 | assertions on them. |
| 1864 | |
| 1865 | To ignore certain arguments you can pass in objects that compare equal to |
| 1866 | *everything*. Calls to :meth:`~Mock.assert_called_with` and |
| 1867 | :meth:`~Mock.assert_called_once_with` will then succeed no matter what was |
| 1868 | passed in. |
| 1869 | |
| 1870 | >>> mock = Mock(return_value=None) |
| 1871 | >>> mock('foo', bar=object()) |
| 1872 | >>> mock.assert_called_once_with('foo', bar=ANY) |
| 1873 | |
| 1874 | `ANY` can also be used in comparisons with call lists like |
| 1875 | :attr:`~Mock.mock_calls`: |
| 1876 | |
| 1877 | >>> m = MagicMock(return_value=None) |
| 1878 | >>> m(1) |
| 1879 | >>> m(1, 2) |
| 1880 | >>> m(object()) |
| 1881 | >>> m.mock_calls == [call(1), call(1, 2), ANY] |
| 1882 | True |
| 1883 | |
| 1884 | |
| 1885 | |
| 1886 | FILTER_DIR |
| 1887 | ---------- |
| 1888 | |
| 1889 | .. data:: FILTER_DIR |
| 1890 | |
| 1891 | `FILTER_DIR` is a module level variable that controls the way mock objects |
| 1892 | respond to `dir` (only for Python 2.6 or more recent). The default is `True`, |
| 1893 | which uses the filtering described below, to only show useful members. If you |
| 1894 | dislike this filtering, or need to switch it off for diagnostic purposes, then |
| 1895 | set `mock.FILTER_DIR = False`. |
| 1896 | |
| 1897 | With filtering on, `dir(some_mock)` shows only useful attributes and will |
| 1898 | include any dynamically created attributes that wouldn't normally be shown. |
| 1899 | If the mock was created with a `spec` (or `autospec` of course) then all the |
| 1900 | attributes from the original are shown, even if they haven't been accessed |
| 1901 | yet: |
| 1902 | |
| 1903 | >>> dir(Mock()) |
| 1904 | ['assert_any_call', |
| 1905 | 'assert_called_once_with', |
| 1906 | 'assert_called_with', |
| 1907 | 'assert_has_calls', |
| 1908 | 'attach_mock', |
| 1909 | ... |
| 1910 | >>> from urllib import request |
| 1911 | >>> dir(Mock(spec=request)) |
| 1912 | ['AbstractBasicAuthHandler', |
| 1913 | 'AbstractDigestAuthHandler', |
| 1914 | 'AbstractHTTPHandler', |
| 1915 | 'BaseHandler', |
| 1916 | ... |
| 1917 | |
| 1918 | Many of the not-very-useful (private to `Mock` rather than the thing being |
| 1919 | mocked) underscore and double underscore prefixed attributes have been |
| 1920 | filtered from the result of calling `dir` on a `Mock`. If you dislike this |
| 1921 | behaviour you can switch it off by setting the module level switch |
| 1922 | `FILTER_DIR`: |
| 1923 | |
| 1924 | >>> from unittest import mock |
| 1925 | >>> mock.FILTER_DIR = False |
| 1926 | >>> dir(mock.Mock()) |
| 1927 | ['_NonCallableMock__get_return_value', |
| 1928 | '_NonCallableMock__get_side_effect', |
| 1929 | '_NonCallableMock__return_value_doc', |
| 1930 | '_NonCallableMock__set_return_value', |
| 1931 | '_NonCallableMock__set_side_effect', |
| 1932 | '__call__', |
| 1933 | '__class__', |
| 1934 | ... |
| 1935 | |
| 1936 | Alternatively you can just use `vars(my_mock)` (instance members) and |
| 1937 | `dir(type(my_mock))` (type members) to bypass the filtering irrespective of |
| 1938 | `mock.FILTER_DIR`. |
| 1939 | |
| 1940 | |
| 1941 | mock_open |
| 1942 | --------- |
| 1943 | |
| 1944 | .. function:: mock_open(mock=None, read_data=None) |
| 1945 | |
| 1946 | A helper function to create a mock to replace the use of `open`. It works |
| 1947 | for `open` called directly or used as a context manager. |
| 1948 | |
| 1949 | The `mock` argument is the mock object to configure. If `None` (the |
| 1950 | default) then a `MagicMock` will be created for you, with the API limited |
| 1951 | to methods or attributes available on standard file handles. |
| 1952 | |
| 1953 | `read_data` is a string for the `read` method of the file handle to return. |
| 1954 | This is an empty string by default. |
| 1955 | |
| 1956 | Using `open` as a context manager is a great way to ensure your file handles |
| 1957 | are closed properly and is becoming common:: |
| 1958 | |
| 1959 | with open('/some/path', 'w') as f: |
| 1960 | f.write('something') |
| 1961 | |
| 1962 | The issue is that even if you mock out the call to `open` it is the |
| 1963 | *returned object* that is used as a context manager (and has `__enter__` and |
| 1964 | `__exit__` called). |
| 1965 | |
| 1966 | Mocking context managers with a :class:`MagicMock` is common enough and fiddly |
| 1967 | enough that a helper function is useful. |
| 1968 | |
| 1969 | >>> m = mock_open() |
| 1970 | >>> with patch('__main__.open', m, create=True): |
| 1971 | ... with open('foo', 'w') as h: |
| 1972 | ... h.write('some stuff') |
| 1973 | ... |
| 1974 | >>> m.mock_calls |
| 1975 | [call('foo', 'w'), |
| 1976 | call().__enter__(), |
| 1977 | call().write('some stuff'), |
| 1978 | call().__exit__(None, None, None)] |
| 1979 | >>> m.assert_called_once_with('foo', 'w') |
| 1980 | >>> handle = m() |
| 1981 | >>> handle.write.assert_called_once_with('some stuff') |
| 1982 | |
| 1983 | And for reading files: |
| 1984 | |
| 1985 | >>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m: |
| 1986 | ... with open('foo') as h: |
| 1987 | ... result = h.read() |
| 1988 | ... |
| 1989 | >>> m.assert_called_once_with('foo') |
| 1990 | >>> assert result == 'bibble' |
| 1991 | |
| 1992 | |
| 1993 | .. _auto-speccing: |
| 1994 | |
| 1995 | Autospeccing |
| 1996 | ------------ |
| 1997 | |
| 1998 | Autospeccing is based on the existing `spec` feature of mock. It limits the |
| 1999 | api of mocks to the api of an original object (the spec), but it is recursive |
| 2000 | (implemented lazily) so that attributes of mocks only have the same api as |
| 2001 | the attributes of the spec. In addition mocked functions / methods have the |
| 2002 | same call signature as the original so they raise a `TypeError` if they are |
| 2003 | called incorrectly. |
| 2004 | |
| 2005 | Before I explain how auto-speccing works, here's why it is needed. |
| 2006 | |
| 2007 | `Mock` is a very powerful and flexible object, but it suffers from two flaws |
| 2008 | when used to mock out objects from a system under test. One of these flaws is |
| 2009 | specific to the `Mock` api and the other is a more general problem with using |
| 2010 | mock objects. |
| 2011 | |
| 2012 | First the problem specific to `Mock`. `Mock` has two assert methods that are |
| 2013 | extremely handy: :meth:`~Mock.assert_called_with` and |
| 2014 | :meth:`~Mock.assert_called_once_with`. |
| 2015 | |
| 2016 | >>> mock = Mock(name='Thing', return_value=None) |
| 2017 | >>> mock(1, 2, 3) |
| 2018 | >>> mock.assert_called_once_with(1, 2, 3) |
| 2019 | >>> mock(1, 2, 3) |
| 2020 | >>> mock.assert_called_once_with(1, 2, 3) |
| 2021 | Traceback (most recent call last): |
| 2022 | ... |
Michael Foord | 28d591c | 2012-09-28 16:15:22 +0100 | [diff] [blame] | 2023 | AssertionError: Expected 'mock' to be called once. Called 2 times. |
Michael Foord | a9e6fb2 | 2012-03-28 14:36:02 +0100 | [diff] [blame] | 2024 | |
| 2025 | Because mocks auto-create attributes on demand, and allow you to call them |
| 2026 | with arbitrary arguments, if you misspell one of these assert methods then |
| 2027 | your assertion is gone: |
| 2028 | |
| 2029 | .. code-block:: pycon |
| 2030 | |
| 2031 | >>> mock = Mock(name='Thing', return_value=None) |
| 2032 | >>> mock(1, 2, 3) |
| 2033 | >>> mock.assret_called_once_with(4, 5, 6) |
| 2034 | |
| 2035 | Your tests can pass silently and incorrectly because of the typo. |
| 2036 | |
| 2037 | The second issue is more general to mocking. If you refactor some of your |
| 2038 | code, rename members and so on, any tests for code that is still using the |
| 2039 | *old api* but uses mocks instead of the real objects will still pass. This |
| 2040 | means your tests can all pass even though your code is broken. |
| 2041 | |
| 2042 | Note that this is another reason why you need integration tests as well as |
| 2043 | unit tests. Testing everything in isolation is all fine and dandy, but if you |
| 2044 | don't test how your units are "wired together" there is still lots of room |
| 2045 | for bugs that tests might have caught. |
| 2046 | |
| 2047 | `mock` already provides a feature to help with this, called speccing. If you |
| 2048 | use a class or instance as the `spec` for a mock then you can only access |
| 2049 | attributes on the mock that exist on the real class: |
| 2050 | |
| 2051 | >>> from urllib import request |
| 2052 | >>> mock = Mock(spec=request.Request) |
| 2053 | >>> mock.assret_called_with |
| 2054 | Traceback (most recent call last): |
| 2055 | ... |
| 2056 | AttributeError: Mock object has no attribute 'assret_called_with' |
| 2057 | |
| 2058 | The spec only applies to the mock itself, so we still have the same issue |
| 2059 | with any methods on the mock: |
| 2060 | |
| 2061 | .. code-block:: pycon |
| 2062 | |
| 2063 | >>> mock.has_data() |
| 2064 | <mock.Mock object at 0x...> |
| 2065 | >>> mock.has_data.assret_called_with() |
| 2066 | |
| 2067 | Auto-speccing solves this problem. You can either pass `autospec=True` to |
| 2068 | `patch` / `patch.object` or use the `create_autospec` function to create a |
| 2069 | mock with a spec. If you use the `autospec=True` argument to `patch` then the |
| 2070 | object that is being replaced will be used as the spec object. Because the |
| 2071 | speccing is done "lazily" (the spec is created as attributes on the mock are |
| 2072 | accessed) you can use it with very complex or deeply nested objects (like |
| 2073 | modules that import modules that import modules) without a big performance |
| 2074 | hit. |
| 2075 | |
| 2076 | Here's an example of it in use: |
| 2077 | |
| 2078 | >>> from urllib import request |
| 2079 | >>> patcher = patch('__main__.request', autospec=True) |
| 2080 | >>> mock_request = patcher.start() |
| 2081 | >>> request is mock_request |
| 2082 | True |
| 2083 | >>> mock_request.Request |
| 2084 | <MagicMock name='request.Request' spec='Request' id='...'> |
| 2085 | |
| 2086 | You can see that `request.Request` has a spec. `request.Request` takes two |
| 2087 | arguments in the constructor (one of which is `self`). Here's what happens if |
| 2088 | we try to call it incorrectly: |
| 2089 | |
| 2090 | >>> req = request.Request() |
| 2091 | Traceback (most recent call last): |
| 2092 | ... |
| 2093 | TypeError: <lambda>() takes at least 2 arguments (1 given) |
| 2094 | |
| 2095 | The spec also applies to instantiated classes (i.e. the return value of |
| 2096 | specced mocks): |
| 2097 | |
| 2098 | >>> req = request.Request('foo') |
| 2099 | >>> req |
| 2100 | <NonCallableMagicMock name='request.Request()' spec='Request' id='...'> |
| 2101 | |
| 2102 | `Request` objects are not callable, so the return value of instantiating our |
| 2103 | mocked out `request.Request` is a non-callable mock. With the spec in place |
| 2104 | any typos in our asserts will raise the correct error: |
| 2105 | |
| 2106 | >>> req.add_header('spam', 'eggs') |
| 2107 | <MagicMock name='request.Request().add_header()' id='...'> |
| 2108 | >>> req.add_header.assret_called_with |
| 2109 | Traceback (most recent call last): |
| 2110 | ... |
| 2111 | AttributeError: Mock object has no attribute 'assret_called_with' |
| 2112 | >>> req.add_header.assert_called_with('spam', 'eggs') |
| 2113 | |
| 2114 | In many cases you will just be able to add `autospec=True` to your existing |
| 2115 | `patch` calls and then be protected against bugs due to typos and api |
| 2116 | changes. |
| 2117 | |
| 2118 | As well as using `autospec` through `patch` there is a |
| 2119 | :func:`create_autospec` for creating autospecced mocks directly: |
| 2120 | |
| 2121 | >>> from urllib import request |
| 2122 | >>> mock_request = create_autospec(request) |
| 2123 | >>> mock_request.Request('foo', 'bar') |
| 2124 | <NonCallableMagicMock name='mock.Request()' spec='Request' id='...'> |
| 2125 | |
| 2126 | This isn't without caveats and limitations however, which is why it is not |
| 2127 | the default behaviour. In order to know what attributes are available on the |
| 2128 | spec object, autospec has to introspect (access attributes) the spec. As you |
| 2129 | traverse attributes on the mock a corresponding traversal of the original |
| 2130 | object is happening under the hood. If any of your specced objects have |
| 2131 | properties or descriptors that can trigger code execution then you may not be |
| 2132 | able to use autospec. On the other hand it is much better to design your |
| 2133 | objects so that introspection is safe [#]_. |
| 2134 | |
| 2135 | A more serious problem is that it is common for instance attributes to be |
| 2136 | created in the `__init__` method and not to exist on the class at all. |
| 2137 | `autospec` can't know about any dynamically created attributes and restricts |
| 2138 | the api to visible attributes. |
| 2139 | |
| 2140 | >>> class Something(object): |
| 2141 | ... def __init__(self): |
| 2142 | ... self.a = 33 |
| 2143 | ... |
| 2144 | >>> with patch('__main__.Something', autospec=True): |
| 2145 | ... thing = Something() |
| 2146 | ... thing.a |
| 2147 | ... |
| 2148 | Traceback (most recent call last): |
| 2149 | ... |
| 2150 | AttributeError: Mock object has no attribute 'a' |
| 2151 | |
| 2152 | There are a few different ways of resolving this problem. The easiest, but |
| 2153 | not necessarily the least annoying, way is to simply set the required |
| 2154 | attributes on the mock after creation. Just because `autospec` doesn't allow |
| 2155 | you to fetch attributes that don't exist on the spec it doesn't prevent you |
| 2156 | setting them: |
| 2157 | |
| 2158 | >>> with patch('__main__.Something', autospec=True): |
| 2159 | ... thing = Something() |
| 2160 | ... thing.a = 33 |
| 2161 | ... |
| 2162 | |
| 2163 | There is a more aggressive version of both `spec` and `autospec` that *does* |
| 2164 | prevent you setting non-existent attributes. This is useful if you want to |
| 2165 | ensure your code only *sets* valid attributes too, but obviously it prevents |
| 2166 | this particular scenario: |
| 2167 | |
| 2168 | >>> with patch('__main__.Something', autospec=True, spec_set=True): |
| 2169 | ... thing = Something() |
| 2170 | ... thing.a = 33 |
| 2171 | ... |
| 2172 | Traceback (most recent call last): |
| 2173 | ... |
| 2174 | AttributeError: Mock object has no attribute 'a' |
| 2175 | |
| 2176 | Probably the best way of solving the problem is to add class attributes as |
| 2177 | default values for instance members initialised in `__init__`. Note that if |
| 2178 | you are only setting default attributes in `__init__` then providing them via |
| 2179 | class attributes (shared between instances of course) is faster too. e.g. |
| 2180 | |
| 2181 | .. code-block:: python |
| 2182 | |
| 2183 | class Something(object): |
| 2184 | a = 33 |
| 2185 | |
| 2186 | This brings up another issue. It is relatively common to provide a default |
| 2187 | value of `None` for members that will later be an object of a different type. |
| 2188 | `None` would be useless as a spec because it wouldn't let you access *any* |
| 2189 | attributes or methods on it. As `None` is *never* going to be useful as a |
| 2190 | spec, and probably indicates a member that will normally of some other type, |
| 2191 | `autospec` doesn't use a spec for members that are set to `None`. These will |
| 2192 | just be ordinary mocks (well - `MagicMocks`): |
| 2193 | |
| 2194 | >>> class Something(object): |
| 2195 | ... member = None |
| 2196 | ... |
| 2197 | >>> mock = create_autospec(Something) |
| 2198 | >>> mock.member.foo.bar.baz() |
| 2199 | <MagicMock name='mock.member.foo.bar.baz()' id='...'> |
| 2200 | |
| 2201 | If modifying your production classes to add defaults isn't to your liking |
| 2202 | then there are more options. One of these is simply to use an instance as the |
| 2203 | spec rather than the class. The other is to create a subclass of the |
| 2204 | production class and add the defaults to the subclass without affecting the |
| 2205 | production class. Both of these require you to use an alternative object as |
| 2206 | the spec. Thankfully `patch` supports this - you can simply pass the |
| 2207 | alternative object as the `autospec` argument: |
| 2208 | |
| 2209 | >>> class Something(object): |
| 2210 | ... def __init__(self): |
| 2211 | ... self.a = 33 |
| 2212 | ... |
| 2213 | >>> class SomethingForTest(Something): |
| 2214 | ... a = 33 |
| 2215 | ... |
| 2216 | >>> p = patch('__main__.Something', autospec=SomethingForTest) |
| 2217 | >>> mock = p.start() |
| 2218 | >>> mock.a |
| 2219 | <NonCallableMagicMock name='Something.a' spec='int' id='...'> |
| 2220 | |
| 2221 | |
| 2222 | .. [#] This only applies to classes or already instantiated objects. Calling |
| 2223 | a mocked class to create a mock instance *does not* create a real instance. |
| 2224 | It is only attribute lookups - along with calls to `dir` - that are done. |
| 2225 | |