Provides a comprehensive guide for writing production-ready Golang tests. Covers table-driven tests, test suites with testify, mocks, unit tests, integration tests, benchmarks, code coverage, parallel tests, fuzzing, fixtures, goroutine leak detection with goleak, snapshot testing, memory leaks, CI with GitHub Actions, and idiomatic naming conventions. Use this whenever writing tests, asking about testing patterns or setting up CI for Go projects. Essential for ANY test-related conversation in Go.
Provides a comprehensive guide for writing production-ready Golang tests. Covers table-driven tests, test suites with testify, mocks, unit tests, integration tests, benchmarks, code coverage, parallel tests, fuzzing, fixtures, goroutine leak detection with goleak, snapshot testing, memory leaks, CI with GitHub Actions, and idiomatic naming conventions. Use this whenever writing tests, asking about testing patterns or setting up CI for Go projects. Essential for ANY test-related conversation in Go.
user-invocable
true
license
MIT
compatibility
Designed for Claude Code or similar AI coding agents, and for projects using Golang.
Persona: You are a Go engineer who treats tests as executable specifications. You write tests to constrain behavior, not to hit coverage targets.
Thinking mode: Use ultrathink for test strategy design and failure analysis. Shallow reasoning misses edge cases and produces brittle tests that pass today but break tomorrow.
Modes:
Write mode — generating new tests for existing or new code. Work sequentially through the code under test; use gotests to scaffold table-driven tests, then enrich with edge cases and error paths.
Review mode — reviewing a PR's test changes. Focus on the diff: check coverage of new behaviour, assertion quality, table-driven structure, and absence of flakiness patterns. Sequential.
Audit mode — auditing an existing test suite for gaps, flakiness, or bad patterns (order-dependent tests, missing t.Parallel(), implementation-detail coupling). Launch up to 3 parallel sub-agents split by concern: (1) unit test quality and coverage gaps, (2) integration test isolation and build tags, (3) goroutine leaks and race conditions.
Debug mode — a test is failing or flaky. Work sequentially: reproduce reliably, isolate the failing assertion, trace the root cause in production code or test setup.
Community default. A company skill that explicitly supersedes samber/cc-skills-golang@golang-testing skill takes precedence.
Go Testing Best Practices
This skill guides the creation of production-ready tests for Go applications. Follow these principles to write maintainable, fast, and reliable tests.
Best Practices Summary
Table-driven tests MUST use named subtests -- every test case needs a name field passed to t.Run
Integration tests MUST use build tags (//go:build integration) to separate from unit tests
Tests MUST NOT depend on execution order -- each test MUST be independently runnable
Independent tests SHOULD use t.Parallel() when possible
NEVER test implementation details -- test observable behavior and public API contracts
Packages with goroutines SHOULD use goleak.VerifyTestMain in TestMain to detect goroutine leaks
Use testify as helpers, not a replacement for standard library
Mock interfaces, not concrete types
Keep unit tests fast (< 1ms), use build tags for integration tests
Run tests with race detection in CI
Include examples as executable documentation
Test Structure and Organization
File Conventions
// package_test.go - tests in same package (white-box, access unexported)package mypackage
// mypackage_test.go - tests in test package (black-box, public API only)package mypackage_test
Unit tests should be fast (< 1ms), isolated (no external dependencies), and deterministic.
Testing HTTP Handlers
Use httptest for handler tests with table-driven patterns. See HTTP Testing for examples with request/response bodies, query parameters, headers, and status code assertions.
Goroutine Leak Detection with goleak
Use go.uber.org/goleak to detect leaking goroutines, especially for concurrent code:
testing/synctest for Deterministic Goroutine Testing
Experimental:testing/synctest is not yet covered by Go's compatibility guarantee. Its API may change in future releases. For stable alternatives, use clockwork (see Mocking).
testing/synctest (Go 1.24+) provides deterministic time for concurrent code testing. Time advances only when all goroutines are blocked, making ordering predictable.
When to use synctest instead of real time:
Testing concurrent code with time-based operations (time.Sleep, time.After, time.Ticker)
time.Sleep advances synthetic time instantly when the goroutine blocks
time.After fires when synthetic time reaches the duration
All goroutines run to blocking points before time advances
Test execution is deterministic and repeatable
Test Timeouts
For tests that may hang, use a timeout helper that panics with caller location. See Helpers.
Benchmarks
→ See samber/cc-skills-golang@golang-benchmark skill for advanced benchmarking: b.Loop() (Go 1.24+), benchstat, profiling from benchmarks, and CI regression detection.
Write benchmarks to measure performance and detect regressions:
funcBenchmarkStringConcatenation(b *testing.B) {
b.Run("plus-operator", func(b *testing.B) {
for i := 0; i < b.N; i++ {
result := "a" + "b" + "c"
_ = result
}
})
b.Run("strings.Builder", func(b *testing.B) {
for i := 0; i < b.N; i++ {
var builder strings.Builder
builder.WriteString("a")
builder.WriteString("b")
builder.WriteString("c")
_ = builder.String()
}
})
}
Benchmarks with different input sizes:
funcBenchmarkFibonacci(b *testing.B) {
sizes := []int{10, 20, 30}
for _, size := range sizes {
b.Run(fmt.Sprintf("n=%d", size), func(b *testing.B) {
b.ReportAllocs()
for i := 0; i < b.N; i++ {
Fibonacci(size)
}
})
}
}
Parallel Tests
Use t.Parallel() to run tests concurrently:
funcTestParallelOperations(t *testing.T) {
tests := []struct {
name string
data []byte
}{
{"small data", make([]byte, 1024)},
{"medium data", make([]byte, 1024*1024)},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
t.Parallel()
is := assert.New(t)
result := Process(tt.data)
is.NotNil(result)
})
}
}
# Generate coverage file
go test -coverprofile=coverage.out ./...
# View coverage in HTML
go tool cover -html=coverage.out
# Coverage by function
go tool cover -func=coverage.out
# Total coverage percentage
go tool cover -func=coverage.out | grep total
Integration Tests
Use build tags to separate integration tests from unit tests:
//go:build integrationpackage mypackage
funcTestDatabaseIntegration(t *testing.T) {
db, err := sql.Open("postgres", os.Getenv("DATABASE_URL"))
if err != nil {
t.Fatal(err)
}
defer db.Close()
// Test real database operations
}
Run integration tests separately:
go test -tags=integration ./...
For Docker Compose fixtures, SQL schemas, and integration test suites, see Integration Testing.
Mocking
Mock interfaces, not concrete types. Define interfaces where consumed, then create mock implementations.
For mock patterns, test fixtures, and time mocking, see Mocking.
Enforce with Linters
Many test best practices are enforced automatically by linters: thelper, paralleltest, testifylint. See the samber/cc-skills-golang@golang-lint skill for configuration and usage.
Cross-References
-> See samber/cc-skills-golang@golang-stretchr-testify skill for detailed testify API (assert, require, mock, suite)
-> See samber/cc-skills-golang@golang-database skill (testing.md) for database integration test patterns
-> See samber/cc-skills-golang@golang-concurrency skill for goroutine leak detection with goleak
-> See samber/cc-skills-golang@golang-continuous-integration skill for CI test configuration and GitHub Actions workflows
-> See samber/cc-skills-golang@golang-lint skill for testifylint and paralleltest configuration
Quick Reference
go test ./... # all tests
go test -run TestName ./... # specific test by exact name
go test -run TestName/subtest ./... # subtests within a test
go test -run 'Test(Add|Sub)' ./... # multiple tests (regexp OR)
go test -run 'Test[A-Z]' ./... # tests starting with capital letter
go test -run 'TestUser.*' ./... # tests matching prefix
go test -run '.*Validation.*' ./... # tests containing substring
go test -run TestName/. ./... # all subtests of TestName
go test -run '/(unit|integration)' ./... # filter by subtest name
go test -race ./... # race detection
go test -cover ./... # coverage summary
go test -bench=. -benchmem ./... # benchmarks
go test -fuzz=FuzzName ./... # fuzzing
go test -tags=integration ./... # integration tests
