Go - race detector workflow (GORACE, stress, goleak)

The Go race detector (ThreadSanitizer compiled into the binary via -race) and goroutine leaks are two separate failure classes: the detector finds concurrent unsynchronized access, goleak finds goroutines that never stop. Run both.

Enable the race detector

Per go.dev/doc/articles/race_detector (opens in new window):

go test -race ./...
go run  -race main.go
go build -race ./cmd/server

Requires cgo and a C compiler on Linux/FreeBSD/Windows (mingw-w64 v8+ on Windows; Darwin ships its own). Expected overhead per the same doc: 2-20x execution time, 5-10x memory, plus 8 bytes per defer/recover accumulating until the goroutine exits - budget CI timeouts accordingly.

A detected race prints the conflicting read/write stacks and goroutine creation sites to stderr (WARNING: DATA RACE); fix by protecting every access to the address with the same primitive (mutex, atomic, or channel hand-off).

GORACE options

GORACE="log_path=/tmp/race/report halt_on_error=1 history_size=2" go test -race ./...

Stress with -count and -cpu

The detector only fires on races that actually execute; a single run can miss a real race. Amplify interleaving diversity:

go test -race -count=10 ./...          # 10 runs per package
go test -race -cpu=1,2,4,8 ./...       # re-run per GOMAXPROCS value
go test -race -count=5 -cpu=1,2,4 ./...

GOMAXPROCS=1 surfaces sequencing bugs; higher values surface true parallel races.

go vet - loop-variable capture

Per pkg.go.dev/cmd/vet (opens in new window) (loopclosure), go vet flags goroutines closing over a range variable - the classic pre-Go-1.22 capture race (for _, v := range items { go func() { process(v) }() }). Run go vet ./... before -race to filter this class early; Go 1.22+ makes range variables per-iteration, but audit code that may build on older toolchains.

goleak - goroutine-leak detection

Per github.com/uber-go/goleak (opens in new window) (go get -u go.uber.org/goleak):

func TestWorkerPool(t *testing.T) {
    defer goleak.VerifyNone(t)     // fails if any goroutine outlives the test
    pool := NewWorkerPool(4)
    pool.Submit(func() { /* work */ })
    pool.Shutdown()
}

VerifyNone is incompatible with t.Parallel() - goleak cannot attribute goroutines to parallel sub-tests. For parallel packages wrap the runner:

func TestMain(m *testing.M) { goleak.VerifyTestMain(m) }

Silence expected library goroutines by top-of-stack function:

goleak.VerifyNone(t, goleak.IgnoreTopFunction("database/sql.(*DB).connectionOpener"))

Full filter catalog (IgnoreAnyFunction, IgnoreCurrent, Cleanup) in goleak-filter-options.md (opens in new window).

CI matrix

Gate at least one matrix dimension with -race (per the race-detector doc: "It is recommended to always run race-enabled tests"):

jobs:
  test:
    strategy:
      matrix:
        go-version: ["1.22", "1.23"]
        race: ["", "-race"]
    steps:
      - uses: actions/setup-go@v5
        with: { go-version: "${{ matrix.go-version }}" }
      - env: { GORACE: "log_path=/tmp/race/report halt_on_error=0" }
        run: |
          go vet ./...
          go test ${{ matrix.race }} -count=3 -cpu=1,4 -timeout=10m ./...
      - if: failure()
        uses: actions/upload-artifact@v4
        with: { name: race-reports, path: /tmp/race/report* }

Set -timeout to 5-10x the non-race run time; upload log_path files on failure.

Anti-patterns

Limitations

• Cross-compiled binaries (GOOS/GOARCH differing from host) won't run -race unless the target toolchain supports TSan; CGO_ENABLED=0 builds exclude it entirely.
• goleak supports only the two most recent Go minor versions.
• goleak has a brief internal retry, but slow-starting background goroutines can false-positive; use IgnoreTopFunction.

References

• go.dev/doc/articles/race_detector (opens in new window) - -race, GORACE, report format, overhead, platforms
• github.com/uber-go/goleak (opens in new window) - goleak API
• pkg.go.dev/go.uber.org/goleak (opens in new window) - filter options

goleak filter options

Filter options for goleak.VerifyNone / goleak.VerifyTestMain, per pkg.go.dev/go.uber.org/goleak (opens in new window). Pass one or more as trailing arguments to suppress goroutines that are expected rather than leaked.

IgnoreTopFunction

Ignores any goroutine whose top-of-stack frame is the named function. Prefer this when the library goroutine is identifiable by name.

goleak.VerifyNone(t,
    goleak.IgnoreTopFunction("database/sql.(*DB).connectionOpener"),
)

IgnoreAnyFunction (v1.3.0+)

Ignores any goroutine whose stack contains the named function at any depth, not just the top frame. Use when the identifying frame is not at the top.

goleak.VerifyNone(t,
    goleak.IgnoreAnyFunction("google.golang.org/grpc.(*ccBalancerWrapper).watcher"),
)

IgnoreCurrent

Snapshots the goroutines already running at call time and ignores exactly those at verification.

opt := goleak.IgnoreCurrent()
// ... test logic ...
goleak.VerifyNone(t, opt)

Prefer IgnoreTopFunction over IgnoreCurrent when the library goroutine is identifiable by name: IgnoreCurrent silences goroutines that were already running at snapshot time, which can mask leaks introduced before the snapshot.

Cleanup

goleak.Cleanup(func(int)) registers a function goleak calls with the exit code after the leak check, e.g. to log instead of failing the process. Used with VerifyTestMain when the default exit behavior needs to change.

References

• pkg.go.dev/go.uber.org/goleak (opens in new window) - full API reference for IgnoreTopFunction, IgnoreAnyFunction, IgnoreCurrent, Cleanup