bpo-26467: Adds AsyncMock for asyncio Mock library support (GH-9296)
diff --git a/Doc/library/unittest.mock.rst b/Doc/library/unittest.mock.rst
index ed00ee6..21e4709 100644
--- a/Doc/library/unittest.mock.rst
+++ b/Doc/library/unittest.mock.rst
@@ -201,9 +201,11 @@
.. testsetup::
+ import asyncio
+ import inspect
import unittest
from unittest.mock import sentinel, DEFAULT, ANY
- from unittest.mock import patch, call, Mock, MagicMock, PropertyMock
+ from unittest.mock import patch, call, Mock, MagicMock, PropertyMock, AsyncMock
from unittest.mock import mock_open
:class:`Mock` is a flexible mock object intended to replace the use of stubs and
@@ -851,6 +853,217 @@
>>> p.assert_called_once_with()
+.. class:: AsyncMock(spec=None, side_effect=None, return_value=DEFAULT, wraps=None, name=None, spec_set=None, unsafe=False, **kwargs)
+
+ An asynchronous version of :class:`Mock`. The :class:`AsyncMock` object will
+ behave so the object is recognized as an async function, and the result of a
+ call is an awaitable.
+
+ >>> mock = AsyncMock()
+ >>> asyncio.iscoroutinefunction(mock)
+ True
+ >>> inspect.isawaitable(mock())
+ True
+
+ The result of ``mock()`` is an async function which will have the outcome
+ of ``side_effect`` or ``return_value``:
+
+ - if ``side_effect`` is a function, the async function will return the
+ result of that function,
+ - if ``side_effect`` is an exception, the async function will raise the
+ exception,
+ - if ``side_effect`` is an iterable, the async function 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 async function will return the
+ value defined by ``return_value``, hence, by default, the async function
+ returns a new :class:`AsyncMock` object.
+
+
+ Setting the *spec* of a :class:`Mock` or :class:`MagicMock` to an async function
+ will result in a coroutine object being returned after calling.
+
+ >>> async def async_func(): pass
+ ...
+ >>> mock = MagicMock(async_func)
+ >>> mock
+ <MagicMock spec='function' id='...'>
+ >>> mock()
+ <coroutine object AsyncMockMixin._mock_call at ...>
+
+ .. method:: assert_awaited()
+
+ Assert that the mock was awaited at least once.
+
+ >>> mock = AsyncMock()
+ >>> async def main():
+ ... await mock()
+ ...
+ >>> asyncio.run(main())
+ >>> mock.assert_awaited()
+ >>> mock_2 = AsyncMock()
+ >>> mock_2.assert_awaited()
+ Traceback (most recent call last):
+ ...
+ AssertionError: Expected mock to have been awaited.
+
+ .. method:: assert_awaited_once()
+
+ Assert that the mock was awaited exactly once.
+
+ >>> mock = AsyncMock()
+ >>> async def main():
+ ... await mock()
+ ...
+ >>> asyncio.run(main())
+ >>> mock.assert_awaited_once()
+ >>> asyncio.run(main())
+ >>> mock.method.assert_awaited_once()
+ Traceback (most recent call last):
+ ...
+ AssertionError: Expected mock to have been awaited once. Awaited 2 times.
+
+ .. method:: assert_awaited_with(*args, **kwargs)
+
+ Assert that the last await was with the specified arguments.
+
+ >>> mock = AsyncMock()
+ >>> async def main(*args, **kwargs):
+ ... await mock(*args, **kwargs)
+ ...
+ >>> asyncio.run(main('foo', bar='bar'))
+ >>> mock.assert_awaited_with('foo', bar='bar')
+ >>> mock.assert_awaited_with('other')
+ Traceback (most recent call last):
+ ...
+ AssertionError: expected call not found.
+ Expected: mock('other')
+ Actual: mock('foo', bar='bar')
+
+ .. method:: assert_awaited_once_with(*args, **kwargs)
+
+ Assert that the mock was awaited exactly once and with the specified
+ arguments.
+
+ >>> mock = AsyncMock()
+ >>> async def main(*args, **kwargs):
+ ... await mock(*args, **kwargs)
+ ...
+ >>> asyncio.run(main('foo', bar='bar'))
+ >>> mock.assert_awaited_once_with('foo', bar='bar')
+ >>> asyncio.run(main('foo', bar='bar'))
+ >>> mock.assert_awaited_once_with('foo', bar='bar')
+ Traceback (most recent call last):
+ ...
+ AssertionError: Expected mock to have been awaited once. Awaited 2 times.
+
+ .. method:: assert_any_await(*args, **kwargs)
+
+ Assert the mock has ever been awaited with the specified arguments.
+
+ >>> mock = AsyncMock()
+ >>> async def main(*args, **kwargs):
+ ... await mock(*args, **kwargs)
+ ...
+ >>> asyncio.run(main('foo', bar='bar'))
+ >>> asyncio.run(main('hello'))
+ >>> mock.assert_any_await('foo', bar='bar')
+ >>> mock.assert_any_await('other')
+ Traceback (most recent call last):
+ ...
+ AssertionError: mock('other') await not found
+
+ .. method:: assert_has_awaits(calls, any_order=False)
+
+ Assert the mock has been awaited with the specified calls.
+ The :attr:`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 :attr:`await_args_list`.
+
+ >>> mock = AsyncMock()
+ >>> async def main(*args, **kwargs):
+ ... await mock(*args, **kwargs)
+ ...
+ >>> calls = [call("foo"), call("bar")]
+ >>> mock.assert_has_calls(calls)
+ Traceback (most recent call last):
+ ...
+ AssertionError: Calls not found.
+ Expected: [call('foo'), call('bar')]
+ >>> asyncio.run(main('foo'))
+ >>> asyncio.run(main('bar'))
+ >>> mock.assert_has_calls(calls)
+
+ .. method:: assert_not_awaited()
+
+ Assert that the mock was never awaited.
+
+ >>> mock = AsyncMock()
+ >>> mock.assert_not_awaited()
+
+ .. method:: reset_mock(*args, **kwargs)
+
+ See :func:`Mock.reset_mock`. Also sets :attr:`await_count` to 0,
+ :attr:`await_args` to None, and clears the :attr:`await_args_list`.
+
+ .. attribute:: await_count
+
+ An integer keeping track of how many times the mock object has been awaited.
+
+ >>> mock = AsyncMock()
+ >>> async def main():
+ ... await mock()
+ ...
+ >>> asyncio.run(main())
+ >>> mock.await_count
+ 1
+ >>> asyncio.run(main())
+ >>> mock.await_count
+ 2
+
+ .. attribute:: await_args
+
+ This is either ``None`` (if the mock hasn’t been awaited), or the arguments that
+ the mock was last awaited with. Functions the same as :attr:`Mock.call_args`.
+
+ >>> mock = AsyncMock()
+ >>> async def main(*args):
+ ... await mock(*args)
+ ...
+ >>> mock.await_args
+ >>> asyncio.run(main('foo'))
+ >>> mock.await_args
+ call('foo')
+ >>> asyncio.run(main('bar'))
+ >>> mock.await_args
+ call('bar')
+
+
+ .. attribute:: await_args_list
+
+ This is a list of all the awaits made to the mock object in sequence (so the
+ length of the list is the number of times it has been awaited). Before any
+ awaits have been made it is an empty list.
+
+ >>> mock = AsyncMock()
+ >>> async def main(*args):
+ ... await mock(*args)
+ ...
+ >>> mock.await_args_list
+ []
+ >>> asyncio.run(main('foo'))
+ >>> mock.await_args_list
+ [call('foo')]
+ >>> asyncio.run(main('bar'))
+ >>> mock.await_args_list
+ [call('foo'), call('bar')]
+
+
Calling
~~~~~~~