With unittest.mock, how do you double an `async with` resource and assert it was exited?

`async with` requires an object with `__aenter__` and `__aexit__` that are **awaitable**. Doubling one is mostly a matter of matching the real object's shape, and then asserting on the exit — which is the assertion teams forget, and the reason a resource leak survives a green suite. ### What the mock library gives you for free Both `MagicMock` and `AsyncMock` pre-configure the async magic methods: on any such double, `__aenter__`, `__aexit__` and `__anext__` are themselves `AsyncMock` instances (Python 3.8 and later). So `async with MagicMock() as thing:` works with no setup at all, `__aenter__` returns a fresh child mock, and `__aexit__` returns `False`, meaning an exception raised inside the block propagates rather than being swallowed. Two knobs cover almost every test: * `manager.__aenter__.return_value = <the fake resource>` decides what the `as` name is bound to. Without it you get an auto-created child, which is fine when the block only passes it around and wrong when the block awaits methods on it — a child of a `MagicMock` is a `MagicMock`, so make the entered resource an `AsyncMock` if the code awaits its methods. * `manager.__aexit__.return_value = True` makes the double swallow exceptions. Set it only when the real manager does, because a stray `True` turns a failing test green. ### Match the shape of the acquisition, not the word "async" The trap that costs the most time: is the factory synchronous or asynchronous? * `async with pool.acquire() as session:` — `acquire` is a **synchronous** call returning an async context manager. Double `pool` with a `MagicMock` and configure `pool.acquire.return_value.__aenter__.return_value`. * `async with await pool.acquire() as session:` — `acquire` is a coroutine function, so an `AsyncMock` is right, and the manager is its `return_value`. Get it backwards and the failure is a very specific `TypeError`: `'coroutine' object does not support the asynchronous context manager protocol`, because `AsyncMock.acquire()` handed `async with` a coroutine rather than a manager. When the real object comes from a library, the fastest way to be sure is to check whether the production call site awaits the factory. ### Asserting the exit Consider a catalogue importer that opens a session, writes records and is expected to release the session whatever happens. An 11-person team is losing connections in production and cannot see why: the unit test asserts the writes, so it never notices that a validation error on one record escapes before the session is released. Two assertions close that hole permanently: * `manager.__aexit__.assert_awaited_once()` — the block was exited, exactly once. Note it must be *awaited*, not merely called; `assert_called_once` on `__aexit__` would pass even for a coroutine that was dropped. * `manager.__aexit__.await_args[0][0]` — the exception **class** passed to the exit, or `None` for a clean exit. Asserting it is `ValueError` proves the importer left the block on the error path and still released the resource; asserting it is `None` proves the happy path. This is a genuinely stronger claim than "the resource was closed" written as an assertion on a `close()` double, because it verifies the language-level protocol the real object relies on. Where the manager is produced by an `@asynccontextmanager`-decorated generator in production code, prefer patching the factory that returns it, since the decorated object's protocol methods live on the helper object rather than on the generator function. ### Failure modes worth naming * Asserting only `__aenter__` — proves the resource was opened, which is the half that was never in doubt. * Reusing one double for several `async with` blocks: `pool.acquire.return_value` is the *same* manager every time, so `await_count` accumulates across blocks. Assert the count you expect rather than "once" when the code enters twice. * Setting `__aexit__.return_value` truthy by accident (for example by configuring the parent mock with a blanket `return_value`), which suppresses exceptions inside the block. ### The neighbouring protocol `async for` is doubled the same way and often appears in the same test. A `MagicMock` exposes `__aiter__` and an `__anext__` that is itself an `AsyncMock`, and the shortest way to make a double iterable is `stream.__aiter__.return_value = iter([record_a, record_b])`, which the mock adapts to the asynchronous protocol. A cursor that is both an async context manager and an async iterator therefore needs both configured, and forgetting the iteration side is why a block that should have processed rows quietly processes none. ### Version notes `__aenter__`, `__aexit__` and `__anext__` have been pre-configured as `AsyncMock` children on `MagicMock` since Python 3.8, and the behaviour is unchanged on 3.14.