Coverage Profiles

## What the Go toolchain actually measures Go's coverage is **statement coverage**, computed by source rewriting. When you pass `-cover`, the toolchain makes an instrumented copy of each package under test: it splits every function into basic blocks (a straight run of statements with no branch in or out) and inserts a counter update at the top of each block. Compiling and running that copy tells you which blocks executed. The percentage `go test` prints is `covered statements / total instrumented statements`. ## The three commands **1. Produce a number.** ``` go test -cover ./... ``` Each package line gains `coverage: 78.3% of statements`. This is enough for a quick check but tells you nothing about which lines are missing. **2. Produce a profile.** ``` go test -coverprofile=cover.out ./... ``` `-coverprofile` implies `-cover`. It writes a text file whose first line is the mode header and whose remaining lines are one block each: ``` mode: set example.com/m/store/store.go:14.28,17.2 2 1 example.com/m/store/store.go:19.31,21.16 2 0 ``` The fields are: the import path plus file, the block's start `line.column` and end `line.column`, the number of statements in the block, and the counter. In `set` mode that counter is `1` if the block ran and `0` if it did not; the second line above is a block that never executed. **3. Read the profile back.** ``` go tool cover -func=cover.out go tool cover -html=cover.out -o cover.html ``` `-func` prints one row per function with its percentage and a final `total:` row — the form CI logs usually capture. `-html` renders each source file with covered blocks shaded green, uncovered blocks red, and untracked text grey; without `-o` it writes a temporary file and opens your browser, which is why CI always passes `-o`. ## Things that surprise people the first time - **The profile is per-run, not cumulative.** One `go test -coverprofile=...` invocation over many packages writes one file. `go tool cover` has no merge subcommand, and the text format carries a single `mode:` header, so you cannot simply concatenate two profiles from two runs; run one command over all the packages you care about instead. - **By default only the package under test is instrumented.** A test in package `a` that calls into package `b` does not credit `b` with anything unless you pass `-coverpkg`. - **Coverage measures execution, not assertion.** A test that calls a function and checks nothing still turns the block green. That is a property of the mechanism, not a flaw in the report. - **Instrumentation costs.** The instrumented build is a different build, so `-cover` runs are slower than plain ones and produce a bigger test binary. That is usually irrelevant for a package test and very relevant for a whole-repo CI job. ## A minimal workflow Locally, the loop that actually finds gaps is: run `go test -coverprofile=cover.out ./yourpkg`, open `go tool cover -html=cover.out`, and read the red. Red inside an error branch usually means no test constructs the failure; red inside an exported function usually means nobody calls it from a test at all. In CI, `-func` plus a threshold check is the common shape because it produces a single grep-able number and a per-function breakdown for the log.