What does a Go test binary print when the go test -timeout deadline expires?

## What the flag actually arms `go test -timeout d` sets a deadline for the **test binary**, which means one deadline for the whole package's run, not per test function. The default is ten minutes. `-timeout 0` disables the deadline entirely, which is occasionally right for a long soak test and almost always wrong in a pipeline, because a hang then consumes the job's own limit and produces no diagnostic at all. ## What it prints When the deadline expires, the testing package raises the traceback level so that no environment setting can suppress the output, then panics. The result looks like this: ``` panic: test timed out after 30s running tests: TestFanoutBroadcast (30s) goroutine 1 [chan receive]: ... goroutine 47 [chan send]: example/fanout.(*hub).broadcast(...) /src/fanout/hub.go:88 +0x9c ``` Three pieces of information are in there, and each answers a different question. 1. **The panic line** tells you it was the deadline, not a crash. A test that fails this way did not assert anything; it simply never finished. 2. **The list of running tests** with elapsed times tells you which test was stuck. If several are listed, the suite was running them in parallel. 3. **The stack of every goroutine in the process** tells you *why*. This is the part that matters for a leak: each goroutine header carries its state — `chan send`, `chan receive`, `select`, `semacquire`, `IO wait`, `sync.WaitGroup.Wait` — and, once it has been parked long enough, roughly how long it has been there. The frames underneath name the exact line it is parked on. ## Reading it for a leak For a fan-out service that keeps one subscription goroutine per connected client, the useful pattern in that dump is repetition. Twenty goroutines sharing one stack, all in `chan send` inside the broadcast loop, is not twenty bugs — it is one bug seen twenty times: the receive side went away and nobody closed the channel or selected on a done signal. The line number under the repeated frame is the fix site. A second pattern worth recognising is a single goroutine parked with a very long wait time while the test that started it finished long ago. That is a leak from an **earlier** test showing up in a dump triggered by a **later** one. ## What it does not catch This is the crucial limitation, and it is the reason an explicit leak check exists alongside it. The deadline fires only if something is still running when it expires. A leaked goroutine that does not block the test does not keep the binary alive: the last test finishes, the process exits, every parked goroutine is discarded, and the package is reported as passing. So: - **`-timeout` catches hangs.** A goroutine the test is waiting on, a deadlock, a channel nobody serves on the critical path. - **It does not catch silent leaks.** A subscription goroutine nobody is waiting for leaks in complete silence and takes the service down in production instead. The two checks are complements, not alternatives. ## Practical use - Set a deadline well below your pipeline's job limit so you get the Go dump instead of a killed job with no output. - When a timeout appears, read the goroutine list before the stacks: which tests were running tells you where to start, and how many were running tells you whether parallelism is involved. - Do not lower the timeout to "catch problems earlier". A deadline tight enough to fire on a slow machine converts a capacity problem into a flaky failure, and the dump it produces looks identical to a real hang. - Do not reach for `-timeout 0` to make a stubborn timeout go away. It removes the only diagnostic you had.