| ========= |
| 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. |
