Golang Testing

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.

Dependencies:

• gotests: go install github.com/cweill/gotests/gotests@latest

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

1. Table-driven tests MUST use named subtests -- every test case needs a name field passed to t.Run
2. Integration tests MUST use build tags (//go:build integration) to separate from unit tests
3. Tests MUST NOT depend on execution order -- each test MUST be independently runnable
4. Independent tests SHOULD use t.Parallel() when possible
5. NEVER test implementation details -- test observable behavior and public API contracts
6. Packages with goroutines SHOULD use goleak.VerifyTestMain in TestMain to detect goroutine leaks
7. Use testify as helpers, not a replacement for standard library
8. Mock interfaces, not concrete types
9. Keep unit tests fast ( 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
• -> See samber/cc-skills-golang@golang-continuous-integration skill for automated AI-driven code review in CI using these guidelines

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: samber
• Source: samber/cc-skills-golang
• License: MIT
• Homepage: https://skills.sh/samber/cc-skills-golang

Install and usage instructions live in the source repository linked above.