The Tor Browser / file revision

 =========

  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.