| The Mock Class |
| ============== |
| |
| .. currentmodule:: mock |
| |
| .. testsetup:: |
| |
| class SomeClass: |
| pass |
| |
| |
| `Mock` is a flexible mock object intended to replace the use of stubs and |
| test doubles throughout your code. Mocks are callable and create attributes as |
| new mocks when you access them [#]_. Accessing the same attribute will always |
| return the same mock. Mocks record how you use them, allowing you to make |
| assertions about what your code has done to them. |
| |
| :class:`MagicMock` is a subclass of `Mock` with all the magic methods |
| pre-created and ready to use. There are also non-callable variants, useful |
| when you are mocking out objects that aren't callable: |
| :class:`NonCallableMock` and :class:`NonCallableMagicMock` |
| |
| The :func:`patch` decorators makes it easy to temporarily replace classes |
| in a particular module with a `Mock` object. By default `patch` will create |
| a `MagicMock` for you. You can specify an alternative class of `Mock` using |
| the `new_callable` argument to `patch`. |
| |
| |
| .. index:: side_effect |
| .. index:: return_value |
| .. index:: wraps |
| .. index:: name |
| .. index:: spec |
| |
| .. class:: Mock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, **kwargs) |
| |
| Create a new `Mock` object. `Mock` takes several optional arguments |
| that specify the behaviour of the Mock object: |
| |
| * `spec`: This can be either a list of strings or an existing object (a |
| class or instance) that acts as the specification for the mock object. If |
| you pass in an object then a list of strings is formed by calling dir on |
| the object (excluding unsupported magic attributes and methods). |
| Accessing any attribute not in this list will raise an `AttributeError`. |
| |
| If `spec` is an object (rather than a list of strings) then |
| :attr:`__class__` returns the class of the spec object. This allows mocks |
| to pass `isinstance` tests. |
| |
| * `spec_set`: A stricter variant of `spec`. If used, attempting to *set* |
| or get an attribute on the mock that isn't on the object passed as |
| `spec_set` will raise an `AttributeError`. |
| |
| * `side_effect`: A function to be called whenever the Mock is called. See |
| the :attr:`~Mock.side_effect` attribute. Useful for raising exceptions or |
| dynamically changing return values. The function is called with the same |
| arguments as the mock, and unless it returns :data:`DEFAULT`, the return |
| value of this function is used as the return value. |
| |
| Alternatively `side_effect` can be an exception class or instance. In |
| this case the exception will be raised when the mock is called. |
| |
| If `side_effect` is an iterable then each call to the mock will return |
| the next value from the iterable. If any of the members of the iterable |
| are exceptions they will be raised instead of returned. |
| |
| A `side_effect` can be cleared by setting it to `None`. |
| |
| * `return_value`: The value returned when the mock is called. By default |
| this is a new Mock (created on first access). See the |
| :attr:`return_value` attribute. |
| |
| * `wraps`: Item for the mock object to wrap. If `wraps` is not None then |
| calling the Mock will pass the call through to the wrapped object |
| (returning the real result and ignoring `return_value`). Attribute access |
| on the mock will return a Mock object that wraps the corresponding |
| attribute of the wrapped object (so attempting to access an attribute |
| that doesn't exist will raise an `AttributeError`). |
| |
| If the mock has an explicit `return_value` set then calls are not passed |
| to the wrapped object and the `return_value` is returned instead. |
| |
| * `name`: If the mock has a name then it will be used in the repr of the |
| mock. This can be useful for debugging. The name is propagated to child |
| mocks. |
| |
| Mocks can also be called with arbitrary keyword arguments. These will be |
| used to set attributes on the mock after it is created. See the |
| :meth:`configure_mock` method for details. |
| |
| |
| .. method:: assert_called_with(*args, **kwargs) |
| |
| This method is a convenient way of asserting that calls are made in a |
| particular way: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.method(1, 2, 3, test='wow') |
| <Mock name='mock.method()' id='...'> |
| >>> mock.method.assert_called_with(1, 2, 3, test='wow') |
| |
| |
| .. method:: assert_called_once_with(*args, **kwargs) |
| |
| Assert that the mock was called exactly once and with the specified |
| arguments. |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock('foo', bar='baz') |
| >>> mock.assert_called_once_with('foo', bar='baz') |
| >>> mock('foo', bar='baz') |
| >>> mock.assert_called_once_with('foo', bar='baz') |
| Traceback (most recent call last): |
| ... |
| AssertionError: Expected to be called once. Called 2 times. |
| |
| |
| .. method:: assert_any_call(*args, **kwargs) |
| |
| assert the mock has been called with the specified arguments. |
| |
| The assert passes if the mock has *ever* been called, unlike |
| :meth:`assert_called_with` and :meth:`assert_called_once_with` that |
| only pass if the call is the most recent one. |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock(1, 2, arg='thing') |
| >>> mock('some', 'thing', 'else') |
| >>> mock.assert_any_call(1, 2, arg='thing') |
| |
| |
| .. method:: assert_has_calls(calls, any_order=False) |
| |
| assert the mock has been called with the specified calls. |
| The `mock_calls` list is checked for the calls. |
| |
| If `any_order` is False (the default) then the calls must be |
| sequential. There can be extra calls before or after the |
| specified calls. |
| |
| If `any_order` is True then the calls can be in any order, but |
| they must all appear in :attr:`mock_calls`. |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock(1) |
| >>> mock(2) |
| >>> mock(3) |
| >>> mock(4) |
| >>> calls = [call(2), call(3)] |
| >>> mock.assert_has_calls(calls) |
| >>> calls = [call(4), call(2), call(3)] |
| >>> mock.assert_has_calls(calls, any_order=True) |
| |
| |
| .. method:: reset_mock() |
| |
| The reset_mock method resets all the call attributes on a mock object: |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock('hello') |
| >>> mock.called |
| True |
| >>> mock.reset_mock() |
| >>> mock.called |
| False |
| |
| This can be useful where you want to make a series of assertions that |
| reuse the same object. Note that `reset_mock` *doesn't* clear the |
| return value, :attr:`side_effect` or any child attributes you have |
| set using normal assignment. Child mocks and the return value mock |
| (if any) are reset as well. |
| |
| |
| .. method:: mock_add_spec(spec, spec_set=False) |
| |
| Add a spec to a mock. `spec` can either be an object or a |
| list of strings. Only attributes on the `spec` can be fetched as |
| attributes from the mock. |
| |
| If `spec_set` is `True` then only attributes on the spec can be set. |
| |
| |
| .. method:: attach_mock(mock, attribute) |
| |
| Attach a mock as an attribute of this one, replacing its name and |
| parent. Calls to the attached mock will be recorded in the |
| :attr:`method_calls` and :attr:`mock_calls` attributes of this one. |
| |
| |
| .. method:: configure_mock(**kwargs) |
| |
| Set attributes on the mock through keyword arguments. |
| |
| Attributes plus return values and side effects can be set on child |
| mocks using standard dot notation and unpacking a dictionary in the |
| method call: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} |
| >>> mock.configure_mock(**attrs) |
| >>> mock.method() |
| 3 |
| >>> mock.other() |
| Traceback (most recent call last): |
| ... |
| KeyError |
| |
| The same thing can be achieved in the constructor call to mocks: |
| |
| .. doctest:: |
| |
| >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} |
| >>> mock = Mock(some_attribute='eggs', **attrs) |
| >>> mock.some_attribute |
| 'eggs' |
| >>> mock.method() |
| 3 |
| >>> mock.other() |
| Traceback (most recent call last): |
| ... |
| KeyError |
| |
| `configure_mock` exists to make it easier to do configuration |
| after the mock has been created. |
| |
| |
| .. method:: __dir__() |
| |
| `Mock` objects limit the results of `dir(some_mock)` to useful results. |
| For mocks with a `spec` this includes all the permitted attributes |
| for the mock. |
| |
| See :data:`FILTER_DIR` for what this filtering does, and how to |
| switch it off. |
| |
| |
| .. method:: _get_child_mock(**kw) |
| |
| Create the child mocks for attributes and return value. |
| By default child mocks will be the same type as the parent. |
| Subclasses of Mock may want to override this to customize the way |
| child mocks are made. |
| |
| For non-callable mocks the callable variant will be used (rather than |
| any custom subclass). |
| |
| |
| .. attribute:: called |
| |
| A boolean representing whether or not the mock object has been called: |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock.called |
| False |
| >>> mock() |
| >>> mock.called |
| True |
| |
| .. attribute:: call_count |
| |
| An integer telling you how many times the mock object has been called: |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock.call_count |
| 0 |
| >>> mock() |
| >>> mock() |
| >>> mock.call_count |
| 2 |
| |
| |
| .. attribute:: return_value |
| |
| Set this to configure the value returned by calling the mock: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.return_value = 'fish' |
| >>> mock() |
| 'fish' |
| |
| The default return value is a mock object and you can configure it in |
| the normal way: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.return_value.attribute = sentinel.Attribute |
| >>> mock.return_value() |
| <Mock name='mock()()' id='...'> |
| >>> mock.return_value.assert_called_with() |
| |
| `return_value` can also be set in the constructor: |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=3) |
| >>> mock.return_value |
| 3 |
| >>> mock() |
| 3 |
| |
| |
| .. attribute:: side_effect |
| |
| This can either be a function to be called when the mock is called, |
| or an exception (class or instance) to be raised. |
| |
| If you pass in a function it will be called with same arguments as the |
| mock and unless the function returns the :data:`DEFAULT` singleton the |
| call to the mock will then return whatever the function returns. If the |
| function returns :data:`DEFAULT` then the mock will return its normal |
| value (from the :attr:`return_value`. |
| |
| An example of a mock that raises an exception (to test exception |
| handling of an API): |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.side_effect = Exception('Boom!') |
| >>> mock() |
| Traceback (most recent call last): |
| ... |
| Exception: Boom! |
| |
| Using `side_effect` to return a sequence of values: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.side_effect = [3, 2, 1] |
| >>> mock(), mock(), mock() |
| (3, 2, 1) |
| |
| The `side_effect` function is called with the same arguments as the |
| mock (so it is wise for it to take arbitrary args and keyword |
| arguments) and whatever it returns is used as the return value for |
| the call. The exception is if `side_effect` returns :data:`DEFAULT`, |
| in which case the normal :attr:`return_value` is used. |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=3) |
| >>> def side_effect(*args, **kwargs): |
| ... return DEFAULT |
| ... |
| >>> mock.side_effect = side_effect |
| >>> mock() |
| 3 |
| |
| `side_effect` can be set in the constructor. Here's an example that |
| adds one to the value the mock is called with and returns it: |
| |
| .. doctest:: |
| |
| >>> side_effect = lambda value: value + 1 |
| >>> mock = Mock(side_effect=side_effect) |
| >>> mock(3) |
| 4 |
| >>> mock(-8) |
| -7 |
| |
| Setting `side_effect` to `None` clears it: |
| |
| .. doctest:: |
| |
| >>> from mock import Mock |
| >>> m = Mock(side_effect=KeyError, return_value=3) |
| >>> m() |
| Traceback (most recent call last): |
| ... |
| KeyError |
| >>> m.side_effect = None |
| >>> m() |
| 3 |
| |
| |
| .. attribute:: call_args |
| |
| This is either `None` (if the mock hasn't been called), or the |
| arguments that the mock was last called with. This will be in the |
| form of a tuple: the first member is any ordered arguments the mock |
| was called with (or an empty tuple) and the second member is any |
| keyword arguments (or an empty dictionary). |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> print mock.call_args |
| None |
| >>> mock() |
| >>> mock.call_args |
| call() |
| >>> mock.call_args == () |
| True |
| >>> mock(3, 4) |
| >>> mock.call_args |
| call(3, 4) |
| >>> mock.call_args == ((3, 4),) |
| True |
| >>> mock(3, 4, 5, key='fish', next='w00t!') |
| >>> mock.call_args |
| call(3, 4, 5, key='fish', next='w00t!') |
| |
| `call_args`, along with members of the lists :attr:`call_args_list`, |
| :attr:`method_calls` and :attr:`mock_calls` are :data:`call` objects. |
| These are tuples, so they can be unpacked to get at the individual |
| arguments and make more complex assertions. See |
| :ref:`calls as tuples <calls-as-tuples>`. |
| |
| |
| .. attribute:: call_args_list |
| |
| This is a list of all the calls made to the mock object in sequence |
| (so the length of the list is the number of times it has been |
| called). Before any calls have been made it is an empty list. The |
| :data:`call` object can be used for conveniently constructing lists of |
| calls to compare with `call_args_list`. |
| |
| .. doctest:: |
| |
| >>> mock = Mock(return_value=None) |
| >>> mock() |
| >>> mock(3, 4) |
| >>> mock(key='fish', next='w00t!') |
| >>> mock.call_args_list |
| [call(), call(3, 4), call(key='fish', next='w00t!')] |
| >>> expected = [(), ((3, 4),), ({'key': 'fish', 'next': 'w00t!'},)] |
| >>> mock.call_args_list == expected |
| True |
| |
| Members of `call_args_list` are :data:`call` objects. These can be |
| unpacked as tuples to get at the individual arguments. See |
| :ref:`calls as tuples <calls-as-tuples>`. |
| |
| |
| .. attribute:: method_calls |
| |
| As well as tracking calls to themselves, mocks also track calls to |
| methods and attributes, and *their* methods and attributes: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.method() |
| <Mock name='mock.method()' id='...'> |
| >>> mock.property.method.attribute() |
| <Mock name='mock.property.method.attribute()' id='...'> |
| >>> mock.method_calls |
| [call.method(), call.property.method.attribute()] |
| |
| Members of `method_calls` are :data:`call` objects. These can be |
| unpacked as tuples to get at the individual arguments. See |
| :ref:`calls as tuples <calls-as-tuples>`. |
| |
| |
| .. attribute:: mock_calls |
| |
| `mock_calls` records *all* calls to the mock object, its methods, magic |
| methods *and* return value mocks. |
| |
| .. doctest:: |
| |
| >>> mock = MagicMock() |
| >>> result = mock(1, 2, 3) |
| >>> mock.first(a=3) |
| <MagicMock name='mock.first()' id='...'> |
| >>> mock.second() |
| <MagicMock name='mock.second()' id='...'> |
| >>> int(mock) |
| 1 |
| >>> result(1) |
| <MagicMock name='mock()()' id='...'> |
| >>> expected = [call(1, 2, 3), call.first(a=3), call.second(), |
| ... call.__int__(), call()(1)] |
| >>> mock.mock_calls == expected |
| True |
| |
| Members of `mock_calls` are :data:`call` objects. These can be |
| unpacked as tuples to get at the individual arguments. See |
| :ref:`calls as tuples <calls-as-tuples>`. |
| |
| |
| .. attribute:: __class__ |
| |
| Normally the `__class__` attribute of an object will return its type. |
| For a mock object with a `spec` `__class__` returns the spec class |
| instead. This allows mock objects to pass `isinstance` tests for the |
| object they are replacing / masquerading as: |
| |
| .. doctest:: |
| |
| >>> mock = Mock(spec=3) |
| >>> isinstance(mock, int) |
| True |
| |
| `__class__` is assignable to, this allows a mock to pass an |
| `isinstance` check without forcing you to use a spec: |
| |
| .. doctest:: |
| |
| >>> mock = Mock() |
| >>> mock.__class__ = dict |
| >>> isinstance(mock, dict) |
| True |
| |
| .. class:: NonCallableMock(spec=None, wraps=None, name=None, spec_set=None, **kwargs) |
| |
| A non-callable version of `Mock`. The constructor parameters have the same |
| meaning of `Mock`, with the exception of `return_value` and `side_effect` |
| which have no meaning on a non-callable mock. |
| |
| Mock objects that use a class or an instance as a `spec` or `spec_set` are able |
| to pass `isintance` tests: |
| |
| .. doctest:: |
| |
| >>> mock = Mock(spec=SomeClass) |
| >>> isinstance(mock, SomeClass) |
| True |
| >>> mock = Mock(spec_set=SomeClass()) |
| >>> isinstance(mock, SomeClass) |
| True |
| |
| The `Mock` classes have support for mocking magic methods. See :ref:`magic |
| methods <magic-methods>` for the full details. |
| |
| The mock classes and the :func:`patch` decorators all take arbitrary keyword |
| arguments for configuration. For the `patch` decorators the keywords are |
| passed to the constructor of the mock being created. The keyword arguments |
| are for configuring attributes of the mock: |
| |
| .. doctest:: |
| |
| >>> m = MagicMock(attribute=3, other='fish') |
| >>> m.attribute |
| 3 |
| >>> m.other |
| 'fish' |
| |
| The return value and side effect of child mocks can be set in the same way, |
| using dotted notation. As you can't use dotted names directly in a call you |
| have to create a dictionary and unpack it using `**`: |
| |
| .. doctest:: |
| |
| >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError} |
| >>> mock = Mock(some_attribute='eggs', **attrs) |
| >>> mock.some_attribute |
| 'eggs' |
| >>> mock.method() |
| 3 |
| >>> mock.other() |
| Traceback (most recent call last): |
| ... |
| KeyError |
| |
| |
| .. class:: PropertyMock(*args, **kwargs) |
| |
| A mock intended to be used as a property, or other descriptor, on a class. |
| `PropertyMock` provides `__get__` and `__set__` methods so you can specify |
| a return value when it is fetched. |
| |
| Fetching a `PropertyMock` instance from an object calls the mock, with |
| no args. Setting it calls the mock with the value being set. |
| |
| .. doctest:: |
| |
| >>> class Foo(object): |
| ... @property |
| ... def foo(self): |
| ... return 'something' |
| ... @foo.setter |
| ... def foo(self, value): |
| ... pass |
| ... |
| >>> with patch('__main__.Foo.foo', new_callable=PropertyMock) as mock_foo: |
| ... mock_foo.return_value = 'mockity-mock' |
| ... this_foo = Foo() |
| ... print this_foo.foo |
| ... this_foo.foo = 6 |
| ... |
| mockity-mock |
| >>> mock_foo.mock_calls |
| [call(), call(6)] |
| |
| Because of the way mock attributes are stored you can't directly attach a |
| `PropertyMock` to a mock object. Instead you can attach it to the mock type |
| object: |
| |
| .. doctest:: |
| |
| >>> m = MagicMock() |
| >>> p = PropertyMock(return_value=3) |
| >>> type(m).foo = p |
| >>> m.foo |
| 3 |
| >>> p.assert_called_once_with() |
| |
| |
| .. index:: __call__ |
| .. index:: calling |
| |
| Calling |
| ======= |
| |
| Mock objects are callable. The call will return the value set as the |
| :attr:`~Mock.return_value` attribute. The default return value is a new Mock |
| object; it is created the first time the return value is accessed (either |
| explicitly or by calling the Mock) - but it is stored and the same one |
| returned each time. |
| |
| Calls made to the object will be recorded in the attributes |
| like :attr:`~Mock.call_args` and :attr:`~Mock.call_args_list`. |
| |
| If :attr:`~Mock.side_effect` is set then it will be called after the call has |
| been recorded, so if `side_effect` raises an exception the call is still |
| recorded. |
| |
| The simplest way to make a mock raise an exception when called is to make |
| :attr:`~Mock.side_effect` an exception class or instance: |
| |
| .. doctest:: |
| |
| >>> m = MagicMock(side_effect=IndexError) |
| >>> m(1, 2, 3) |
| Traceback (most recent call last): |
| ... |
| IndexError |
| >>> m.mock_calls |
| [call(1, 2, 3)] |
| >>> m.side_effect = KeyError('Bang!') |
| >>> m('two', 'three', 'four') |
| Traceback (most recent call last): |
| ... |
| KeyError: 'Bang!' |
| >>> m.mock_calls |
| [call(1, 2, 3), call('two', 'three', 'four')] |
| |
| If `side_effect` is a function then whatever that function returns is what |
| calls to the mock return. The `side_effect` function is called with the |
| same arguments as the mock. This allows you to vary the return value of the |
| call dynamically, based on the input: |
| |
| .. doctest:: |
| |
| >>> def side_effect(value): |
| ... return value + 1 |
| ... |
| >>> m = MagicMock(side_effect=side_effect) |
| >>> m(1) |
| 2 |
| >>> m(2) |
| 3 |
| >>> m.mock_calls |
| [call(1), call(2)] |
| |
| If you want the mock to still return the default return value (a new mock), or |
| any set return value, then there are two ways of doing this. Either return |
| `mock.return_value` from inside `side_effect`, or return :data:`DEFAULT`: |
| |
| .. doctest:: |
| |
| >>> m = MagicMock() |
| >>> def side_effect(*args, **kwargs): |
| ... return m.return_value |
| ... |
| >>> m.side_effect = side_effect |
| >>> m.return_value = 3 |
| >>> m() |
| 3 |
| >>> def side_effect(*args, **kwargs): |
| ... return DEFAULT |
| ... |
| >>> m.side_effect = side_effect |
| >>> m() |
| 3 |
| |
| To remove a `side_effect`, and return to the default behaviour, set the |
| `side_effect` to `None`: |
| |
| .. doctest:: |
| |
| >>> m = MagicMock(return_value=6) |
| >>> def side_effect(*args, **kwargs): |
| ... return 3 |
| ... |
| >>> m.side_effect = side_effect |
| >>> m() |
| 3 |
| >>> m.side_effect = None |
| >>> m() |
| 6 |
| |
| The `side_effect` can also be any iterable object. Repeated calls to the mock |
| will return values from the iterable (until the iterable is exhausted and |
| a `StopIteration` is raised): |
| |
| .. doctest:: |
| |
| >>> m = MagicMock(side_effect=[1, 2, 3]) |
| >>> m() |
| 1 |
| >>> m() |
| 2 |
| >>> m() |
| 3 |
| >>> m() |
| Traceback (most recent call last): |
| ... |
| StopIteration |
| |
| If any members of the iterable are exceptions they will be raised instead of |
| returned: |
| |
| .. doctest:: |
| |
| >>> iterable = (33, ValueError, 66) |
| >>> m = MagicMock(side_effect=iterable) |
| >>> m() |
| 33 |
| >>> m() |
| Traceback (most recent call last): |
| ... |
| ValueError |
| >>> m() |
| 66 |
| |
| |
| .. _deleting-attributes: |
| |
| Deleting Attributes |
| =================== |
| |
| Mock objects create attributes on demand. This allows them to pretend to be |
| objects of any type. |
| |
| You may want a mock object to return `False` to a `hasattr` call, or raise an |
| `AttributeError` when an attribute is fetched. You can do this by providing |
| an object as a `spec` for a mock, but that isn't always convenient. |
| |
| You "block" attributes by deleting them. Once deleted, accessing an attribute |
| will raise an `AttributeError`. |
| |
| .. doctest:: |
| |
| >>> mock = MagicMock() |
| >>> hasattr(mock, 'm') |
| True |
| >>> del mock.m |
| >>> hasattr(mock, 'm') |
| False |
| >>> del mock.f |
| >>> mock.f |
| Traceback (most recent call last): |
| ... |
| AttributeError: f |
| |
| |
| Attaching Mocks as Attributes |
| ============================= |
| |
| When you attach a mock as an attribute of another mock (or as the return |
| value) it becomes a "child" of that mock. Calls to the child are recorded in |
| the :attr:`~Mock.method_calls` and :attr:`~Mock.mock_calls` attributes of the |
| parent. This is useful for configuring child mocks and then attaching them to |
| the parent, or for attaching mocks to a parent that records all calls to the |
| children and allows you to make assertions about the order of calls between |
| mocks: |
| |
| .. doctest:: |
| |
| >>> parent = MagicMock() |
| >>> child1 = MagicMock(return_value=None) |
| >>> child2 = MagicMock(return_value=None) |
| >>> parent.child1 = child1 |
| >>> parent.child2 = child2 |
| >>> child1(1) |
| >>> child2(2) |
| >>> parent.mock_calls |
| [call.child1(1), call.child2(2)] |
| |
| The exception to this is if the mock has a name. This allows you to prevent |
| the "parenting" if for some reason you don't want it to happen. |
| |
| .. doctest:: |
| |
| >>> mock = MagicMock() |
| >>> not_a_child = MagicMock(name='not-a-child') |
| >>> mock.attribute = not_a_child |
| >>> mock.attribute() |
| <MagicMock name='not-a-child()' id='...'> |
| >>> mock.mock_calls |
| [] |
| |
| Mocks created for you by :func:`patch` are automatically given names. To |
| attach mocks that have names to a parent you use the :meth:`~Mock.attach_mock` |
| method: |
| |
| .. doctest:: |
| |
| >>> thing1 = object() |
| >>> thing2 = object() |
| >>> parent = MagicMock() |
| >>> with patch('__main__.thing1', return_value=None) as child1: |
| ... with patch('__main__.thing2', return_value=None) as child2: |
| ... parent.attach_mock(child1, 'child1') |
| ... parent.attach_mock(child2, 'child2') |
| ... child1('one') |
| ... child2('two') |
| ... |
| >>> parent.mock_calls |
| [call.child1('one'), call.child2('two')] |
| |
| |
| ----- |
| |
| .. [#] The only exceptions are magic methods and attributes (those that have |
| leading and trailing double underscores). Mock doesn't create these but |
| instead of raises an ``AttributeError``. This is because the interpreter |
| will often implicitly request these methods, and gets *very* confused to |
| get a new Mock object when it expects a magic method. If you need magic |
| method support see :ref:`magic methods <magic-methods>`. |
