---
title: "Run the tests with a race detector · Agent Wranglers"
url: https://agentwranglers.se/playbook/testing/security-and-robustness/race-detector
id: TST-62
level: Recommended
updated: 2026-10-22
build: a2a6bdfed830
tokens: 997
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Run the tests with a race detector

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Security and robustness](https://agentwranglers.se/playbook/testing/security-and-robustness.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-22.

- ID: TST-62
- Level: Recommended
- Chapter: [Security and robustness](https://agentwranglers.se/playbook/testing/security-and-robustness.md)
- Rule: When code runs on several threads or goroutines, run the tests with a race detector in CI on every pull request. Fail on any race it reports.
- Check: The CI job runs the suite with the race detector, and its log shows the flag. Add two goroutines or threads that write one counter without a lock on a branch. The job fails and names both lines.
- How: A data race corrupts state only now and then, so normal tests pass and the bug shows up in production under load. Race detectors watch memory access while the tests run. Examples are `go test -race` for Go, ThreadSanitizer (`-fsanitize=thread`) for C, C++ and Rust, and Miri for unsafe Rust. They find races only in code the tests run, so give concurrent code tests that start several workers at once. The detector slows tests and uses more memory, so a separate CI job may run it. Fix each race with the patterns in [Guard state that concurrent code shares](https://agentwranglers.se/playbook/architecture/concurrency/guard-shared-state.md). Languages without shared-memory threads, such as JavaScript in one event loop, still race across `await` and need [Make conditional writes](https://agentwranglers.se/playbook/data/transactions-and-concurrency/conditional-writes.md) instead.

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### Go example

```go
// go test -race ./...
func TestCounterIsSafeAcrossWorkers(t *testing.T) {
    counter := NewVisitCounter()
    var wg sync.WaitGroup
    for range 50 {
        wg.Add(1)
        go func() { defer wg.Done(); counter.Add() }()
    }
    wg.Wait()
    if counter.Total() != 50 {
        t.Fatalf("got %d visits, want 50", counter.Total())
    }
}
```

### Plain text example

```rust
// RUSTFLAGS="-Zsanitizer=thread" cargo +nightly test -Zbuild-std --target x86_64-unknown-linux-gnu
#[test]
fn counter_is_safe_across_workers() {
    let counter = std::sync::Arc::new(VisitCounter::new());
    let workers: Vec<_> = (0..50)
        .map(|_| { let c = counter.clone(); std::thread::spawn(move || c.add()) })
        .collect();
    for worker in workers { worker.join().unwrap(); }
    assert_eq!(counter.total(), 50);
}
```

## Sources

- [Go data race detector](https://go.dev/doc/articles/race_detector)

## Related rules

- ARC-40 [Guard state that concurrent code shares](https://agentwranglers.se/playbook/architecture/concurrency/guard-shared-state.md) in Clean code and architecture
- DAT-16 [Make conditional writes](https://agentwranglers.se/playbook/data/transactions-and-concurrency/conditional-writes.md) in Data and databases

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/testing/security-and-robustness/race-detector">Agent Wranglers testing playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Fuzz every parser of untrusted input](https://agentwranglers.se/playbook/testing/security-and-robustness/fuzz-parsers.md)
- Next: [Break the services you depend on in a test environment](https://agentwranglers.se/playbook/testing/security-and-robustness/environment-fault-injection.md)
- [Security and robustness](https://agentwranglers.se/playbook/testing/security-and-robustness.md)