# Module `mock`

Wrapper to unittest.mock reducing the boilerplate when testing asyncio powered code.

A mock can behave as a coroutine, as specified in the documentation of `Mock`.

## Mock classes

class `asynctest.``Mock`(spec=None, side_effect=None, return_value=sentinel.DEFAULT, wraps=None, name=None, spec_set=None, parent=None, _spec_state=None, _new_name='', _new_parent=None, **kwargs)

  Enhance `unittest.mock.Mock` so it returns a `CoroutineMock` object instead of a `Mock` object where a method on a `spec` or `spec_set` object is a coroutine.

  For instance:

      >>> class Foo:
      ...     @asyncio.coroutine
      ...     def foo(self):
      ...         pass
      ...
      ...     def bar(self):
      ...         pass

      >>> type(asynctest.mock.Mock(Foo()).foo)
      <class 'asynctest.mock.CoroutineMock'>

      >>> type(asynctest.mock.Mock(Foo()).bar)
      <class 'asynctest.mock.Mock'>

  The test author can also specify a wrapped object with `wraps`. In this case, the `Mock` object behavior is the same as with an `unittest.mock.Mock` object: the wrapped object may have methods defined as coroutine functions.

  If you want to mock a coroutine function, use `CoroutineMock` instead.

  See `NonCallableMock` for details about `asynctest` features, and `unittest.mock` for the comprehensive documentation about mocking.

class `asynctest.``NonCallableMock`(spec=None, wraps=None, name=None, spec_set=None, is_coroutine=None, parent=None, **kwargs)

  Enhance `unittest.mock.NonCallableMock` with features allowing to mock a coroutine function.

  If `is_coroutine` is set to `True`, the `NonCallableMock` object will behave so `asyncio.iscoroutinefunction()` will return `True` with `mock` as parameter.

  If `spec` or `spec_set` is defined and an attribute is get, `CoroutineMock` is returned instead of `Mock` when the matching spec attribute is a coroutine function.

  The test author can also specify a wrapped object with `wraps`. In this case, the `Mock` object behavior is the same as with an `unittest.mock.Mock` object: the wrapped object may have methods defined as coroutine functions.

  See `unittest.mock.NonCallableMock`

  `is_coroutine`

    True if the object mocked is a coroutine

class `asynctest.``MagicMock`(*args, **kwargs)

  Enhance `unittest.mock.MagicMock` so it returns a `CoroutineMock` object instead of a `Mock` object where a method on a `spec` or `spec_set` object is a coroutine.

  If you want to mock a coroutine function, use `CoroutineMock` instead.

  `MagicMock` allows to mock `__aenter__`, `__aexit__`, `__aiter__` and `__anext__`.

  When mocking an asynchronous iterator, you can set the `return_value` of `__aiter__` to an iterable to define the list of values to be returned during iteration.

  You can not mock `__await__`. If you want to mock an object implementing __await__, `CoroutineMock` will likely be sufficient.

  see `Mock`.

  New in version 0.11: support of asynchronous iterators and asynchronous context managers.

class `asynctest.``CoroutineMock`(*args, **kwargs)

  Enhance `Mock` with features allowing to mock a coroutine function.

  The `CoroutineMock` object will behave so the object is recognized as coroutine function, and the result of a call as a coroutine:

      >>> mock = CoroutineMock()
      >>> asyncio.iscoroutinefunction(mock)
      True
      >>> asyncio.iscoroutine(mock())
      True

  The result of `mock()` is a coroutine which will have the outcome of `side_effect` or `return_value`:

  - if `side_effect` is a function, the coroutine will return the result of that function,
  - if `side_effect` is an exception, the coroutine will raise the exception,
  - if `side_effect` is an iterable, the coroutine will return the next value of the iterable, however, if the sequence of result is exhausted, `StopIteration` is raised immediately,
  - if `side_effect` is not defined, the coroutine will return the value defined by `return_value`, hence, by default, the coroutine returns a new `CoroutineMock` object.

  If the outcome of `side_effect` or `return_value` is a coroutine, the mock coroutine obtained when the mock object is called will be this coroutine itself (and not a coroutine returning a coroutine).

  The test author can also specify a wrapped object with `wraps`. In this case, the `Mock` object behavior is the same as with an `unittest.mock.Mock` object: the wrapped object may have methods defined as coroutine functions.

  `assert_any_await`(*args, **kwargs)

    Assert the mock has ever been awaited with the specified arguments.

    New in version 0.12.

  `assert_awaited`()

    Assert that the mock was awaited at least once.

    New in version 0.12.

  `assert_awaited_once`(*args, **kwargs)

    Assert that the mock was awaited exactly once.

    New in version 0.12.

  `assert_awaited_once_with`(*args, **kwargs)

    Assert that the mock was awaited exactly once and with the specified arguments.

    New in version 0.12.

  `assert_awaited_with`(*args, **kwargs)

    Assert that the last await was with the specified arguments.

    New in version 0.12.

  `assert_has_awaits`(calls, any_order=False)

    Assert the mock has been awaited with the specified calls. The `await_args_list` list is checked for the awaits.

    If any_order is False (the default) then the awaits must be sequential. There can be extra calls before or after the specified awaits.

    If any_order is True then the awaits can be in any order, but they must all appear in `await_args_list`.

    New in version 0.12.

  `assert_not_awaited`()

    Assert that the mock was never awaited.

    New in version 0.12.

  `await_args`
  `await_args_list`
  `await_count`

    Number of times the mock has been awaited.

    New in version 0.12.

  `awaited`

    Property which is set when the mock is awaited. Its `wait` and `wait_next` coroutine methods can be used to synchronize execution.

    New in version 0.12.

  `reset_mock`(*args, **kwargs)

    See `unittest.mock.Mock.reset_mock()`

