Testing Standards

Philosophy

Tests are verification infrastructure, not checkboxes. They protect against regressions, document expected behavior, and surface real issues for human evaluation.

Comprehensive, not exhaustive. Cover meaningful scenarios without combinatorial explosion.

Pre-Flight Checklist

Before writing any test, answer:

1. What is the contract? (inputs → outputs, side effects, errors)
2. What are the boundaries? (empty, nil, zero, max, negative)
3. What can go wrong? (every error return path)
4. What state does it depend on? (filesystem, env vars, time)
5. Is there concurrency? (goroutines, shared state)

Write tests for #2 and #3 FIRST. Edge cases and errors catch real bugs.

Go Test Essentials

func TestFoo(t *testing.T) {
    t.Parallel()           // Unless shared state
    dir := t.TempDir()     // Auto-cleanup, not os.MkdirTemp
    t.Setenv("KEY", "val") // Auto-restore, prevents t.Parallel() misuse
}

func helper(t *testing.T) {
    t.Helper()  // REQUIRED - fixes line numbers in failures
}

Error assertions:

if !errors.Is(err, ErrNotFound) { ... }      // Sentinel errors
if !errors.As(err, &pathErr) { ... }         // Wrapped errors
if !strings.Contains(err.Error(), "x") {...} // Message matching

Table-Driven Tests

func TestCharge(t *testing.T) {
    tests := []struct {
        name    string
        card    Card   // GIVEN
        amount  int64  // GIVEN
        wantErr error  // THEN
    }{
        {"expired card", Card{Expiry: past}, 100, ErrExpired},
        {"valid card", Card{Expiry: future}, 100, nil},
        {"negative amount", Card{}, -1, ErrInvalidAmount},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            _, err := svc.Charge(tt.card, tt.amount)  // WHEN
            if !errors.Is(err, tt.wantErr) {
                t.Errorf("got %v, want %v", err, tt.wantErr)
            }
        })
    }
}

Coverage Requirements

If a function returns an error, test that it returns the right error.

Real-World Test Data

Tests must reflect production reality:

User{Name: "test"}

User{Name: "María García-López"}

Mocks are a last resort. Prefer interfaces with test implementations or recorded fixtures.

Test Integrity Rules

❌ FORBIDDEN: Changing assertions to match broken behavior
❌ FORBIDDEN: Deleting tests that "don't work anymore"
❌ FORBIDDEN: Adding t.Skip() without justification
✅ REQUIRED: Escalate unexpected failures for evaluation

Tests may fix implementation only when:

1. Test reveals a legitimate bug (doesn't match documented contract)
2. Fix is isolated to the defect (no scope creep)

Escalate when: Multiple tests fail, architectural issue suspected, or fix requires API changes.

Anti-Patterns

time.Sleep

os.Chdir

t.Helper()

os.MkdirTemp

t.TempDir()

Organization

pkg/service/
├── service.go
├── service_test.go       # Unit tests
└── service_int_test.go   # //go:build integration
internal/testutil/        # Shared helpers

Always run:

go test -race ./...