Go Testing & Benchmark Skill

Table-driven test and fuzz scaffolding for agents - a cookbook-style Agent Skill for Go 1.26 test generation from acceptance criteria.

What This Skill Does

Produces test scaffolds: table-driven t.Run subtests, httptest handler cases, fuzz F.Add seeds, and benchmark stubs - with go test verification commands, not production code rewrites.

When to Invoke

• Agent asked to "add tests" without structure
• New package needs table-driven coverage from AC bullets
• Fuzz target needed for string/JSON parsers
• Benchmark stub before perf work (pairs with Go Performance Profiling Skill)
• PR lacks subtests for error branches

Inputs

Outputs

• *_test.go scaffold with table slice and subtests
• Optional FuzzXxx with corpus seeds
• Optional BenchmarkXxx with b.Loop (Go 1.24+ style) or classic loop
• Commands: go test ./pkg/..., go test -race, go test -fuzz=FuzzParse -fuzztime=30s

Guardrails

1. Test behavior, not unexported helpers unless same-package white-box policy allows.
2. No time.Sleep for synchronization - use channels, synctest, or interfaces.
3. Parallel subtests only when isolated - t.Parallel() documented per case.
4. Fuzz only pure parsers - no network/DB in fuzz target without heavy setup.
5. Run tests before delivering scaffold - must compile.
6. Golden files - update with explicit -update flag pattern per team policy.

Recipe

Quick-reference recipe card - copy-paste ready.

func TestParseID(t *testing.T) {
    tests := []struct {
        name    string
        in      string
        want    string
        wantErr bool
    }{
        {name: "valid", in: "abc-123", want: "abc-123"},
        {name: "empty", in: "", wantErr: true},
        {name: "spaces", in: "  ", wantErr: true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := ParseID(tt.in)
            if tt.wantErr {
                if err == nil {
                    t.Fatal("expected error")
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected: %v", err)
            }
            if got != tt.want {
                t.Fatalf("got %q want %q", got, tt.want)
            }
        })
    }
}

go test ./internal/parse/... -count=1
go test -race ./internal/parse/...   # if package uses goroutines

When to reach for this skill:

• PM AC list needs mapped subtests before merge
• Agent produced one giant TestEverything function
• Parser package needs fuzz before security review

Working Example

Step 0 - Map AC to cases

AC:
- Valid UUID returns normalized form
- Invalid UUID returns ErrInvalid
- Empty input returns ErrEmpty

Each bullet becomes t.Run name and table row.

Step 1 - Handler test with httptest

func TestGetUserHandler(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(getUser))
    t.Cleanup(srv.Close)
 
    resp, err := http.Get(srv.URL + "/users/1")
    if err != nil {
        t.Fatal(err)
    }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        t.Fatalf("status %d", resp.StatusCode)
    }
}

• Prefer testing handler via httptest.NewRecorder for unit scope
• See httptest for Handler Integration Tests

Step 2 - Fuzz scaffold

func FuzzParseID(f *testing.F) {
    f.Add("abc-123")
    f.Add("")
    f.Fuzz(func(t *testing.T, in string) {
        _, _ = ParseID(in) // must not panic; document invariants
    })
}

go test -fuzz=FuzzParseID -fuzztime=30s ./internal/parse/

Step 3 - Benchmark stub

func BenchmarkParseID(b *testing.B) {
    for b.Loop() {
        _, _ = ParseID("abc-123")
    }
}

go test -bench=BenchmarkParseID -benchmem ./internal/parse/ -count=5

Deep Dive

** testify / cmp**: if team uses github.com/stretchr/testify, skill imports require per ADR.

Otherwise stdlib-only assertions keep deps minimal.

Examples (ExampleXxx): for godoc-verified snippets - see Examples as Executable Documentation.

Coverage: go test -cover ./... for report; skill does not chase 100% on generated scaffold.

Build tags: integration tests behind //go:build integration - skill separates fast unit table from slow IT.

Gotchas

• Subtest name with / breaks -run regex - use safe names.
• Loop variable in parallel subtests - capture tt := tt before t.Parallel().
• Fuzz on functions that mutate global state - isolate or skip fuzz.
• Benchmark without resetting input - skews alloc measurements.

Alternatives

FAQs

Related

• Agent Skills Basics - SKILL.md structure
• Go Testing Basics - testing intro
• Table-Driven Tests and Subtests - patterns
• Fuzz Testing with testing.F - fuzz reference
• Benchmarks with testing.B and b.Loop - benchmarks
• testify, httptest, and Test Doubles - doubles

Stack versions: This page was written for Go 1.26.x (Green Tea GC default, go fix modernizers - verify patch at build), chi (latest - verify at build), gin (latest - verify at build), echo (latest - verify at build), google.golang.org/grpc (latest - verify at build), sigs.k8s.io/controller-runtime (latest - verify at build), kubebuilder (latest - verify at build), tinygo (latest - verify board targets at build), wazero (latest - verify at build), and golangci-lint (latest - verify linter set at build).