## TL;DR

`go test` kills any package that runs longer than its timeout (default 10m) and panics with a stack dump. The quick relief is `-timeout 30m`; the real fix is finding which test hung, using the goroutine stacks in the panic output or re-running with -v to see the last test that started.

## Error

```text
panic: test timed out after 10m0s
running tests:
    TestProcessLargeFile (600s)
```

## Steps

1. Re-run just the stuck package with a longer timeout: `go test -timeout 30m -run TestProcessLargeFile ./pkg/worker`. Expected: the package completes, or you get a fresh stack dump to read.
2. If it still hangs, read the panic's goroutine stacks and find the one inside your test code. Expected: you see the function and line where it waits (channel receive, mutex, network read).
3. Fix the hang at its source: a test waiting on a channel nobody closes needs the missing close or a timeout branch. Expected: the test finishes on its own.
4. If the suite is legitimately slow, make the longer timeout permanent in CI, e.g. `go test -timeout 20m ./...`. Expected: CI stops killing healthy slow suites.
5. For a suite you own, split it: move the slow test to its own package or add t.Parallel where safe. Expected: wall time drops back under the default.

## When to use

- The panic names a test and a duration like 10m0s.
- A suite that used to pass now times out (input grew, or CI got slower).
- The hang reproduces with -run on a single test.

## When not to use

- Tests FAIL with assertion diffs (a logic bug, not a hang).
- The package does not build (compile error, different fix).
- `panic: runtime error` like nil pointer dereference (a crash, not a timeout).

## Tool compatibility

- Go 1.16 and newer, `go test` with the -timeout flag.
- Works the same under testify suites and plain testing.

## Variant phrasings

### test timed out after 5m0s

Someone set -timeout 5m explicitly. Same diagnosis, just a shorter fuse.

### panic: test timed out with no test listed

The hang is in TestMain or a package init, not a test function. Read the stacks for init or TestMain frames.

### signal: killed

The OS killed the test binary, usually out of memory. That is resource exhaustion, not the go test watchdog.

## Why it happens

The go test binary runs each package with a watchdog; when the deadline passes it panics and dumps every goroutine's stack. A deadlock on an unbuffered channel, a network call with no deadline, or a test that legitimately takes 12 minutes all trip it.

## Edge cases

- `-timeout 0` disables the watchdog entirely; fine for local debugging, never in CI.
- The stack dump lists testing.tRunner frames first; your code is further down the trace.
- Parallel subtests each hold the clock, so one slow subtest can doom the whole package.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_m5O4iYUNUAptpUZwAZVAng