What does calling a unittest.mock.AsyncMock return, and how does that differ from Mock?

`unittest.mock.AsyncMock` is the test double for a **coroutine function** — something defined with `async def`. It exists because a plain `Mock` gets the shape of an async call wrong in a way that either explodes or, worse, passes quietly. ### What a call does, and what an await does Two separate events happen when production code runs `result = await double(item_id)`. 1. **The call.** `double(item_id)` invokes the mock. `AsyncMock.__call__` records the call in `call_count`/`call_args_list` exactly as `Mock` does, and then returns a **coroutine object**. Nothing you configured has been produced yet; no `side_effect` has run. 2. **The await.** Awaiting that coroutine object is what makes the mock produce a value. It records the await in `await_count`/`await_args`/`await_args_list`, applies `side_effect` if one is set, and otherwise returns `return_value`. The practical consequence is that `return_value` is a **plain value**, not something you have to wrap. `AsyncMock(return_value={"id": 7})` makes `await double()` produce `{"id": 7}`. Candidates who learned mocking on Python 3.7 often still wrap results in a future or hand-roll a coroutine function; on 3.8 and later that is not only unnecessary, it is wrong — the await then yields the future object rather than the value inside it. Reach for a real awaitable only when the code under test treats the returned object as a future in its own right, for instance by cancelling it or attaching a done callback. `side_effect` on an `AsyncMock` accepts the same shapes as on `Mock` — an exception instance or class, an iterable of results, a callable — plus one extra: an **async** callable, which the mock awaits and whose result it returns. That is the clean way to compute a per-call answer or to raise only for particular arguments. ### The two ways to get it wrong **Forgetting the await in production code.** If the code under test calls the double but never awaits it, the coroutine object is created, dropped and eventually garbage-collected, and CPython emits `RuntimeWarning: coroutine 'AsyncMockMixin._execute_mock_call' was never awaited`. That warning is easy to lose in a noisy test log, so it is worth turning warnings into errors in CI, and better still to assert on the mock's `await_count` rather than trusting a warning to surface. This is the single most valuable thing `AsyncMock` gives you: real code that forgets an `await` produces a double that was *called* but never *awaited*, and only an await assertion notices. **Using a synchronous double where a coroutine function is expected.** Awaiting a `Mock` or `MagicMock` raises `TypeError`. On Python 3.14 the message reads `'MagicMock' object can't be awaited`; through 3.13 the same condition read `object MagicMock can't be used in 'await' expression`, so never assert on that string in a test. This failure is loud, which makes it the friendly one — the dangerous case is the reverse, where an async double stands in for something the code never awaits. ### How AsyncMock relates to the rest of the family `AsyncMock` subclasses `MagicMock`, so it inherits the pre-configured magic methods and adds the asynchronous ones: `__aenter__`, `__aexit__` and `__anext__` on any `MagicMock` or `AsyncMock` are themselves `AsyncMock` instances, which is why an `async with` over a `MagicMock` works out of the box. The double also advertises itself convincingly: `inspect.iscoroutinefunction(AsyncMock())` returns `True`, so production code that branches on that check still takes its async path. Conversely, not every async-looking thing needs an `AsyncMock`. A **synchronous** function that returns an awaitable — a factory that hands back a task or a coroutine — is not a coroutine function. Its double should be a `MagicMock` whose `return_value` is awaitable. Matching the double to the real object's shape, rather than to the presence of the word "async" nearby, is the whole skill. ### Reading a failure Three symptoms map cleanly back to this model, and recognising them saves a long hunt. `TypeError: 'MagicMock' object can't be awaited` means a synchronous double sits where a coroutine function belongs. `RuntimeWarning: coroutine ... was never awaited` means an async double was called by code that did not await it — either a real bug in the code under test, or a double that should have been synchronous. And an assertion that reports a mock was never awaited, while the call assertion for the same arguments passes, means the coroutine was created and dropped somewhere in between. ### What AsyncMock does not give you It is a double, not a scheduler. Constructing one needs no running event loop, and it introduces no concurrency of its own: the await resolves immediately, in order, with no suspension point that another task can slip through. That is usually what you want in a unit test, but it means an `AsyncMock` cannot reproduce interleaving bugs — a double that always completes instantly will never show you the window in which two tasks race. Timing-shaped behaviour has to be modelled explicitly, for instance with an async `side_effect` that awaits before returning. ### Version notes `AsyncMock`, the await assertions, and automatic async magic-method support all arrived in Python 3.8. Nothing about that core behaviour changed through 3.14; only the wording of the `TypeError` raised when a non-async mock is awaited was rewritten in 3.14.