Golang Testing

---
name: golang-testing
description: Write unit tests with table-driven patterns and interface mocking in Go. Use when writing Go unit tests, table-driven tests, or using mock interfaces.
metadata:
  triggers:
    files:
    - '**/*_test.go'
    keywords:
    - testing
    - unit tests
    - go test
    - mocking
    - testify
---
# Golang Testing

## **Priority: P0 (CRITICAL)**

## Implementation Workflow

1. **Write failing test first** — Follow Red-Green-Refactor TDD workflow.
2. **Use table-driven tests** — Define test cases as slice of structs; iterate with `t.Run()`.
3. **Zero Volatile Fields for Struct Comparison** — When asserting struct equality, zero out timestamps, dynamic IDs, or generated tokens before `assert.Equal` to prevent flaky assertions.
4. **Mock via interfaces** — Use DI and interfaces. Prefer `mockery` for auto-generated mocks or manual mocks for simple cases.
5. **Run parallel** — Use `t.Parallel()` for non-sequential tests to speed up CI.
6. **Clean up resources** — Use `t.Cleanup()` to restore state or release DB/file resources.
7. **Check coverage** — Aim for >80% line coverage. Run `go test -cover` to audit.

See [table-driven test examples](references/table-driven-tests.md)

## Tools

- **Stdlib**: `testing` package usually enough.
- **Testify**: Assertions (`assert`, `require`) and mocks.
- **Mockery**: Auto-generate mocks for interfaces.
- **GoMock**: Popular mocking framework alternative.

## Naming

- Test file: `*_test.go`
- Test function: `func TestName(t *testing.T)`
- Example function: `func ExampleName()`

## Anti-Patterns

- **No assert in loops**: use `t.Run` subtests to isolate failures.
- **No brittle assertions on volatile fields**: avoid matching exact timestamps or non-deterministic IDs without normalization.
- **No global mock state**: define mocks locally within test scope.
- **No skipping race detection**: always run `go test -race` in CI.

## References

- [Table-Driven Tests](references/table-driven-tests.md)
- [Mocking Strategies](references/mocking-strategies.md)