In a Go test, when is the context from t.Context() cancelled relative to t.Cleanup functions?

## What t.Context gives you Most Go code that does anything blocking takes a `context.Context` as its first parameter. Tests therefore need one to pass in, and for years every test wrote `ctx, cancel := context.WithCancel(context.Background())` plus a `defer cancel()`, or just passed `context.Background()` and never cancelled anything. `t.Context()` (added in Go 1.24, alongside the same method on `*testing.B` and `*testing.F`) supplies a context scoped to the test, so the code under test is actually told to stop when the test ends. ## The exact timing The documented contract is that the returned context is **cancelled just before the functions registered with `t.Cleanup` are called**. Laid out for one test: 1. The test body runs, having passed `t.Context()` into the code under test. 2. The test finishes (returns, fails, or is stopped by `Fatal`). 3. For a parent test, all subtests complete. 4. **`t.Context()`'s context is cancelled.** 5. Cleanup functions run, LIFO. That ordering exists so cleanups have something stable to clean up. Background work started by the code under test — a goroutine polling, a request in flight, a watcher loop — sees `ctx.Done()` close *before* teardown begins, and a cleanup can then wait for those things to shut down before removing the resources they were using. Tearing the directory or the server out from under still-running work would produce exactly the confusing late errors that this ordering avoids. ## The consequence you must design around Because cancellation happens *before* step 5, **every cleanup function sees an already-cancelled context**. Any code inside a cleanup that honours cancellation will fail immediately: ```go t.Cleanup(func() { // ctx here is already canceled: this call fails with context.Canceled. if err := purgeRemote(t.Context(), id); err != nil { t.Errorf("purge: %v", err) } }) ``` The symptom is a teardown that always reports `context canceled` and a fixture that is never actually removed, in a test that otherwise passes. The fix is to give the cleanup its own context: ```go t.Cleanup(func() { ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() if err := purgeRemote(ctx, id); err != nil { t.Errorf("purge: %v", err) } }) ``` A bounded timeout matters here: a cleanup that hangs holds the whole test binary until the package timeout fires and produces a much less readable failure. ## Scoping Each test and each subtest gets its own context. A subtest's context is cancelled when *that subtest* completes, so a parallel subtest's context closes well before the parent's. The parent's context is cancelled only once every subtest has completed, because that is when the parent's cleanups run. If you create fixtures in the parent and use them from parallel subtests, pass the parent's `t.Context()` down when you want the whole group to be cancelled together, and each subtest's own `t.Context()` when work should stop with that case alone. ## What it is not `t.Context()` is not a timeout. It does not carry a deadline of its own; it is cancelled by the lifecycle, not by the clock, and the test binary's overall `-timeout` is a separate mechanism that panics the whole run rather than cancelling this context politely. If a specific operation in a test needs a deadline, wrap it: `context.WithTimeout(t.Context(), d)`. It also is not a place to carry test fixtures. It is a cancellation signal that happens to be a `context.Context`; values belong in explicit parameters or in the test's own variables. ## Before Go 1.24 Older tests do this by hand, and the hand-written version is worth recognising in a review: `ctx, cancel := context.WithCancel(context.Background())` with `t.Cleanup(cancel)` gets close, but note that a `t.Cleanup(cancel)` registered early runs *last* under LIFO, so the cancellation lands after the other cleanups rather than before them — the opposite of the built-in ordering. That subtle difference is a good reason to use `t.Context()` where the toolchain version allows it.