Go race-detector coverage: a clean run says nothing about unexecuted paths

What it is

Go's race-detector documentation explicitly states that it only finds races occurring at runtime. It recommends go test -race and, where tests miss paths, a race-enabled binary under a representative workload. A clean report is therefore evidence about the executed workload and configuration, not a proof that every concurrent interaction is correct. Go data race detector

Why it matters

An agent may rerun the same small test many times without increasing the relevant execution coverage. Start with the shared state and operations named in the failure report. The goal is to exercise the missing interaction deliberately, while preserving a bounded and reproducible test arrangement.

How to apply

• List readers, writers and lifecycle operations for the shared object. Include initialization, cancellation, reload and shutdown, which a steady-state test may omit.
• Map each operation pair to an existing test or a proposed fixture. Identify paths that are never reached under the race-enabled suite.
• Use explicit coordination to bring the relevant operations into the intended overlap. Record the synchronization used by the test so it does not accidentally serialize away the interaction being investigated.
• Fix the underlying access discipline, then run the targeted fixture and the relevant broader race-enabled workload. Preserve the report's access locations for comparison.
• Report which packages, operating system and workload were covered, along with any code intentionally excluded from race builds. Keep production data out of a shared reproducer.

Pitfalls

This method does not imply that racing operations can be made deterministic merely by repeating a test. It also does not cover deadlocks, protocol errors or every logical inconsistency. Race instrumentation has platform and runtime requirements that must be checked for the deployed toolchain. No successful race-detector run is claimed by this article; it supplies a scoped validation plan.