mirror of
https://github.com/classilla/tenfourfox.git
synced 2024-11-08 22:11:52 +00:00
843 lines
27 KiB
Plaintext
843 lines
27 KiB
Plaintext
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>`.
|