A binary built with `go build -cover` wrote nothing to GOCOVERDIR after an end-to-end run. Why?

## Coverage outside `go test` `go test -cover` measures what a test binary executes. It cannot measure what a *deployed* binary executes — a server started by a docker-compose-style harness, driven by an end-to-end script that speaks HTTP to it. For that the toolchain offers a second path: ``` go build -cover -o ./bin/server ./cmd/server ``` The result is an ordinary binary you can ship into a test environment, with counters compiled into every basic block. It behaves normally; the only difference is that on exit it emits coverage data. ## Where the data goes, and when The binary writes into the directory named by the **`GOCOVERDIR`** environment variable. Two files are produced per run: a meta-data file describing the packages and blocks (stable across runs of the same binary) and a counter file holding this run's counts. Several runs accumulate several counter files in the same directory, which is exactly the intended shape — start the server, run scenario A, restart, run scenario B, and the directory holds both. Two failure modes fall directly out of that design, and they are what the question is really about: 1. **`GOCOVERDIR` is not set in the binary's environment.** It is easy to export it in the shell that runs the test script while the server itself is started by a container runtime or a process supervisor that does not inherit it. The binary then runs happily and emits a warning to stderr about coverage data not being written — a line nobody reads in a busy CI log. 2. **The process never terminates normally.** The write happens on the way out of the process. A harness that ends with `kill -9`, an orchestrator that SIGKILLs the container at teardown, or a hard crash all skip it. The end-to-end run genuinely exercised the code; the evidence is simply gone, and the report shows zeros for paths you watched execute. The second one is the classic. The symptom — 'the script demonstrably hit that endpoint and the coverage report says the handler never ran' — points at measurement, not at the tests. ## Fixing it **Shut down gracefully.** Give the server a signal handler for SIGTERM that returns from `main` (or calls `os.Exit`) after draining, and have the harness send SIGTERM and wait rather than SIGKILL. This is the smallest change and it is usually a good idea for its own sake. **Or flush explicitly.** The `runtime/coverage` package lets an instrumented process write its own data mid-life: ```go if err := coverage.WriteCountersDir(os.Getenv("GOCOVERDIR")); err != nil { log.Printf("coverage flush failed: %v", err) } ``` Call it from an admin endpoint or a signal handler, and the counters are on disk before anything can kill the process. `coverage.WriteMetaDir` writes the meta-data file, and `coverage.ClearCounters` resets counters so you can attribute a following scenario separately. This is the approach for a long-running service you deliberately never restart during the test window. ## Reading the result The files in `GOCOVERDIR` are a binary format, not the text profile `go tool cover` consumes. `go tool covdata` bridges the two: ``` go tool covdata percent -i=/tmp/covdata go tool covdata func -i=/tmp/covdata go tool covdata merge -i=/tmp/run1,/tmp/run2 -o=/tmp/merged go tool covdata textfmt -i=/tmp/merged -o=cover.out go tool cover -html=cover.out -o cover.html ``` `percent` and `func` give you numbers directly. `merge` combines several directories — which is how you fold three scenario runs into one result, and notably something the text profile format cannot do. `textfmt` converts to the familiar profile so the HTML renderer and any existing tooling still work. ## Why this matters operationally A coverage number that mixes unit tests and end-to-end runs is only trustworthy if the end-to-end half is actually being captured. Silent loss is the dangerous case: nobody notices a missing counter file, the total quietly drops, and the team responds by writing more unit tests for code the integration suite already covers. Making the harness fail loudly when `GOCOVERDIR` ends up empty is a cheap guard, and it turns an invisible measurement bug into a build failure.