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