Result Reuse and -count

## What `(cached)` actually reports When `go test` finishes a package successfully, the go command writes that package's test output and exit status into the build cache directory (`go env GOCACHE`) under a key derived from everything it believes the run depended on. The next time you ask for the same package with the same inputs, it does not compile-and-run anything: it looks the entry up, prints the stored output, and marks the summary line `(cached)` where the elapsed time normally goes. ``` ok example.com/billing/internal/rates 0.412s <- ran ok example.com/billing/internal/rates (cached) <- reprinted ``` So the marker is not "the tests ran quickly" and not "the tests were skipped". It is "the test binary was not executed; you are looking at a recording". With `-v`, the recorded verbose log is replayed too, which is why a cached run can print a wall of `--- PASS` lines instantly. ## Only successful runs are cached This is the property that makes the feature tolerable. A package that fails is re-run every single time, so you can never be looking at a stale failure. The risk runs entirely in the other direction: a stale *pass*, if something the go command could not observe changed underneath you. ## When caching applies at all The go command caches in package list mode — when you name packages, as in `go test ./...`, `go test .`, or `go test example.com/billing/...`. The local-directory form, plain `go test` with no package arguments, is documented as not caching, which is why some developers say they "never see (cached)" while a colleague sees it constantly. Results are stored per package: in a repo-wide run you routinely get a mix, a few packages executing and the rest replaying. ## Forcing a real run The conventional escape hatch is `-count=1`: ``` go test -count=1 ./internal/rates/ ``` It is worth knowing *why* this works, because the usual guess is wrong. `-count=1` is already the default number of runs, so it changes nothing about execution. It works because the go command only reuses a result when every flag on the command line comes from a small set it considers safe to cache across (`-run`, `-v`, `-short`, `-timeout`, `-cpu`, `-parallel`, `-failfast`, `-list`, `-fullpath`). `-count` is deliberately not in that set, so passing it makes the invocation uncacheable: the result is not matched against the cache and not stored either. Any other non-cacheable flag has the same effect; `-count=1` is simply the idiom because it is otherwise a no-op. The heavier hammer is `go clean -testcache`, which expires every stored test result in the build cache — all packages, all modules, everything that shares that `GOCACHE`. It leaves the compiled-package build cache alone, so your next build is still fast. `go clean -cache` is the one that wipes compiled artefacts too and makes the next build slow; reach for it only when you actually suspect the build cache. ## Why a package you did not touch can still be `(cached)` The entry is keyed on the test binary for *that* package, which is built from the package's own source plus all of its dependencies. Editing an unrelated package leaves that binary byte-identical, so the reuse is correct. Editing a package that the test imports rebuilds the binary and produces a different key, so it re-runs. That is the behaviour you want: the cache is a per-package memo, not a global timestamp. ## What to say in an interview Name the three facts: the binary did not run, only passes are cached, and `-count=1` disables reuse because `-count` is outside the cacheable flag set. Then add the honest caveat — the cache only knows about inputs the go command can see, so a test that talks to a service or reads a file outside its own source tree can go on printing `(cached)` after the thing it depends on has changed.