Running Under -race

## The flag is a build flag, not a runtime switch `-race` changes how the test binary is compiled. The compiler instruments the package under test and everything it links, inserting a call into the race runtime around each memory read and write and around each synchronisation operation (channel send and receive, mutex lock and unlock, atomic operations, `WaitGroup` calls, goroutine start and exit). The instrumented runtime maintains shadow state for the memory the program touches, recording which goroutine last read or wrote each location and what synchronisation had happened at that moment. Because it is a build flag, there is no way to switch it on for an existing binary. `go build -race`, `go run -race` and `go test -race` all produce a different, instrumented artefact, cached separately from the ordinary one. ## What it reports, and what it cannot The detector is *dynamic*. It reports a conflict when two goroutines actually touch the same memory location, at least one of them writing, with no synchronisation ordering the two accesses — and both of those accesses have to genuinely execute during the run. That has two consequences a junior candidate is expected to state plainly: - A race in code your tests never call is not reported. The detector saw nothing, so it says nothing. - A race in code your tests *do* call may still go unreported if, in that run, the two goroutines happened to be ordered by some synchronisation, or one of them never got far enough. Running the same suite again can produce a different verdict. So a green `-race` run is evidence that the interleavings you exercised were clean. It is not a proof of absence. ## Reading the output A report is bracketed by lines of `=` and starts with `WARNING: DATA RACE`. It names the offending access first — for example `Write at 0x... by goroutine 9:` — with a stack, then `Previous read at 0x... by goroutine 8:` with its stack, and often the stack where each goroutine was created. That second stack is the valuable half: it tells you which other code path was touching the same memory. The `testing` package checks after each test whether the race runtime recorded new reports, and if so fails that test with the message `race detected during execution of test`. That is how a race becomes attributable to a specific test rather than to the package as a whole. If a race is detected outside any running test — during package initialisation, in `TestMain` before or after `m.Run`, or in a goroutine that outlived the test that started it — there is no test to blame, and you see only the report plus `Found N data race(s)` at exit. ## The exit status By default the run does not stop at the first report; it continues, collecting more, and the race runtime uses a dedicated exit status (66 unless you override it through the `GORACE` environment variable) when the process exits because races were detected. From `go test`'s point of view the package failed: it prints `FAIL` and exits non-zero. Any CI system that treats a non-zero exit as a failed step therefore gates merges on the detector with no extra wiring — and conversely, a pipeline step that swallows that status (piping it through something that always succeeds, or only grepping the log) has silently turned the gate off. ## How you actually use it Run it locally on the package you just changed before you push, especially if the change introduced a goroutine, a shared map or a cached value: `go test -race ./cache`. When a report appears, read both stacks, find the shared location, and decide whether the fix is a mutex, a channel hand-off, giving each goroutine its own copy, or removing the sharing entirely. Re-run under `-race` to confirm the report is gone; the absence of a report on the same test that produced one is meaningful, even though absence in general is not. A common beginner mistake is to reach for `-race` when the symptom is a hang or a leak. It is a data-race detector: it has nothing to say about a deadlock, a goroutine that never exits, or a logic bug in your synchronisation that is nonetheless properly synchronised.