Golang TestingSAFE

A collection of Agent Skills Standard and Best Practice for Programming Languages, Frameworks that help our AI Agent follow best practies on frameworks and programming laguages

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
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)**

## Core Rule Anchors

- **`[BE-TEST-01]` Table-Driven Subtests for Equivalent Cases**: Prefer table-driven tests (`[]struct{ name, input, expected, expectErr }` with `t.Run`) when functions have multiple equivalent inputs, boundary permutations, or repetitive setup. Distinct scenarios or diverging setup may remain separate test functions; 2-3 distinct cases are fine. Reviewers must not raise stylistic table-driven findings without a behavioral gap.
- **`[BE-TEST-02]` Ban on Brittle SQLMock String Matching**: Do not use `sqlmock.ExpectQuery` to regex-match raw SQL strings. Test pure domain business calculations directly, or use `testcontainers-go` for PostgreSQL repository verification.
- **`[BE-TEST-03]` Ban on Shallow Assertions**: Never assert only `assert.NoError(t, err)` or `assert.NotNil(t, result)` without inspecting returned domain struct fields, status codes, and invariants.
- **`[BE-TEST-04]` Ban on Pass-Through Interface Mocks**: Repositories and service handlers must test contract compliance and error mapping. Ban 1:1 pass-through mock echoing without contract assertions.
- **`[BE-TEST-05]` Bug-First Regression Lock**: Every PR fixing a bug ticket or with title `fix(...)` must introduce a test reproducing the defect prior to the fix.

## Implementation Workflow

1. **Write failing test first** — Follow Red-Green-Refactor TDD workflow (`[BE-TEST-05]`).
2. **Table-driven tests for equivalent inputs** — For parameterized cases sharing setup, define test cases as a slice of structs with `t.Run` (`[BE-TEST-01]`).
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 small, consumer-centric interfaces (1-3 methods) (`[BE-TEST-04]`). 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** — Coverage is diagnostic and project-configured; verify risk-weighted critical paths rather than padding code for an arbitrary percentage.

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

## Tools & Naming

- **Stdlib**: `testing` package (`TestXxx(t *testing.T)`, `ExampleXxx()`).
- **Testify**: Assertions (`assert`, `require`) and mocks.
- **Mockery / GoMock**: Auto-generate mocks for interfaces.
- **Integration**: Prefer `testcontainers-go` over raw SQL mock strings (`[BE-TEST-02]`).

## Anti-Patterns

- **`[BE-TEST-01]` No stylistic rewrites**: Do not demand table-driven rewrites of passing tests unless 5+ repetitive blocks or a coverage gap exists.
- **`[BE-TEST-02]` No raw SQL regex matching**: Do not match SQL strings in mocks.
- **`[BE-TEST-03]` No shallow assertions**: Never assert only `assert.NoError`/`NotNil` without payload inspection.
- **`[BE-TEST-04]` No pass-through mock echoing**: Ban 1:1 mock echoing without contract assertions.
- **`[BE-TEST-05]` No bug fix without reproduction test**.
- **No assert in loops**: use `t.Run` subtests to isolate failures.
- **No brittle assertions on volatile fields**: normalize timestamps/dynamic IDs.
- **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)

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.