Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 1 | ================== |
| 2 | Patch Decorators |
| 3 | ================== |
| 4 | |
| 5 | |
| 6 | .. currentmodule:: mock |
| 7 | |
| 8 | .. testsetup:: |
| 9 | |
| 10 | class SomeClass(object): |
| 11 | static_method = None |
| 12 | class_method = None |
| 13 | attribute = None |
| 14 | |
| 15 | sys.modules['package'] = package = Mock(name='package') |
| 16 | sys.modules['package.module'] = package.module |
| 17 | |
| 18 | class TestCase(unittest2.TestCase): |
| 19 | def run(self): |
| 20 | result = unittest2.TestResult() |
| 21 | super(unittest2.TestCase, self).run(result) |
| 22 | assert result.wasSuccessful() |
| 23 | |
| 24 | .. testcleanup:: |
| 25 | |
| 26 | patch.TEST_PREFIX = 'test' |
| 27 | |
| 28 | |
| 29 | The patch decorators are used for patching objects only within the scope of |
| 30 | the function they decorate. They automatically handle the unpatching for you, |
| 31 | even if exceptions are raised. All of these functions can also be used in with |
| 32 | statements or as class decorators. |
| 33 | |
| 34 | |
| 35 | patch |
| 36 | ===== |
| 37 | |
| 38 | .. note:: |
| 39 | |
| 40 | `patch` is straightforward to use. The key is to do the patching in the |
| 41 | right namespace. See the section `where to patch`_. |
| 42 | |
Michael Foord | 08f4755 | 2012-03-25 17:39:04 +0100 | [diff] [blame] | 43 | .. function:: patch(target, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 44 | |
| 45 | `patch` acts as a function decorator, class decorator or a context |
| 46 | manager. Inside the body of the function or with statement, the `target` |
Michael Foord | 06fb5c6 | 2012-03-28 15:10:06 +0100 | [diff] [blame] | 47 | is patched with a `new` object. When the function/with statement exits |
| 48 | the patch is undone. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 49 | |
Michael Foord | 06fb5c6 | 2012-03-28 15:10:06 +0100 | [diff] [blame] | 50 | If `new` is omitted, then the target is replaced with a |
| 51 | :class:`MagicMock`. If `patch` is used as a decorator and `new` is |
| 52 | omitted, the created mock is passed in as an extra argument to the |
| 53 | decorated function. If `patch` is used as a context manager the created |
| 54 | mock is returned by the context manager. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 55 | |
Michael Foord | 06fb5c6 | 2012-03-28 15:10:06 +0100 | [diff] [blame] | 56 | `target` should be a string in the form `'package.module.ClassName'`. The |
| 57 | `target` is imported and the specified object replaced with the `new` |
| 58 | object, so the `target` must be importable from the environment you are |
| 59 | calling `patch` from. The target is imported when the decorated function |
| 60 | is executed, not at decoration time. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 61 | |
| 62 | The `spec` and `spec_set` keyword arguments are passed to the `MagicMock` |
| 63 | if patch is creating one for you. |
| 64 | |
| 65 | In addition you can pass `spec=True` or `spec_set=True`, which causes |
| 66 | patch to pass in the object being mocked as the spec/spec_set object. |
| 67 | |
| 68 | `new_callable` allows you to specify a different class, or callable object, |
| 69 | that will be called to create the `new` object. By default `MagicMock` is |
| 70 | used. |
| 71 | |
| 72 | A more powerful form of `spec` is `autospec`. If you set `autospec=True` |
| 73 | then the mock with be created with a spec from the object being replaced. |
| 74 | All attributes of the mock will also have the spec of the corresponding |
| 75 | attribute of the object being replaced. Methods and functions being mocked |
| 76 | will have their arguments checked and will raise a `TypeError` if they are |
Michael Foord | af78a50 | 2012-03-13 17:00:04 -0700 | [diff] [blame] | 77 | called with the wrong signature. For mocks |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 78 | replacing a class, their return value (the 'instance') will have the same |
| 79 | spec as the class. See the :func:`create_autospec` function and |
| 80 | :ref:`auto-speccing`. |
| 81 | |
| 82 | Instead of `autospec=True` you can pass `autospec=some_object` to use an |
| 83 | arbitrary object as the spec instead of the one being replaced. |
| 84 | |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 85 | By default `patch` will fail to replace attributes that don't exist. If |
| 86 | you pass in `create=True`, and the attribute doesn't exist, patch will |
| 87 | create the attribute for you when the patched function is called, and |
| 88 | delete it again afterwards. This is useful for writing tests against |
| 89 | attributes that your production code creates at runtime. It is off by by |
| 90 | default because it can be dangerous. With it switched on you can write |
| 91 | passing tests against APIs that don't actually exist! |
| 92 | |
| 93 | Patch can be used as a `TestCase` class decorator. It works by |
| 94 | decorating each test method in the class. This reduces the boilerplate |
| 95 | code when your test methods share a common patchings set. `patch` finds |
| 96 | tests by looking for method names that start with `patch.TEST_PREFIX`. |
| 97 | By default this is `test`, which matches the way `unittest` finds tests. |
| 98 | You can specify an alternative prefix by setting `patch.TEST_PREFIX`. |
| 99 | |
| 100 | Patch can be used as a context manager, with the with statement. Here the |
| 101 | patching applies to the indented block after the with statement. If you |
| 102 | use "as" then the patched object will be bound to the name after the |
| 103 | "as"; very useful if `patch` is creating a mock object for you. |
| 104 | |
| 105 | `patch` takes arbitrary keyword arguments. These will be passed to |
| 106 | the `Mock` (or `new_callable`) on construction. |
| 107 | |
| 108 | `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are |
| 109 | available for alternate use-cases. |
| 110 | |
Michael Foord | c4448af | 2012-03-28 15:33:26 +0100 | [diff] [blame] | 111 | `patch` as function decorator, creating the mock for you and passing it into |
| 112 | the decorated function: |
Michael Foord | 87d01c5 | 2012-03-28 15:25:51 +0100 | [diff] [blame] | 113 | |
| 114 | .. doctest:: |
| 115 | |
| 116 | >>> @patch('__main__.SomeClass') |
Michael Foord | 5b0c6b1 | 2012-03-28 15:50:56 +0100 | [diff] [blame] | 117 | ... def function(normal_argument, mock_class): |
Michael Foord | 87d01c5 | 2012-03-28 15:25:51 +0100 | [diff] [blame] | 118 | ... print mock_class is SomeClass |
| 119 | ... |
Michael Foord | 5b0c6b1 | 2012-03-28 15:50:56 +0100 | [diff] [blame] | 120 | >>> function(None) |
Michael Foord | 87d01c5 | 2012-03-28 15:25:51 +0100 | [diff] [blame] | 121 | True |
| 122 | |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 123 | |
| 124 | Patching a class replaces the class with a `MagicMock` *instance*. If the |
| 125 | class is instantiated in the code under test then it will be the |
| 126 | :attr:`~Mock.return_value` of the mock that will be used. |
| 127 | |
| 128 | If the class is instantiated multiple times you could use |
| 129 | :attr:`~Mock.side_effect` to return a new mock each time. Alternatively you |
| 130 | can set the `return_value` to be anything you want. |
| 131 | |
| 132 | To configure return values on methods of *instances* on the patched class |
| 133 | you must do this on the `return_value`. For example: |
| 134 | |
| 135 | .. doctest:: |
| 136 | |
| 137 | >>> class Class(object): |
| 138 | ... def method(self): |
| 139 | ... pass |
| 140 | ... |
| 141 | >>> with patch('__main__.Class') as MockClass: |
| 142 | ... instance = MockClass.return_value |
| 143 | ... instance.method.return_value = 'foo' |
| 144 | ... assert Class() is instance |
| 145 | ... assert Class().method() == 'foo' |
| 146 | ... |
| 147 | |
| 148 | If you use `spec` or `spec_set` and `patch` is replacing a *class*, then the |
| 149 | return value of the created mock will have the same spec. |
| 150 | |
| 151 | .. doctest:: |
| 152 | |
| 153 | >>> Original = Class |
| 154 | >>> patcher = patch('__main__.Class', spec=True) |
| 155 | >>> MockClass = patcher.start() |
| 156 | >>> instance = MockClass() |
| 157 | >>> assert isinstance(instance, Original) |
| 158 | >>> patcher.stop() |
| 159 | |
| 160 | The `new_callable` argument is useful where you want to use an alternative |
| 161 | class to the default :class:`MagicMock` for the created mock. For example, if |
| 162 | you wanted a :class:`NonCallableMock` to be used: |
| 163 | |
| 164 | .. doctest:: |
| 165 | |
| 166 | >>> thing = object() |
| 167 | >>> with patch('__main__.thing', new_callable=NonCallableMock) as mock_thing: |
| 168 | ... assert thing is mock_thing |
| 169 | ... thing() |
| 170 | ... |
| 171 | Traceback (most recent call last): |
| 172 | ... |
| 173 | TypeError: 'NonCallableMock' object is not callable |
| 174 | |
| 175 | Another use case might be to replace an object with a `StringIO` instance: |
| 176 | |
| 177 | .. doctest:: |
| 178 | |
| 179 | >>> from StringIO import StringIO |
| 180 | >>> def foo(): |
| 181 | ... print 'Something' |
| 182 | ... |
| 183 | >>> @patch('sys.stdout', new_callable=StringIO) |
| 184 | ... def test(mock_stdout): |
| 185 | ... foo() |
| 186 | ... assert mock_stdout.getvalue() == 'Something\n' |
| 187 | ... |
| 188 | >>> test() |
| 189 | |
| 190 | When `patch` is creating a mock for you, it is common that the first thing |
| 191 | you need to do is to configure the mock. Some of that configuration can be done |
| 192 | in the call to patch. Any arbitrary keywords you pass into the call will be |
| 193 | used to set attributes on the created mock: |
| 194 | |
| 195 | .. doctest:: |
| 196 | |
| 197 | >>> patcher = patch('__main__.thing', first='one', second='two') |
| 198 | >>> mock_thing = patcher.start() |
| 199 | >>> mock_thing.first |
| 200 | 'one' |
| 201 | >>> mock_thing.second |
| 202 | 'two' |
| 203 | |
| 204 | As well as attributes on the created mock attributes, like the |
| 205 | :attr:`~Mock.return_value` and :attr:`~Mock.side_effect`, of child mocks can |
| 206 | also be configured. These aren't syntactically valid to pass in directly as |
| 207 | keyword arguments, but a dictionary with these as keys can still be expanded |
| 208 | into a `patch` call using `**`: |
| 209 | |
| 210 | .. doctest:: |
| 211 | |
| 212 | >>> config = {'method.return_value': 3, 'other.side_effect': KeyError} |
| 213 | >>> patcher = patch('__main__.thing', **config) |
| 214 | >>> mock_thing = patcher.start() |
| 215 | >>> mock_thing.method() |
| 216 | 3 |
| 217 | >>> mock_thing.other() |
| 218 | Traceback (most recent call last): |
| 219 | ... |
| 220 | KeyError |
| 221 | |
| 222 | |
| 223 | patch.object |
| 224 | ============ |
| 225 | |
Michael Foord | 08f4755 | 2012-03-25 17:39:04 +0100 | [diff] [blame] | 226 | .. function:: patch.object(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 227 | |
| 228 | patch the named member (`attribute`) on an object (`target`) with a mock |
| 229 | object. |
| 230 | |
| 231 | `patch.object` can be used as a decorator, class decorator or a context |
Michael Foord | af78a50 | 2012-03-13 17:00:04 -0700 | [diff] [blame] | 232 | manager. Arguments `new`, `spec`, `create`, `spec_set`, `autospec` and |
| 233 | `new_callable` have the same meaning as for `patch`. Like `patch`, |
| 234 | `patch.object` takes arbitrary keyword arguments for configuring the mock |
| 235 | object it creates. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 236 | |
| 237 | When used as a class decorator `patch.object` honours `patch.TEST_PREFIX` |
| 238 | for choosing which methods to wrap. |
| 239 | |
| 240 | You can either call `patch.object` with three arguments or two arguments. The |
| 241 | three argument form takes the object to be patched, the attribute name and the |
| 242 | object to replace the attribute with. |
| 243 | |
| 244 | When calling with the two argument form you omit the replacement object, and a |
| 245 | mock is created for you and passed in as an extra argument to the decorated |
| 246 | function: |
| 247 | |
| 248 | .. doctest:: |
| 249 | |
| 250 | >>> @patch.object(SomeClass, 'class_method') |
| 251 | ... def test(mock_method): |
| 252 | ... SomeClass.class_method(3) |
| 253 | ... mock_method.assert_called_with(3) |
| 254 | ... |
| 255 | >>> test() |
| 256 | |
| 257 | `spec`, `create` and the other arguments to `patch.object` have the same |
| 258 | meaning as they do for `patch`. |
| 259 | |
| 260 | |
| 261 | patch.dict |
| 262 | ========== |
| 263 | |
| 264 | .. function:: patch.dict(in_dict, values=(), clear=False, **kwargs) |
| 265 | |
| 266 | Patch a dictionary, or dictionary like object, and restore the dictionary |
| 267 | to its original state after the test. |
| 268 | |
| 269 | `in_dict` can be a dictionary or a mapping like container. If it is a |
| 270 | mapping then it must at least support getting, setting and deleting items |
| 271 | plus iterating over keys. |
| 272 | |
| 273 | `in_dict` can also be a string specifying the name of the dictionary, which |
| 274 | will then be fetched by importing it. |
| 275 | |
| 276 | `values` can be a dictionary of values to set in the dictionary. `values` |
| 277 | can also be an iterable of `(key, value)` pairs. |
| 278 | |
| 279 | If `clear` is True then the dictionary will be cleared before the new |
| 280 | values are set. |
| 281 | |
| 282 | `patch.dict` can also be called with arbitrary keyword arguments to set |
| 283 | values in the dictionary. |
| 284 | |
| 285 | `patch.dict` can be used as a context manager, decorator or class |
| 286 | decorator. When used as a class decorator `patch.dict` honours |
| 287 | `patch.TEST_PREFIX` for choosing which methods to wrap. |
| 288 | |
| 289 | `patch.dict` can be used to add members to a dictionary, or simply let a test |
| 290 | change a dictionary, and ensure the dictionary is restored when the test |
| 291 | ends. |
| 292 | |
| 293 | .. doctest:: |
| 294 | |
| 295 | >>> from mock import patch |
| 296 | >>> foo = {} |
| 297 | >>> with patch.dict(foo, {'newkey': 'newvalue'}): |
| 298 | ... assert foo == {'newkey': 'newvalue'} |
| 299 | ... |
| 300 | >>> assert foo == {} |
| 301 | |
| 302 | >>> import os |
| 303 | >>> with patch.dict('os.environ', {'newkey': 'newvalue'}): |
| 304 | ... print os.environ['newkey'] |
| 305 | ... |
| 306 | newvalue |
| 307 | >>> assert 'newkey' not in os.environ |
| 308 | |
| 309 | Keywords can be used in the `patch.dict` call to set values in the dictionary: |
| 310 | |
| 311 | .. doctest:: |
| 312 | |
| 313 | >>> mymodule = MagicMock() |
| 314 | >>> mymodule.function.return_value = 'fish' |
| 315 | >>> with patch.dict('sys.modules', mymodule=mymodule): |
| 316 | ... import mymodule |
| 317 | ... mymodule.function('some', 'args') |
| 318 | ... |
| 319 | 'fish' |
| 320 | |
| 321 | `patch.dict` can be used with dictionary like objects that aren't actually |
| 322 | dictionaries. At the very minimum they must support item getting, setting, |
| 323 | deleting and either iteration or membership test. This corresponds to the |
| 324 | magic methods `__getitem__`, `__setitem__`, `__delitem__` and either |
| 325 | `__iter__` or `__contains__`. |
| 326 | |
| 327 | .. doctest:: |
| 328 | |
| 329 | >>> class Container(object): |
| 330 | ... def __init__(self): |
| 331 | ... self.values = {} |
| 332 | ... def __getitem__(self, name): |
| 333 | ... return self.values[name] |
| 334 | ... def __setitem__(self, name, value): |
| 335 | ... self.values[name] = value |
| 336 | ... def __delitem__(self, name): |
| 337 | ... del self.values[name] |
| 338 | ... def __iter__(self): |
| 339 | ... return iter(self.values) |
| 340 | ... |
| 341 | >>> thing = Container() |
| 342 | >>> thing['one'] = 1 |
| 343 | >>> with patch.dict(thing, one=2, two=3): |
| 344 | ... assert thing['one'] == 2 |
| 345 | ... assert thing['two'] == 3 |
| 346 | ... |
| 347 | >>> assert thing['one'] == 1 |
| 348 | >>> assert list(thing) == ['one'] |
| 349 | |
| 350 | |
| 351 | patch.multiple |
| 352 | ============== |
| 353 | |
Michael Foord | 08f4755 | 2012-03-25 17:39:04 +0100 | [diff] [blame] | 354 | .. function:: patch.multiple(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, **kwargs) |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 355 | |
| 356 | Perform multiple patches in a single call. It takes the object to be |
| 357 | patched (either as an object or a string to fetch the object by importing) |
| 358 | and keyword arguments for the patches:: |
| 359 | |
| 360 | with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'): |
| 361 | ... |
| 362 | |
| 363 | Use :data:`DEFAULT` as the value if you want `patch.multiple` to create |
| 364 | mocks for you. In this case the created mocks are passed into a decorated |
| 365 | function by keyword, and a dictionary is returned when `patch.multiple` is |
| 366 | used as a context manager. |
| 367 | |
| 368 | `patch.multiple` can be used as a decorator, class decorator or a context |
Michael Foord | af78a50 | 2012-03-13 17:00:04 -0700 | [diff] [blame] | 369 | manager. The arguments `spec`, `spec_set`, `create`, `autospec` and |
| 370 | `new_callable` have the same meaning as for `patch`. These arguments will |
| 371 | be applied to *all* patches done by `patch.multiple`. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 372 | |
| 373 | When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX` |
| 374 | for choosing which methods to wrap. |
| 375 | |
| 376 | If you want `patch.multiple` to create mocks for you, then you can use |
| 377 | :data:`DEFAULT` as the value. If you use `patch.multiple` as a decorator |
| 378 | then the created mocks are passed into the decorated function by keyword. |
| 379 | |
| 380 | .. doctest:: |
| 381 | |
| 382 | >>> thing = object() |
| 383 | >>> other = object() |
| 384 | |
| 385 | >>> @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) |
| 386 | ... def test_function(thing, other): |
| 387 | ... assert isinstance(thing, MagicMock) |
| 388 | ... assert isinstance(other, MagicMock) |
| 389 | ... |
| 390 | >>> test_function() |
| 391 | |
| 392 | `patch.multiple` can be nested with other `patch` decorators, but put arguments |
| 393 | passed by keyword *after* any of the standard arguments created by `patch`: |
| 394 | |
| 395 | .. doctest:: |
| 396 | |
| 397 | >>> @patch('sys.exit') |
| 398 | ... @patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) |
| 399 | ... def test_function(mock_exit, other, thing): |
| 400 | ... assert 'other' in repr(other) |
| 401 | ... assert 'thing' in repr(thing) |
| 402 | ... assert 'exit' in repr(mock_exit) |
| 403 | ... |
| 404 | >>> test_function() |
| 405 | |
| 406 | If `patch.multiple` is used as a context manager, the value returned by the |
| 407 | context manger is a dictionary where created mocks are keyed by name: |
| 408 | |
| 409 | .. doctest:: |
| 410 | |
| 411 | >>> with patch.multiple('__main__', thing=DEFAULT, other=DEFAULT) as values: |
| 412 | ... assert 'other' in repr(values['other']) |
| 413 | ... assert 'thing' in repr(values['thing']) |
| 414 | ... assert values['thing'] is thing |
| 415 | ... assert values['other'] is other |
| 416 | ... |
| 417 | |
| 418 | |
| 419 | .. _start-and-stop: |
| 420 | |
| 421 | patch methods: start and stop |
| 422 | ============================= |
| 423 | |
| 424 | All the patchers have `start` and `stop` methods. These make it simpler to do |
| 425 | patching in `setUp` methods or where you want to do multiple patches without |
| 426 | nesting decorators or with statements. |
| 427 | |
| 428 | To use them call `patch`, `patch.object` or `patch.dict` as normal and keep a |
| 429 | reference to the returned `patcher` object. You can then call `start` to put |
| 430 | the patch in place and `stop` to undo it. |
| 431 | |
| 432 | If you are using `patch` to create a mock for you then it will be returned by |
| 433 | the call to `patcher.start`. |
| 434 | |
| 435 | .. doctest:: |
| 436 | |
| 437 | >>> patcher = patch('package.module.ClassName') |
| 438 | >>> from package import module |
| 439 | >>> original = module.ClassName |
| 440 | >>> new_mock = patcher.start() |
| 441 | >>> assert module.ClassName is not original |
| 442 | >>> assert module.ClassName is new_mock |
| 443 | >>> patcher.stop() |
| 444 | >>> assert module.ClassName is original |
| 445 | >>> assert module.ClassName is not new_mock |
| 446 | |
| 447 | |
| 448 | A typical use case for this might be for doing multiple patches in the `setUp` |
| 449 | method of a `TestCase`: |
| 450 | |
| 451 | .. doctest:: |
| 452 | |
| 453 | >>> class MyTest(TestCase): |
| 454 | ... def setUp(self): |
| 455 | ... self.patcher1 = patch('package.module.Class1') |
| 456 | ... self.patcher2 = patch('package.module.Class2') |
| 457 | ... self.MockClass1 = self.patcher1.start() |
| 458 | ... self.MockClass2 = self.patcher2.start() |
| 459 | ... |
| 460 | ... def tearDown(self): |
| 461 | ... self.patcher1.stop() |
| 462 | ... self.patcher2.stop() |
| 463 | ... |
| 464 | ... def test_something(self): |
| 465 | ... assert package.module.Class1 is self.MockClass1 |
| 466 | ... assert package.module.Class2 is self.MockClass2 |
| 467 | ... |
| 468 | >>> MyTest('test_something').run() |
| 469 | |
| 470 | .. caution:: |
| 471 | |
| 472 | If you use this technique you must ensure that the patching is "undone" by |
| 473 | calling `stop`. This can be fiddlier than you might think, because if an |
| 474 | exception is raised in the setUp then tearDown is not called. `unittest2 |
| 475 | <http://pypi.python.org/pypi/unittest2>`_ cleanup functions make this |
| 476 | easier. |
| 477 | |
| 478 | .. doctest:: |
| 479 | |
| 480 | >>> class MyTest(TestCase): |
| 481 | ... def setUp(self): |
| 482 | ... patcher = patch('package.module.Class') |
| 483 | ... self.MockClass = patcher.start() |
| 484 | ... self.addCleanup(patcher.stop) |
| 485 | ... |
| 486 | ... def test_something(self): |
| 487 | ... assert package.module.Class is self.MockClass |
| 488 | ... |
| 489 | >>> MyTest('test_something').run() |
| 490 | |
| 491 | As an added bonus you no longer need to keep a reference to the `patcher` |
| 492 | object. |
| 493 | |
Michael Foord | 99dc7a5 | 2012-06-10 20:29:40 +0100 | [diff] [blame] | 494 | It is also possible to stop all patches which have been started by using |
| 495 | `patch.stopall`. |
| 496 | |
| 497 | .. function:: patch.stopall |
| 498 | |
Michael Foord | 2bfaa5e | 2012-06-11 16:29:52 +0100 | [diff] [blame] | 499 | Stop all active patches. Only stops patches started with `start`. |
Michael Foord | 1e68bec | 2012-03-03 22:24:30 +0000 | [diff] [blame] | 500 | |
| 501 | |
| 502 | TEST_PREFIX |
| 503 | =========== |
| 504 | |
| 505 | All of the patchers can be used as class decorators. When used in this way |
| 506 | they wrap every test method on the class. The patchers recognise methods that |
| 507 | start with `test` as being test methods. This is the same way that the |
| 508 | `unittest.TestLoader` finds test methods by default. |
| 509 | |
| 510 | It is possible that you want to use a different prefix for your tests. You can |
| 511 | inform the patchers of the different prefix by setting `patch.TEST_PREFIX`: |
| 512 | |
| 513 | .. doctest:: |
| 514 | |
| 515 | >>> patch.TEST_PREFIX = 'foo' |
| 516 | >>> value = 3 |
| 517 | >>> |
| 518 | >>> @patch('__main__.value', 'not three') |
| 519 | ... class Thing(object): |
| 520 | ... def foo_one(self): |
| 521 | ... print value |
| 522 | ... def foo_two(self): |
| 523 | ... print value |
| 524 | ... |
| 525 | >>> |
| 526 | >>> Thing().foo_one() |
| 527 | not three |
| 528 | >>> Thing().foo_two() |
| 529 | not three |
| 530 | >>> value |
| 531 | 3 |
| 532 | |
| 533 | |
| 534 | Nesting Patch Decorators |
| 535 | ======================== |
| 536 | |
| 537 | If you want to perform multiple patches then you can simply stack up the |
| 538 | decorators. |
| 539 | |
| 540 | You can stack up multiple patch decorators using this pattern: |
| 541 | |
| 542 | .. doctest:: |
| 543 | |
| 544 | >>> @patch.object(SomeClass, 'class_method') |
| 545 | ... @patch.object(SomeClass, 'static_method') |
| 546 | ... def test(mock1, mock2): |
| 547 | ... assert SomeClass.static_method is mock1 |
| 548 | ... assert SomeClass.class_method is mock2 |
| 549 | ... SomeClass.static_method('foo') |
| 550 | ... SomeClass.class_method('bar') |
| 551 | ... return mock1, mock2 |
| 552 | ... |
| 553 | >>> mock1, mock2 = test() |
| 554 | >>> mock1.assert_called_once_with('foo') |
| 555 | >>> mock2.assert_called_once_with('bar') |
| 556 | |
| 557 | |
| 558 | Note that the decorators are applied from the bottom upwards. This is the |
| 559 | standard way that Python applies decorators. The order of the created mocks |
| 560 | passed into your test function matches this order. |
| 561 | |
| 562 | Like all context-managers patches can be nested using contextlib's nested |
| 563 | function; *every* patching will appear in the tuple after "as": |
| 564 | |
| 565 | .. doctest:: |
| 566 | |
| 567 | >>> from contextlib import nested |
| 568 | >>> with nested( |
| 569 | ... patch('package.module.ClassName1'), |
| 570 | ... patch('package.module.ClassName2') |
| 571 | ... ) as (MockClass1, MockClass2): |
| 572 | ... assert package.module.ClassName1 is MockClass1 |
| 573 | ... assert package.module.ClassName2 is MockClass2 |
| 574 | ... |
| 575 | |
| 576 | |
| 577 | .. _where-to-patch: |
| 578 | |
| 579 | Where to patch |
| 580 | ============== |
| 581 | |
| 582 | `patch` works by (temporarily) changing the object that a *name* points to with |
| 583 | another one. There can be many names pointing to any individual object, so |
| 584 | for patching to work you must ensure that you patch the name used by the system |
| 585 | under test. |
| 586 | |
| 587 | The basic principle is that you patch where an object is *looked up*, which |
| 588 | is not necessarily the same place as where it is defined. A couple of |
| 589 | examples will help to clarify this. |
| 590 | |
| 591 | Imagine we have a project that we want to test with the following structure:: |
| 592 | |
| 593 | a.py |
| 594 | -> Defines SomeClass |
| 595 | |
| 596 | b.py |
| 597 | -> from a import SomeClass |
| 598 | -> some_function instantiates SomeClass |
| 599 | |
| 600 | Now we want to test `some_function` but we want to mock out `SomeClass` using |
| 601 | `patch`. The problem is that when we import module b, which we will have to |
| 602 | do then it imports `SomeClass` from module a. If we use `patch` to mock out |
| 603 | `a.SomeClass` then it will have no effect on our test; module b already has a |
| 604 | reference to the *real* `SomeClass` and it looks like our patching had no |
| 605 | effect. |
| 606 | |
| 607 | The key is to patch out `SomeClass` where it is used (or where it is looked up |
| 608 | ). In this case `some_function` will actually look up `SomeClass` in module b, |
| 609 | where we have imported it. The patching should look like: |
| 610 | |
| 611 | `@patch('b.SomeClass')` |
| 612 | |
| 613 | However, consider the alternative scenario where instead of `from a import |
| 614 | SomeClass` module b does `import a` and `some_function` uses `a.SomeClass`. Both |
| 615 | of these import forms are common. In this case the class we want to patch is |
| 616 | being looked up on the a module and so we have to patch `a.SomeClass` instead: |
| 617 | |
| 618 | `@patch('a.SomeClass')` |
| 619 | |
| 620 | |
| 621 | Patching Descriptors and Proxy Objects |
| 622 | ====================================== |
| 623 | |
| 624 | Since version 0.6.0 both patch_ and patch.object_ have been able to correctly |
| 625 | patch and restore descriptors: class methods, static methods and properties. |
| 626 | You should patch these on the *class* rather than an instance. |
| 627 | |
| 628 | Since version 0.7.0 patch_ and patch.object_ work correctly with some objects |
| 629 | that proxy attribute access, like the `django setttings object |
| 630 | <http://www.voidspace.org.uk/python/weblog/arch_d7_2010_12_04.shtml#e1198>`_. |
| 631 | |
| 632 | .. note:: |
| 633 | |
| 634 | In django `import settings` and `from django.conf import settings` |
| 635 | return different objects. If you are using libraries / apps that do both you |
| 636 | may have to patch both. Grrr... |