Cursor rule

1---
2description: 
3globs: *_test.go,**/*_test.go
4alwaysApply: false
5---
6# Go Test Best Practices
7 
8## Go Version
9- Use Go 1.24+ features in tests
10- Reference: @https://tip.golang.org/doc/go1.24
11- Key testing improvements:
12  - t.Cleanup() for test cleanup
13  - t.TempDir() for managing temp dirs
14  - t.Setenv() for scoped environment variables
15  - b.Loop() for benchmarks (Go 1.24)
16  - go test -fuzz for fuzzing
17  - go vet now detects test misuses (Go 1.24)
18 
19## Test Function Conventions
20- All test functions must follow correct naming and signature:
21  - Unit tests: `func TestXxx(t *testing.T)`
22  - Benchmarks: `func BenchmarkXxx(b *testing.B)`
23  - Fuzz tests: `func FuzzXxx(f *testing.F)`
24- Avoid misnamed or malformed test functions – go vet will catch these in Go 1.24+
25- Keep test functions short, focused, and readable
26 
27## Table-Driven Tests
28- Use table-driven style for variations of the same logic
29- Use subtests (`t.Run(name, func(t *testing.T))`) for each case
30- Always call `t.Parallel()` within subtests if test cases are independent
31- Prefer descriptive names in subtests for easier debugging
32 
33## Test Utilities and Cleanups
34- Use `t.Cleanup()` to register cleanup logic in tests
35- Use `t.TempDir()` instead of manual temp file management
36- Use `t.Setenv(key, value)` for setting env vars in test scope
37- Avoid manual cleanup with `defer os.Remove(...)` unless absolutely needed
38 
39## Benchmarking
40- Use `b.ReportAllocs()` to track memory allocations in benchmarks
41- Use `b.ResetTimer()` before measuring just-in-time workloads
42- Prefer `b.Loop()` over `for i := 0; i < b.N; i++` (Go 1.24+)
43- Keep benchmark logic minimal and representative
44 
45## Fuzzing (Go 1.18+)
46- Use `FuzzXxx(f *testing.F)` to test parsers and data consumers
47- Add seed inputs via `f.Add(...)` to initialize coverage
48- Fuzz tests should validate invariants and panic conditions
49- Always check and minimize corpus growth
50 
51## Assertions and Error Checks
52- Avoid panics in tests – use `t.Fatal`, `t.Error`, `t.Fatalf`, `t.Errorf`
53- Use table-driven want vs got comparisons
54- Clearly format failure messages: `t.Errorf("expected %v, got %v", want, got)`
55- Consider using helper functions to reduce repetitive checks
56 
57## Parallel Testing
58- Use `t.Parallel()` for top-level test functions where safe
59- Always use inside subtests when possible
60- Avoid global state mutation in parallel tests
61- Protect shared state with sync primitives if required
62 
63## Logging and Debugging
64- Use `t.Log` / `t.Logf` for test-local logs
65- Avoid `fmt.Println()` in tests – not tied to test output
66- Prefer structured test logs when debugging complex cases
67 
68## Temp Files & Directories
69- Use `t.TempDir()` for temp paths
70- Prefer `filepath.Join(t.TempDir(), "file.txt")` over hardcoded temp paths
71- Avoid manually cleaning up temp files – use Go's built-in cleanup
72 
73## Environment Handling
74- Use `t.Setenv()` for environment variable setup in tests
75- Avoid modifying `os.Setenv` directly unless cleaned up properly
76- Test behavior under different env configs using subtests
77 
78## Test Organization
79- Keep tests near the code they test (same package, _test.go file)
80- Group related tests together using sections or subtests
81- Use helper functions ending in _test.go to avoid export issues
82- Avoid logic in test files that is not directly test-related
83 
84## Linting & Vetting
85- Run go vet on all test files – especially with Go 1.24+ analyzers
86- Enable linters:
87  - testpackage: avoid logic in test files
88  - gocognit: test complexity
89  - errcheck: all errors must be checked
90  - staticcheck: catch subtle test issues
91- Use go test -race for all concurrent test suites
92 
93## Observability in Tests
94- Log context IDs or test metadata using t.Log for traceability
95- Capture test-specific logs and metrics via mocks or test sinks
96- Prefer context-aware testing when mocking services
97 
98## Using Testify
99 
100### Testify/Assert
101- Import with `import "github.com/stretchr/testify/assert"`
102- Use for readable test assertions: `assert.Equal(t, expected, actual, "optional message")`
103- Key assertion functions:
104  - `assert.Equal(t, expected, actual)` - Check for equality
105  - `assert.NotEqual(t, notExpected, actual)` - Check for inequality
106  - `assert.True(t, value)` / `assert.False(t, value)` - Check boolean values
107  - `assert.Nil(t, value)` / `assert.NotNil(t, value)` - Check for nil
108  - `assert.NoError(t, err)` / `assert.Error(t, err)` - Check error values
109  - `assert.Contains(t, collection, element)` - Check containment
110  - `assert.Subset(t, superSet, subSet)` - Check subset relationships
111- Use `require` instead of `assert` when test should abort on failure:
112  - `require.NoError(t, err)` - Test will abort if error is not nil
113  - Import with `import "github.com/stretchr/testify/require"`
114- Prefer assertion error messages that provide context:
115  - `assert.Equal(t, expected, actual, "should match after transformation")` 
116 
117### Testify/Mock
118- Import with `import "github.com/stretchr/testify/mock"`
119- Create mock structs that embed `mock.Mock`
120- Define expectations before running the function under test:
121  - `mockObj.On("MethodName", arg1, arg2).Return(returnVal1, returnVal2)`
122- Verify expectations after test with `mockObj.AssertExpectations(t)`
123- For specific call counts: `mockObj.On("MethodName", mock.Anything).Return(true).Times(3)`
124- Match any argument with `mock.Anything` or `mock.AnythingOfType("string")`
125- Use custom matchers with `mock.MatchedBy(func(arg Type) bool { ... })`
126- Capture arguments with `mock.On(...).Run(func(args mock.Arguments) { ... })`
127- Structure test with clear setup, execution, and assertion phases
128 
129### Testify Best Practices
130- Combine with table-driven tests for maximum readability
131- Avoid excessive mocking - mock only external dependencies
132- Use testify consistently across test suite for uniformity
133- For complex mock setup, use helper functions to improve readability
134- Consider using testify/suite for tests that share setup/teardown
135- Use `assert.Subset()` and `assert.ElementsMatch()` for collection comparison
136- For API testing, use testify with httptest package
137 
138## Modern Patterns to Prefer
139- ✅ Use `t.Parallel()` and `t.Run()` for better concurrency
140- ✅ Use `t.Cleanup()` over manual defer cleanup
141- ✅ Use `t.Setenv()` over os.Setenv
142- ✅ Use `b.Loop()` over manual for i := 0; i < b.N; i++
143- ✅ Use fuzzing for complex input functions
144- ✅ Always check errors explicitly, even in tests
145- ✅ Use testify/assert for clear test assertions
146- ✅ Use testify/mock for clean dependency mocking