The race detector and coverage
The race detector and the coverage tool are two ways to look at a test run rather than two kinds of test. The first instruments the binary and reports unsynchronised access to shared memory; the second counts which statements the tests executed. Both are switches on go test, which is the reason they are cheap to adopt: nothing in the code changes. The benchmark lesson measured speed; this one looks for bugs and for blind spots.
The race detector
go test -race builds the test binary with the race detector, which records every read and write of memory with the goroutine that made it and reports two accesses to the same address without synchronisation. The mutex in the counter is what keeps the report quiet: without it the test still finishes and the counter is usually wrong, which is why the race detector is more reliable than the wrong answer.
package counter
import (
"sync"
"testing"
)
type Counter struct {
mu sync.Mutex
n int
}
func (c *Counter) Inc() {
c.mu.Lock()
c.n++
c.mu.Unlock()
}
func (c *Counter) Value() int {
c.mu.Lock()
defer c.mu.Unlock()
return c.n
}
func TestCounterConcurrent(t *testing.T) {
var c Counter
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
wg.Add(1)
go func() {
defer wg.Done()
for j := 0; j < 100; j++ {
c.Inc()
}
}()
}
wg.Wait()
if got := c.Value(); got != 10000 {
t.Errorf("Value() = %d, want 10000", got)
}
}
go test -v -race .
=== RUN TestCounterConcurrent
--- PASS: TestCounterConcurrent (0.02s)
PASS
ok example.com/counter 1.043s
The detector found nothing, and the test passed, because every access goes through the mutex. When it does find a race it prints WARNING: DATA RACE with two stacks and the addresses involved, and the test fails; those addresses change on every run, which is why this page shows the clean run and the shape of the report rather than a captured one. The detector only sees the execution it instruments: a race on a path no test took is not reported.
Coverage of statements
go test -cover prints the percentage of statements the tests executed. The number is a map of what was never run, not a grade: a test that calls a function without checking its result still counts as covering it. The switch case function below has four branches, and the table reaches all of them.
package grade
import "testing"
func TestLetter(t *testing.T) {
cases := []struct {
score int
want string
}{
{95, "A"},
{85, "B"},
{75, "C"},
{10, "F"},
}
for _, tc := range cases {
if got := Letter(tc.score); got != tc.want {
t.Errorf("Letter(%d) = %q, want %q", tc.score, got, tc.want)
}
}
}
go test -v -cover .
=== RUN TestLetter
--- PASS: TestLetter (0.00s)
PASS
coverage: 100.0% of statements
ok example.com/grade 0.005s coverage: 100.0% of statements
go test -coverprofile=cover.out .
ok example.com/grade 0.007s coverage: 100.0% of statements
The profile run wrote cover.out, which go tool cover reads. The -func form prints one line per function and a total, and the HTML form paints the source in two colours. A profile from CI is a useful artefact to attach to a review, because it shows which lines the new tests actually reached.
go test -coverprofile=cover.out . && go tool cover -func=cover.out
ok example.com/grade 0.006s coverage: 100.0% of statements
example.com/grade/grade.go:3: Letter 100.0%
total: (statements) 100.0%
A test that stops at the happy path leaves the rest of the function grey in the HTML report. The next block has one test that only reaches the first two cases, and the percentage makes the gap visible without reading the source:
package grade
import "testing"
func TestLetterHigh(t *testing.T) {
if got := Letter(95); got != "A" {
t.Errorf("Letter(95) = %q, want A", got)
}
if got := Letter(85); got != "B" {
t.Errorf("Letter(85) = %q, want B", got)
}
}
go test -v -cover .
=== RUN TestLetterHigh
--- PASS: TestLetterHigh (0.00s)
PASS
coverage: 60.0% of statements
ok example.com/grade 0.006s coverage: 60.0% of statements
The number fell because the low branches were never executed, which is exactly the kind of statement coverage can see. It cannot see that the reached branches were checked: a table that calls the function and ignores the result would report the same percentage and prove nothing, so coverage finds missing tests, not weak ones.
Exercises
- Remove the mutex from the counter and run the test with and without -race. What does the test report, and what does the detector report?
- Replace the switch with a map of thresholds and run the coverage profile again. Which statements are still uncovered, and what test would cover them?
- Add a function with an early return for an invalid input, leave it untested, and find it in the HTML coverage report. Which line is grey?
Questions
A new set of questions in a new order every time. Choose one answer for each, then check.
-
What does go test -race detect?
Answer
Unsynchronised concurrent access to the same memory
It reports two accesses without a happens-before relationship between them.
-
Does a passing test prove the absence of a race?
Answer
No, the detector only sees the execution it instrumented
An untested path can race without being reported.
-
What does go test -cover measure?
Answer
The share of statements the tests executed
Coverage counts execution, not verification.
-
What does a coverprofile let you do?
Answer
Read the coverage per function or per line with go tool cover
go tool cover -func and -html read the profile file.
-
Why does the counter test need a mutex under -race?
Answer
Without it the unsynchronised increment is a data race
Concurrent writes to the same int are the textbook race.
-
What does a grey line in the HTML coverage report mean?
Answer
The statement was never executed by the tests
The report paints executed statements green and unexecuted ones grey.
-
Why is 100% coverage not a certificate?
Answer
A test can execute a line without checking the result
Coverage shows what ran, not what was asserted.
-
What does -race do to the speed of the test binary?
Answer
It slows it down and uses more memory
Instrumentation is expensive, which is why it is not the default.
-
Which command prints coverage per function?
Answer
go tool cover -func=cover.out
The -func flag prints one line per function with its percentage.
-
Where does a coverprofile come from?
Answer
go test -coverprofile=cover.out
The test run writes the profile, and go tool cover reads it.
The code on this page was run with go 1.26.10 on Alpine Linux 3.24.3 (x86_64) in a Docker container.
Article author: Arthur Isaev