## Autospeccing

`asynctest.``create_autospec`(spec, spec_set=False, instance=False, _parent=None, _name=None, **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.

  `spec` can be a coroutine function, a class or object with coroutine functions as attributes.

  If `spec` is a coroutine function, and `instance` is not `False`, a `RuntimeError` is raised.

  New in version 0.12.

## Patch

`asynctest.``GLOBAL`

  Value of `scope`, activating a patch until the decorated generator or coroutine returns or raises an exception.

`asynctest.``LIMITED`

  Value of `scope`, deactivating a patch when a decorated generator or a coroutine pauses (`yield` or `await`).

`asynctest.``patch`(target, new=sentinel.DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, scope=<PatchScope.GLOBAL: 2>, **kwargs)

  A context manager, function decorator or class decorator which patches the target with the value given by the `new` argument.

  `new` specifies which object will replace the `target` when the patch is applied. By default, the target will be patched with an instance of `CoroutineMock` if it is a coroutine, or a `MagicMock` object.

  It is a replacement to `unittest.mock.patch()`, but using `asynctest.mock` objects.

  When a generator or a coroutine is patched using the decorator, the patch is activated or deactivated according to the `scope` argument value:

  > - `asynctest.GLOBAL`: the default, enables the patch until the generator or the coroutine finishes (returns or raises an exception),
  > - `asynctest.LIMITED`: the patch will be activated when the generator or coroutine is being executed, and deactivated when it yields a value and pauses its execution (with `yield`, `yield from` or `await`).

  The behavior differs from `unittest.mock.patch()` for generators.

  When used as a context manager, the patch is still active even if the generator or coroutine is paused, which may affect concurrent tasks:

      @asyncio.coroutine
      def coro():
          with asynctest.mock.patch("module.function"):
              yield from asyncio.get_event_loop().sleep(1)

      @asyncio.coroutine
      def independent_coro():
          assert not isinstance(module.function, asynctest.mock.Mock)

      asyncio.create_task(coro())
      asyncio.create_task(independent_coro())
      # this will raise an AssertionError(coro() is scheduled first)!
      loop.run_forever()

  Parameters: | scope – `asynctest.GLOBAL` or `asynctest.LIMITED`, controls when the patch is activated on generators and coroutines

  When used as a decorator with a generator based coroutine, the order of the decorators matters. The order of the `@patch()` decorators is in the reverse order of the parameters produced by these patches for the patched function. And the `@asyncio.coroutine` decorator should be the last since `@patch()` conceptually patches the coroutine, not the function:

      @patch("module.function2")
      @patch("module.function1")
      @asyncio.coroutine
      def test_coro(self, mock_function1, mock_function2):
          yield from asyncio.get_event_loop().sleep(1)

  see `unittest.mock.patch()`.

  New in version 0.6: patch into generators and coroutines with a decorator.

`asynctest.patch.``object`(target, attribute, new=DEFAULT, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, scope=asynctest.GLOBAL, **kwargs)

  Patch the named member (`attribute`) on an object (`target`) with a mock object, in the same fashion as `patch()`.

  See `patch()` and `unittest.mock.patch.object()`.

`asynctest.patch.``multiple`(target, spec=None, create=False, spec_set=None, autospec=None, new_callable=None, scope=asynctest.global, **kwargs)

  Perform multiple patches in a single call. It takes the object to be patched (either as an object or a string to fetch the object by importing) and keyword arguments for the patches.

  See `patch()` and `unittest.mock.patch.multiple()`.

`asynctest.patch.``dict`(in_dict, values=(), clear=False, scope=asynctest.GLOBAL, **kwargs)

  Patch a dictionary, or dictionary like object, and restore the dictionary to its original state after the test.

  Its behavior can be controlled on decorated generators and coroutines with `scope`.

  New in version 0.8: patch into generators and coroutines with a decorator.

  Parameters:

  - in_dict – dictionary like object, or string referencing the object to patch.
  - values – a dictionary of values or an iterable of (key, value) pairs to set in the dictionary.
  - clear – if `True`, in_dict will be cleared before the new values are set.
  - scope – `asynctest.GLOBAL` or `asynctest.LIMITED`, controls when the patch is activated on generators and coroutines

  See: | `patch()` (details about `scope`) and `unittest.mock.patch.dict()`.

## Helpers

`asynctest.``mock_open`(mock=None, read_data='')

  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.

  Parameters:

  - mock – mock object to configure, by default a `MagicMock` object is created with the API limited to methods or attributes available on standard file handles.
  - read_data – string for the `read()` and `readlines()` of the file handle to return. This is an empty string by default.

`asynctest.``return_once`(value, then=None)

  Helper to use with `side_effect`, so a mock will return a given value only once, then return another value.

  When used as a `side_effect` value, if one of `value` or `then` is an `Exception` type, an instance of this exception will be raised.

      >>> mock.recv = Mock(side_effect=return_once(b"data"))
      >>> mock.recv()
      b"data"
      >>> repr(mock.recv())
      'None'
      >>> repr(mock.recv())
      'None'

      >>> mock.recv = Mock(side_effect=return_once(b"data", then=BlockingIOError))
      >>> mock.recv()
      b"data"
      >>> mock.recv()
      Traceback BlockingIOError

  Parameters:

  - value – value to be returned once by the mock when called.
  - then – value returned for any subsequent call.

  New in version 0.4.