go test -run: Filter Tests by Regex in CI
go test -run <regex> runs only the tests whose names match the regular expression; subtests are matched by joining names with a slash.
In CI you sometimes want to rerun one failing test or split a suite. -run filters by name, and -count=1 forces a fresh run past the test result cache.
What it does
go test -run takes an unanchored regular expression matched against test function names. For subtests, the pattern is split on / so -run TestX/case_a targets a specific subtest. -count=1 disables result caching so the tests actually re-execute.
Common usage
go test -run TestLogin ./...
go test -run 'TestParse/(valid|empty)' -v ./internal/parse
go test -run TestFlaky -count=1 ./... # bypass the cache
go test -run '^$' -bench=. ./... # benches only, no testsFlags
| Flag | What it does |
|---|---|
| -run <regex> | Run only tests matching the (unanchored) regex |
| -count=1 | Disable test caching; force re-run |
| -v | Verbose: print each test name and result |
| -skip <regex> | Skip tests matching the regex (Go 1.20+) |
| -timeout <dur> | Fail the run if it exceeds the duration |
| -shuffle=on | Randomize test/order to catch order dependence |
In CI
Cache the Go build cache and module cache; note go test caches passing results, so a green rerun may be cached. Use -count=1 when you need a real execution. Anchor patterns with ^...$ to avoid accidentally matching more tests than intended.
Common errors in CI
"testing: warning: no tests to run" means the -run regex matched nothing (a typo or wrong subtest path). "cannot use -run with ..." rarely appears; more often a bad regex gives "error parsing regexp: missing closing ): ...". A suite that finishes instantly with no "ok" lines is usually -run filtering everything out.