What does go test -race do, and what does its DATA RACE report contain?

## The flag is a build mode, not a test option `-race` is accepted by `go build`, `go run`, `go install` and `go test` alike. When you pass it, the compiler instruments the code: around reads and writes of memory that could be shared, it inserts calls into a race runtime that is linked into the resulting binary. The binary `go test -race` runs is therefore a genuinely different program from the one plain `go test` runs — same source, different object code, cached separately. Everything people say about the race detector's speed and memory use applies to that instrumented binary only; it says nothing about the build you deploy. ## What it watches while the tests run For each word of memory the program touches, the race runtime keeps a small record of which goroutines accessed it and how those goroutines were ordered relative to each other. Ordering comes from the synchronization you already write: a channel send and the receive that takes it, a `sync.Mutex` unlock and the next lock of the same mutex, `sync.WaitGroup.Done` and the `Wait` that returns after it, `sync.Once`, and the `sync/atomic` operations. When a new access arrives, the runtime asks one question: is this access ordered, through some chain of those operations, with respect to the earlier accesses to this same memory? If two accesses to the same memory are **not** ordered by anything, and at least one of them is a write, that is a data race and it is reported. Notice what is *not* in that rule: the wall-clock gap between the two accesses. Two goroutines that touch the same variable a full second apart are still reported, as long as nothing synchronizes them. You do not have to be lucky enough to hit the exact interleaving that would corrupt data — you only have to make both accesses happen in the same run. ## Reading the report A report is a block delimited by lines of `=` characters. It names the offending access first (`Write at 0x... by goroutine 9`), then the earlier conflicting one (`Previous read at 0x... by goroutine 8`), each with a stack trace pointing at file and line. Below those, `Goroutine 9 (running) created at:` gives the stack of the `go` statement that started that goroutine — often more useful than the access itself, because it shows where the sharing was introduced. At the end of the run the binary prints `Found N data race(s)` and the test fails. The address matters: the report is about a piece of memory, not a variable name. Two differently named slices that share one backing array are the same memory as far as the detector is concerned. ## What it costs An instrumented binary typically runs 2–20x slower and uses 5–10x more memory than the same tests without `-race`. That is why `-race` is a deliberate mode rather than the default, and why bolting it onto an existing CI job with tight timeouts and memory limits tends to produce timeouts before it produces race reports. ## What it is not It is not a static analyser. It never looks at code it does not execute, so it is not a substitute for review or for linting, and a clean run says only that the accesses that actually happened were properly ordered. It is also not a general concurrency checker. It does not report deadlocks — a program where every goroutine is blocked is caught by the Go runtime's own fatal `all goroutines are asleep - deadlock!` throw, not by `-race`. It does not report goroutines that never exit. And it does not judge whether your locking is *semantically* right: code that takes a mutex around each of two operations that needed to be atomic together is perfectly race-free and still wrong. ## Running it `go test -race ./...` is the usual invocation, optionally narrowed with `-run` while you are chasing one test. Because the failure is a normal test failure, it fits any CI system without special handling. The one habit worth forming early: when a concurrency bug is reported and you cannot reproduce it, running the relevant tests under `-race` is the first thing to try, not the last.