Go Testing Best Practices

This skill provides actionable testing guidelines. For detailed implementation patterns, code examples, rationale, and production system references, consult go-testing-best-practices.md .

When Working with Go Tests

Always apply these current best practices:

1. Test Organisation

• Place test files alongside source code using *_test.go naming

• Use internal tests (same package) for unit testing unexported functions

• Use external tests (package foo_test ) for integration testing and examples

• Split test files by functionality when they exceed 500-800 lines (e.g., handler_auth_test.go , handler_validation_test.go )

2. Table-Driven Testing

• Prefer map-based tables over slice-based for automatic unique test names

• Use descriptive test case names that appear in failure output

• See detailed guide for complete pattern and examples

3. Concurrent Testing

• Use testing/synctest for deterministic concurrent testing (Go 1.24+)

• This eliminates flaky time-based tests and runs in microseconds instead of seconds

• For traditional parallel tests, always call t.Parallel() first in test functions

4. Assertions and Comparisons

• Use cmp.Diff() from google/go-cmp for complex comparisons

• Standard library is sufficient for simple tests

• Testify is the dominant third-party framework when richer assertions are needed

5. Mocking and Test Doubles

• Favour integration testing with real dependencies over heavy mocking

• Use Testcontainers for database/service integration tests

• When mocking is necessary, prefer simple function-based test doubles over code generation

• Use interface-based design ("accept interfaces, return structs")

6. Coverage Targets

• Aim for 70-80% coverage as a practical target

• Focus on meaningful tests over percentage metrics

• Use go test -cover and go tool cover -html for analysis

7. Test Fixtures

• Use testdata directory for test fixtures (automatically ignored by Go toolchain)

• Implement golden file testing for validating complex output

• Use functional builder patterns for complex test data

8. Helpers and Cleanup

• Always mark helper functions with t.Helper() for accurate error reporting

• Use t.Cleanup() for resource cleanup (superior to defer in tests)

9. Benchmarking (Go 1.24+)

• Use B.Loop() method as the preferred pattern (prevents compiler optimisations)

• Combine with benchstat for statistical analysis

• Use -benchmem for memory profiling

10. Naming Conventions

• Test functions: Test* , Benchmark* , Fuzz* , Example* (capital letter after prefix)

• Use got and want for actual vs expected values

• Use descriptive test case names in table-driven tests

Integration vs Unit Testing

• Separate tests by environment variable (preferred over build tags)

• See detailed guide for implementation pattern

Additional Reference Material

Load go-testing-best-practices.md when you need:

• Complete code examples for table-driven tests, mocking patterns, golden files, helpers, or benchmarks

• Detailed explanation of testing/synctest concurrent testing patterns

• Rationale behind why specific patterns are preferred over alternatives

• Production system examples and statistics (Kubernetes, Docker, Uber, Netflix, ByteDance)

• Context on testing framework choices (Testify, GoMock, Testcontainers)

• Comprehensive coverage strategies and tooling details

• Integration testing patterns with containerisation

The detailed guide contains full context, examples with explanations, and production-proven patterns. This SKILL.md provides the actionable rules to apply.

Key Principle

Focus on meaningful tests that validate behaviour rather than implementation. Pragmatic excellence over theoretical perfection.