How do you test that a coroutine's cancellation and timeout branches actually run?

### Cancellation and timeout are code paths, so they need tests Every long-running coroutine has at least two exits: the happy path, and the path where somebody cancels it or a deadline expires. The second exit is where the resource cleanup lives — releasing a warehouse reservation, returning a connection, flushing a partial pick-list — and it is almost never exercised by the happy-path tests. Untested cleanup code is how a service that looks fine in CI leaks reservations in production every time a client disconnects. ### Driving the cancellation branch The recipe has four steps, and skipping any one of them produces a test that passes without testing anything. **1. Start the coroutine as a task.** `asyncio.create_task` schedules it; the test keeps the task object, because that is the handle you cancel and await. **2. Wait until it has actually reached the await you intend to interrupt.** If you cancel immediately, the task may be cancelled before its body has run a single line, and the `except` branch you wanted to test never executes — the test goes green having proved nothing. Use an `asyncio.Event` the coroutine sets at the point of interest, not a sleep. **3. Cancel, then await.** `Task.cancel()` only *requests* cancellation: it arranges for `CancelledError` to be thrown into the coroutine at its current suspension point the next time the loop runs it. Nothing has happened yet when `cancel()` returns. The test must `await` the task (or gather it) for the cancellation to be delivered and the cleanup to run. **4. Assert on both the outcome and the side effect.** `task.cancelled()` must be `True`, and the observable cleanup must have happened. Asserting only the side effect misses a coroutine that swallows the cancellation; asserting only `cancelled()` misses cleanup that silently did not run. ### Why `cancelled()` is the sharp assertion `asyncio.CancelledError` inherits from `BaseException`, not `Exception` — that has been true since 3.8, and it exists precisely so that a blanket `except Exception:` in application code does not accidentally eat a cancellation. A coroutine that catches `CancelledError` and returns normally instead of re-raising is a real and common bug: the task finishes *successfully*, `task.cancelled()` is `False`, awaiting it yields a value, and the surrounding structured-concurrency machinery believes the shutdown succeeded when it did not. That single assertion catches the bug, which is why it belongs in the test even when the cleanup assertion already passes. The correct shape in the code under test is catch, clean up, re-raise: ```python try: await do_work() except asyncio.CancelledError: release_reservation() raise ``` A `finally:` block is the alternative when the cleanup is unconditional; the `except` form is what you want when the cleanup is specific to being cancelled. ### The timeout branch Test it by making the work *never* complete and the budget *tiny*, never by sleeping the real duration: ```python async with asyncio.timeout(0.01): await never_completes() ``` `asyncio.timeout` and `asyncio.timeout_at` arrived in 3.11 and are the modern form; `asyncio.wait_for` still exists and does the same job for a single awaitable. Since 3.11 `asyncio.TimeoutError` is an alias of the builtin `TimeoutError`, so `except TimeoutError:` is the correct catch on 3.14 — older material that carefully distinguishes the two is out of date. The mechanism to explain in an interview: a timeout scope works *by cancelling* the task inside it and converting that cancellation into `TimeoutError` at the boundary. So the coroutine under test sees `CancelledError` internally, and the caller sees `TimeoutError`. Code that swallows `CancelledError` therefore breaks timeouts too — the deadline expires and nothing stops. That is one bug with two symptoms, and one test for each. Two anti-patterns to name explicitly. First, asserting on elapsed wall-clock time (`assert 0.09 < elapsed < 0.12`) reintroduces exactly the machine-speed dependence you were trying to avoid; assert that the branch was taken, not how long it took. Second, using a real multi-second timeout in a test makes the suite slow for no additional coverage: the code path is identical at 10 ms. ### Edges worth a sentence `asyncio.shield` protects an inner awaitable from an outer cancellation, and a test for shielded code must assert that the inner work *continued*. `Task.uncancel` and `Task.cancelling` (3.11) exist so that a nested timeout scope can absorb its own cancellation without breaking an outer one; they matter when you write your own scope-like helper, and asserting on `cancelling()` counts is how you prove such a helper does not swallow an outer cancel.