forked from mirrors/gecko-dev
583 lines
19 KiB
Text
583 lines
19 KiB
Text
=========
|
|
Helpers
|
|
=========
|
|
|
|
.. currentmodule:: mock
|
|
|
|
.. testsetup::
|
|
|
|
mock.FILTER_DIR = True
|
|
from pprint import pprint as pp
|
|
original_dir = dir
|
|
def dir(obj):
|
|
print pp(original_dir(obj))
|
|
|
|
import urllib2
|
|
__main__.urllib2 = urllib2
|
|
|
|
.. testcleanup::
|
|
|
|
dir = original_dir
|
|
mock.FILTER_DIR = True
|
|
|
|
|
|
|
|
call
|
|
====
|
|
|
|
.. function:: call(*args, **kwargs)
|
|
|
|
`call` is a helper object for making simpler assertions, for comparing
|
|
with :attr:`~Mock.call_args`, :attr:`~Mock.call_args_list`,
|
|
:attr:`~Mock.mock_calls` and :attr: `~Mock.method_calls`. `call` can also be
|
|
used with :meth:`~Mock.assert_has_calls`.
|
|
|
|
.. doctest::
|
|
|
|
>>> m = MagicMock(return_value=None)
|
|
>>> m(1, 2, a='foo', b='bar')
|
|
>>> m()
|
|
>>> m.call_args_list == [call(1, 2, a='foo', b='bar'), call()]
|
|
True
|
|
|
|
.. method:: call.call_list()
|
|
|
|
For a call object that represents multiple calls, `call_list`
|
|
returns a list of all the intermediate calls as well as the
|
|
final call.
|
|
|
|
`call_list` is particularly useful for making assertions on "chained calls". A
|
|
chained call is multiple calls on a single line of code. This results in
|
|
multiple entries in :attr:`~Mock.mock_calls` on a mock. Manually constructing
|
|
the sequence of calls can be tedious.
|
|
|
|
:meth:`~call.call_list` can construct the sequence of calls from the same
|
|
chained call:
|
|
|
|
.. doctest::
|
|
|
|
>>> m = MagicMock()
|
|
>>> m(1).method(arg='foo').other('bar')(2.0)
|
|
<MagicMock name='mock().method().other()()' id='...'>
|
|
>>> kall = call(1).method(arg='foo').other('bar')(2.0)
|
|
>>> kall.call_list()
|
|
[call(1),
|
|
call().method(arg='foo'),
|
|
call().method().other('bar'),
|
|
call().method().other()(2.0)]
|
|
>>> m.mock_calls == kall.call_list()
|
|
True
|
|
|
|
.. _calls-as-tuples:
|
|
|
|
A `call` object is either a tuple of (positional args, keyword args) or
|
|
(name, positional args, keyword args) depending on how it was constructed. When
|
|
you construct them yourself this isn't particularly interesting, but the `call`
|
|
objects that are in the :attr:`Mock.call_args`, :attr:`Mock.call_args_list` and
|
|
:attr:`Mock.mock_calls` attributes can be introspected to get at the individual
|
|
arguments they contain.
|
|
|
|
The `call` objects in :attr:`Mock.call_args` and :attr:`Mock.call_args_list`
|
|
are two-tuples of (positional args, keyword args) whereas the `call` objects
|
|
in :attr:`Mock.mock_calls`, along with ones you construct yourself, are
|
|
three-tuples of (name, positional args, keyword args).
|
|
|
|
You can use their "tupleness" to pull out the individual arguments for more
|
|
complex introspection and assertions. The positional arguments are a tuple
|
|
(an empty tuple if there are no positional arguments) and the keyword
|
|
arguments are a dictionary:
|
|
|
|
.. doctest::
|
|
|
|
>>> m = MagicMock(return_value=None)
|
|
>>> m(1, 2, 3, arg='one', arg2='two')
|
|
>>> kall = m.call_args
|
|
>>> args, kwargs = kall
|
|
>>> args
|
|
(1, 2, 3)
|
|
>>> kwargs
|
|
{'arg2': 'two', 'arg': 'one'}
|
|
>>> args is kall[0]
|
|
True
|
|
>>> kwargs is kall[1]
|
|
True
|
|
|
|
>>> m = MagicMock()
|
|
>>> m.foo(4, 5, 6, arg='two', arg2='three')
|
|
<MagicMock name='mock.foo()' id='...'>
|
|
>>> kall = m.mock_calls[0]
|
|
>>> name, args, kwargs = kall
|
|
>>> name
|
|
'foo'
|
|
>>> args
|
|
(4, 5, 6)
|
|
>>> kwargs
|
|
{'arg2': 'three', 'arg': 'two'}
|
|
>>> name is m.mock_calls[0][0]
|
|
True
|
|
|
|
|
|
create_autospec
|
|
===============
|
|
|
|
.. function:: create_autospec(spec, spec_set=False, instance=False, **kwargs)
|
|
|
|
Create a mock object using another object as a spec. Attributes on the
|
|
mock will use the corresponding attribute on the `spec` object as their
|
|
spec.
|
|
|
|
Functions or methods being mocked will have their arguments checked to
|
|
ensure that they are called with the correct signature.
|
|
|
|
If `spec_set` is `True` then attempting to set attributes that don't exist
|
|
on the spec object will raise an `AttributeError`.
|
|
|
|
If a class is used as a spec then the return value of the mock (the
|
|
instance of the class) will have the same spec. You can use a class as the
|
|
spec for an instance object by passing `instance=True`. The returned mock
|
|
will only be callable if instances of the mock are callable.
|
|
|
|
`create_autospec` also takes arbitrary keyword arguments that are passed to
|
|
the constructor of the created mock.
|
|
|
|
See :ref:`auto-speccing` for examples of how to use auto-speccing with
|
|
`create_autospec` and the `autospec` argument to :func:`patch`.
|
|
|
|
|
|
ANY
|
|
===
|
|
|
|
.. data:: ANY
|
|
|
|
Sometimes you may need to make assertions about *some* of the arguments in a
|
|
call to mock, but either not care about some of the arguments or want to pull
|
|
them individually out of :attr:`~Mock.call_args` and make more complex
|
|
assertions on them.
|
|
|
|
To ignore certain arguments you can pass in objects that compare equal to
|
|
*everything*. Calls to :meth:`~Mock.assert_called_with` and
|
|
:meth:`~Mock.assert_called_once_with` will then succeed no matter what was
|
|
passed in.
|
|
|
|
.. doctest::
|
|
|
|
>>> mock = Mock(return_value=None)
|
|
>>> mock('foo', bar=object())
|
|
>>> mock.assert_called_once_with('foo', bar=ANY)
|
|
|
|
`ANY` can also be used in comparisons with call lists like
|
|
:attr:`~Mock.mock_calls`:
|
|
|
|
.. doctest::
|
|
|
|
>>> m = MagicMock(return_value=None)
|
|
>>> m(1)
|
|
>>> m(1, 2)
|
|
>>> m(object())
|
|
>>> m.mock_calls == [call(1), call(1, 2), ANY]
|
|
True
|
|
|
|
|
|
|
|
FILTER_DIR
|
|
==========
|
|
|
|
.. data:: FILTER_DIR
|
|
|
|
`FILTER_DIR` is a module level variable that controls the way mock objects
|
|
respond to `dir` (only for Python 2.6 or more recent). The default is `True`,
|
|
which uses the filtering described below, to only show useful members. If you
|
|
dislike this filtering, or need to switch it off for diagnostic purposes, then
|
|
set `mock.FILTER_DIR = False`.
|
|
|
|
With filtering on, `dir(some_mock)` shows only useful attributes and will
|
|
include any dynamically created attributes that wouldn't normally be shown.
|
|
If the mock was created with a `spec` (or `autospec` of course) then all the
|
|
attributes from the original are shown, even if they haven't been accessed
|
|
yet:
|
|
|
|
.. doctest::
|
|
|
|
>>> dir(Mock())
|
|
['assert_any_call',
|
|
'assert_called_once_with',
|
|
'assert_called_with',
|
|
'assert_has_calls',
|
|
'attach_mock',
|
|
...
|
|
>>> import urllib2
|
|
>>> dir(Mock(spec=urllib2))
|
|
['AbstractBasicAuthHandler',
|
|
'AbstractDigestAuthHandler',
|
|
'AbstractHTTPHandler',
|
|
'BaseHandler',
|
|
...
|
|
|
|
Many of the not-very-useful (private to `Mock` rather than the thing being
|
|
mocked) underscore and double underscore prefixed attributes have been
|
|
filtered from the result of calling `dir` on a `Mock`. If you dislike this
|
|
behaviour you can switch it off by setting the module level switch
|
|
`FILTER_DIR`:
|
|
|
|
.. doctest::
|
|
|
|
>>> import mock
|
|
>>> mock.FILTER_DIR = False
|
|
>>> dir(mock.Mock())
|
|
['_NonCallableMock__get_return_value',
|
|
'_NonCallableMock__get_side_effect',
|
|
'_NonCallableMock__return_value_doc',
|
|
'_NonCallableMock__set_return_value',
|
|
'_NonCallableMock__set_side_effect',
|
|
'__call__',
|
|
'__class__',
|
|
...
|
|
|
|
Alternatively you can just use `vars(my_mock)` (instance members) and
|
|
`dir(type(my_mock))` (type members) to bypass the filtering irrespective of
|
|
`mock.FILTER_DIR`.
|
|
|
|
|
|
mock_open
|
|
=========
|
|
|
|
.. function:: mock_open(mock=None, read_data=None)
|
|
|
|
A helper function to create a mock to replace the use of `open`. It works
|
|
for `open` called directly or used as a context manager.
|
|
|
|
The `mock` argument is the mock object to configure. If `None` (the
|
|
default) then a `MagicMock` will be created for you, with the API limited
|
|
to methods or attributes available on standard file handles.
|
|
|
|
`read_data` is a string for the `read` method of the file handle to return.
|
|
This is an empty string by default.
|
|
|
|
Using `open` as a context manager is a great way to ensure your file handles
|
|
are closed properly and is becoming common::
|
|
|
|
with open('/some/path', 'w') as f:
|
|
f.write('something')
|
|
|
|
The issue is that even if you mock out the call to `open` it is the
|
|
*returned object* that is used as a context manager (and has `__enter__` and
|
|
`__exit__` called).
|
|
|
|
Mocking context managers with a :class:`MagicMock` is common enough and fiddly
|
|
enough that a helper function is useful.
|
|
|
|
.. doctest::
|
|
|
|
>>> from mock import mock_open
|
|
>>> m = mock_open()
|
|
>>> with patch('__main__.open', m, create=True):
|
|
... with open('foo', 'w') as h:
|
|
... h.write('some stuff')
|
|
...
|
|
>>> m.mock_calls
|
|
[call('foo', 'w'),
|
|
call().__enter__(),
|
|
call().write('some stuff'),
|
|
call().__exit__(None, None, None)]
|
|
>>> m.assert_called_once_with('foo', 'w')
|
|
>>> handle = m()
|
|
>>> handle.write.assert_called_once_with('some stuff')
|
|
|
|
And for reading files:
|
|
|
|
.. doctest::
|
|
|
|
>>> with patch('__main__.open', mock_open(read_data='bibble'), create=True) as m:
|
|
... with open('foo') as h:
|
|
... result = h.read()
|
|
...
|
|
>>> m.assert_called_once_with('foo')
|
|
>>> assert result == 'bibble'
|
|
|
|
|
|
.. _auto-speccing:
|
|
|
|
Autospeccing
|
|
============
|
|
|
|
Autospeccing is based on the existing `spec` feature of mock. It limits the
|
|
api of mocks to the api of an original object (the spec), but it is recursive
|
|
(implemented lazily) so that attributes of mocks only have the same api as
|
|
the attributes of the spec. In addition mocked functions / methods have the
|
|
same call signature as the original so they raise a `TypeError` if they are
|
|
called incorrectly.
|
|
|
|
Before I explain how auto-speccing works, here's why it is needed.
|
|
|
|
`Mock` is a very powerful and flexible object, but it suffers from two flaws
|
|
when used to mock out objects from a system under test. One of these flaws is
|
|
specific to the `Mock` api and the other is a more general problem with using
|
|
mock objects.
|
|
|
|
First the problem specific to `Mock`. `Mock` has two assert methods that are
|
|
extremely handy: :meth:`~Mock.assert_called_with` and
|
|
:meth:`~Mock.assert_called_once_with`.
|
|
|
|
.. doctest::
|
|
|
|
>>> mock = Mock(name='Thing', return_value=None)
|
|
>>> mock(1, 2, 3)
|
|
>>> mock.assert_called_once_with(1, 2, 3)
|
|
>>> mock(1, 2, 3)
|
|
>>> mock.assert_called_once_with(1, 2, 3)
|
|
Traceback (most recent call last):
|
|
...
|
|
AssertionError: Expected to be called once. Called 2 times.
|
|
|
|
Because mocks auto-create attributes on demand, and allow you to call them
|
|
with arbitrary arguments, if you misspell one of these assert methods then
|
|
your assertion is gone:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> mock = Mock(name='Thing', return_value=None)
|
|
>>> mock(1, 2, 3)
|
|
>>> mock.assret_called_once_with(4, 5, 6)
|
|
|
|
Your tests can pass silently and incorrectly because of the typo.
|
|
|
|
The second issue is more general to mocking. If you refactor some of your
|
|
code, rename members and so on, any tests for code that is still using the
|
|
*old api* but uses mocks instead of the real objects will still pass. This
|
|
means your tests can all pass even though your code is broken.
|
|
|
|
Note that this is another reason why you need integration tests as well as
|
|
unit tests. Testing everything in isolation is all fine and dandy, but if you
|
|
don't test how your units are "wired together" there is still lots of room
|
|
for bugs that tests might have caught.
|
|
|
|
`mock` already provides a feature to help with this, called speccing. If you
|
|
use a class or instance as the `spec` for a mock then you can only access
|
|
attributes on the mock that exist on the real class:
|
|
|
|
.. doctest::
|
|
|
|
>>> import urllib2
|
|
>>> mock = Mock(spec=urllib2.Request)
|
|
>>> mock.assret_called_with
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: Mock object has no attribute 'assret_called_with'
|
|
|
|
The spec only applies to the mock itself, so we still have the same issue
|
|
with any methods on the mock:
|
|
|
|
.. code-block:: pycon
|
|
|
|
>>> mock.has_data()
|
|
<mock.Mock object at 0x...>
|
|
>>> mock.has_data.assret_called_with()
|
|
|
|
Auto-speccing solves this problem. You can either pass `autospec=True` to
|
|
`patch` / `patch.object` or use the `create_autospec` function to create a
|
|
mock with a spec. If you use the `autospec=True` argument to `patch` then the
|
|
object that is being replaced will be used as the spec object. Because the
|
|
speccing is done "lazily" (the spec is created as attributes on the mock are
|
|
accessed) you can use it with very complex or deeply nested objects (like
|
|
modules that import modules that import modules) without a big performance
|
|
hit.
|
|
|
|
Here's an example of it in use:
|
|
|
|
.. doctest::
|
|
|
|
>>> import urllib2
|
|
>>> patcher = patch('__main__.urllib2', autospec=True)
|
|
>>> mock_urllib2 = patcher.start()
|
|
>>> urllib2 is mock_urllib2
|
|
True
|
|
>>> urllib2.Request
|
|
<MagicMock name='urllib2.Request' spec='Request' id='...'>
|
|
|
|
You can see that `urllib2.Request` has a spec. `urllib2.Request` takes two
|
|
arguments in the constructor (one of which is `self`). Here's what happens if
|
|
we try to call it incorrectly:
|
|
|
|
.. doctest::
|
|
|
|
>>> req = urllib2.Request()
|
|
Traceback (most recent call last):
|
|
...
|
|
TypeError: <lambda>() takes at least 2 arguments (1 given)
|
|
|
|
The spec also applies to instantiated classes (i.e. the return value of
|
|
specced mocks):
|
|
|
|
.. doctest::
|
|
|
|
>>> req = urllib2.Request('foo')
|
|
>>> req
|
|
<NonCallableMagicMock name='urllib2.Request()' spec='Request' id='...'>
|
|
|
|
`Request` objects are not callable, so the return value of instantiating our
|
|
mocked out `urllib2.Request` is a non-callable mock. With the spec in place
|
|
any typos in our asserts will raise the correct error:
|
|
|
|
.. doctest::
|
|
|
|
>>> req.add_header('spam', 'eggs')
|
|
<MagicMock name='urllib2.Request().add_header()' id='...'>
|
|
>>> req.add_header.assret_called_with
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: Mock object has no attribute 'assret_called_with'
|
|
>>> req.add_header.assert_called_with('spam', 'eggs')
|
|
|
|
In many cases you will just be able to add `autospec=True` to your existing
|
|
`patch` calls and then be protected against bugs due to typos and api
|
|
changes.
|
|
|
|
As well as using `autospec` through `patch` there is a
|
|
:func:`create_autospec` for creating autospecced mocks directly:
|
|
|
|
.. doctest::
|
|
|
|
>>> import urllib2
|
|
>>> mock_urllib2 = create_autospec(urllib2)
|
|
>>> mock_urllib2.Request('foo', 'bar')
|
|
<NonCallableMagicMock name='mock.Request()' spec='Request' id='...'>
|
|
|
|
This isn't without caveats and limitations however, which is why it is not
|
|
the default behaviour. In order to know what attributes are available on the
|
|
spec object, autospec has to introspect (access attributes) the spec. As you
|
|
traverse attributes on the mock a corresponding traversal of the original
|
|
object is happening under the hood. If any of your specced objects have
|
|
properties or descriptors that can trigger code execution then you may not be
|
|
able to use autospec. On the other hand it is much better to design your
|
|
objects so that introspection is safe [#]_.
|
|
|
|
A more serious problem is that it is common for instance attributes to be
|
|
created in the `__init__` method and not to exist on the class at all.
|
|
`autospec` can't know about any dynamically created attributes and restricts
|
|
the api to visible attributes.
|
|
|
|
.. doctest::
|
|
|
|
>>> class Something(object):
|
|
... def __init__(self):
|
|
... self.a = 33
|
|
...
|
|
>>> with patch('__main__.Something', autospec=True):
|
|
... thing = Something()
|
|
... thing.a
|
|
...
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: Mock object has no attribute 'a'
|
|
|
|
There are a few different ways of resolving this problem. The easiest, but
|
|
not necessarily the least annoying, way is to simply set the required
|
|
attributes on the mock after creation. Just because `autospec` doesn't allow
|
|
you to fetch attributes that don't exist on the spec it doesn't prevent you
|
|
setting them:
|
|
|
|
.. doctest::
|
|
|
|
>>> with patch('__main__.Something', autospec=True):
|
|
... thing = Something()
|
|
... thing.a = 33
|
|
...
|
|
|
|
There is a more aggressive version of both `spec` and `autospec` that *does*
|
|
prevent you setting non-existent attributes. This is useful if you want to
|
|
ensure your code only *sets* valid attributes too, but obviously it prevents
|
|
this particular scenario:
|
|
|
|
.. doctest::
|
|
|
|
>>> with patch('__main__.Something', autospec=True, spec_set=True):
|
|
... thing = Something()
|
|
... thing.a = 33
|
|
...
|
|
Traceback (most recent call last):
|
|
...
|
|
AttributeError: Mock object has no attribute 'a'
|
|
|
|
Probably the best way of solving the problem is to add class attributes as
|
|
default values for instance members initialised in `__init__`. Note that if
|
|
you are only setting default attributes in `__init__` then providing them via
|
|
class attributes (shared between instances of course) is faster too. e.g.
|
|
|
|
.. code-block:: python
|
|
|
|
class Something(object):
|
|
a = 33
|
|
|
|
This brings up another issue. It is relatively common to provide a default
|
|
value of `None` for members that will later be an object of a different type.
|
|
`None` would be useless as a spec because it wouldn't let you access *any*
|
|
attributes or methods on it. As `None` is *never* going to be useful as a
|
|
spec, and probably indicates a member that will normally of some other type,
|
|
`autospec` doesn't use a spec for members that are set to `None`. These will
|
|
just be ordinary mocks (well - `MagicMocks`):
|
|
|
|
.. doctest::
|
|
|
|
>>> class Something(object):
|
|
... member = None
|
|
...
|
|
>>> mock = create_autospec(Something)
|
|
>>> mock.member.foo.bar.baz()
|
|
<MagicMock name='mock.member.foo.bar.baz()' id='...'>
|
|
|
|
If modifying your production classes to add defaults isn't to your liking
|
|
then there are more options. One of these is simply to use an instance as the
|
|
spec rather than the class. The other is to create a subclass of the
|
|
production class and add the defaults to the subclass without affecting the
|
|
production class. Both of these require you to use an alternative object as
|
|
the spec. Thankfully `patch` supports this - you can simply pass the
|
|
alternative object as the `autospec` argument:
|
|
|
|
.. doctest::
|
|
|
|
>>> class Something(object):
|
|
... def __init__(self):
|
|
... self.a = 33
|
|
...
|
|
>>> class SomethingForTest(Something):
|
|
... a = 33
|
|
...
|
|
>>> p = patch('__main__.Something', autospec=SomethingForTest)
|
|
>>> mock = p.start()
|
|
>>> mock.a
|
|
<NonCallableMagicMock name='Something.a' spec='int' id='...'>
|
|
|
|
.. note::
|
|
|
|
An additional limitation (currently) with `autospec` is that unbound
|
|
methods on mocked classes *don't* take an "explicit self" as the first
|
|
argument - so this usage will fail with `autospec`.
|
|
|
|
.. doctest::
|
|
|
|
>>> class Foo(object):
|
|
... def foo(self):
|
|
... pass
|
|
...
|
|
>>> Foo.foo(Foo())
|
|
>>> MockFoo = create_autospec(Foo)
|
|
>>> MockFoo.foo(MockFoo())
|
|
Traceback (most recent call last):
|
|
...
|
|
TypeError: <lambda>() takes exactly 1 argument (2 given)
|
|
|
|
The reason is that its very hard to tell the difference between functions,
|
|
unbound methods and staticmethods across Python 2 & 3 and the alternative
|
|
implementations. This restriction may be fixed in future versions.
|
|
|
|
|
|
------
|
|
|
|
.. [#] This only applies to classes or already instantiated objects. Calling
|
|
a mocked class to create a mock instance *does not* create a real instance.
|
|
It is only attribute lookups - along with calls to `dir` - that are done. A
|
|
way round this problem would have been to use `getattr_static
|
|
<http://docs.python.org/dev/library/inspect.html#inspect.getattr_static>`_,
|
|
which can fetch attributes without triggering code execution. Descriptors
|
|
like `classmethod` and `staticmethod` *need* to be fetched correctly though,
|
|
so that their signatures can be mocked correctly.
|