diff options
| author | Craig Jennings <c@cjennings.net> | 2026-06-02 18:22:11 -0500 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-06-02 18:22:11 -0500 |
| commit | 3a06aff7eec20814f6b51b72691f4140668189c2 (patch) | |
| tree | 0dcfde239685ebeabea3ce941317f1dac5be8349 /languages/go/claude/rules/go-testing.md | |
| parent | 0b07c15fb33ceaeec484dec9889c37098ec2e844 (diff) | |
| download | rulesets-3a06aff7eec20814f6b51b72691f4140668189c2.tar.gz rulesets-3a06aff7eec20814f6b51b72691f4140668189c2.zip | |
feat(go): build out the full Go language bundle
The Go bundle was coverage-slice-only. Because it shipped no rule files, sync-language-bundle.sh (which fingerprints a project's bundle by spotting one of its rule files in .claude/rules/) couldn't detect it, so the coverage slice it did ship never stayed in sync. Adding the rules is what makes the bundle sync-maintainable, which was the point.
Brought Go to the full tier, matching elisp:
- claude/rules/go.md and go-testing.md, the style and testing rules (table-driven tests, go test -race, errors.Is over message matching, how the coverage slice fits). These two are also the sync fingerprint.
- claude/hooks/validate-go.sh, a PostToolUse hook that runs gofmt and go vet on each edited .go file. go vet type-checks, so compile and syntax errors surface at edit time. It deliberately doesn't auto-run tests, since a package's tests can be slow or integration-tagged and shouldn't fire on every keystroke.
- claude/settings.json, Go permissions plus the hook wiring.
- githooks/pre-commit, a secret scan and a gofmt check on staged .go.
- CLAUDE.md, the seed.
validate-go.sh is TDD'd by scripts/tests/validate-go.bats: a clean file passes, gofmt and vet failures both block with the JSON payload, and non-go, missing, or empty paths are ignored. I updated install-lang.bats test 7, which asserted Go installs no CLAUDE.md, to check the full bundle instead. Verified with a real install into a throwaway project and a green make test.
Diffstat (limited to 'languages/go/claude/rules/go-testing.md')
| -rw-r--r-- | languages/go/claude/rules/go-testing.md | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/languages/go/claude/rules/go-testing.md b/languages/go/claude/rules/go-testing.md new file mode 100644 index 0000000..3b20efc --- /dev/null +++ b/languages/go/claude/rules/go-testing.md @@ -0,0 +1,166 @@ +# Go Testing Rules + +Applies to: `**/*_test.go` + +Implements the core principles from `testing.md`. All rules there apply here — +this file covers Go-specific patterns. + +## Framework: the standard `testing` package + +Use the standard library `testing` package. Reach for a third-party assertion +library (`testify`) only when a project already uses it; don't introduce it for +new code. Plain `if got != want { t.Errorf(...) }` is the idiom, and it keeps +the failure message under your control. + +Avoid full BDD frameworks (Ginkgo/Gomega) unless the project standardizes on +them — they obscure the standard `go test` failure output. + +## Table-Driven Tests Are the Default + +A table-driven test is how Go expresses the Normal / Boundary / Error +categories from `testing.md` in one place. Each row is a case; `t.Run` gives +each a named subtest so a failure points at the exact row. + +```go +func TestCartApplyDiscount(t *testing.T) { + tests := []struct { + name string + coupon string + want int + wantErr bool + }{ + {"normal percentage off", "SAVE10", 90, false}, // Normal + {"zero discount is a no-op", "SAVE0", 100, false}, // Boundary + {"expired coupon rejected", "EXPIRED", 0, true}, // Error + } + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got, err := ApplyDiscount(100, tt.coupon) + if (err != nil) != tt.wantErr { + t.Fatalf("ApplyDiscount() err = %v, wantErr = %v", err, tt.wantErr) + } + if !tt.wantErr && got != tt.want { + t.Errorf("ApplyDiscount() = %d, want %d", got, tt.want) + } + }) + } +} +``` + +Use `t.Errorf` to record a failure and keep going (multiple assertions per +case); use `t.Fatalf` when continuing would panic or test nothing useful (a +`nil` you're about to dereference). + +### Pairwise for Parameter-Heavy Functions + +When the table would need dozens of rows to cover the combinations of three or +more parameters (feature flags × roles × shipping × payment), switch to +combinatorial coverage via `/pairwise-tests`. It generates a minimal matrix +hitting every 2-way interaction — usually 80-99% fewer rows than exhaustive — +which you paste straight back into the table. See `testing.md` § Combinatorial +Coverage for when to skip. + +## Run With the Race Detector + +Run the suite with `-race` for anything that touches goroutines, channels, or +shared state. The race detector catches data races that are invisible in a +plain run and flaky in production. + +``` +go test -race ./... +``` + +Wire `-race` into the project's `make test`. A passing race-free run is the bar +for concurrent code, not an optional extra. + +## Test Naming and Location + +- Tests live in `<file>_test.go` beside the code, in the same package + (`package foo`) for white-box tests, or `package foo_test` for black-box + tests that exercise only the exported API. Prefer black-box (`foo_test`) when + you're testing the contract; it keeps tests honest about what's public. +- Top-level test functions: `TestThing`, scenario carried by the subtest name + via `t.Run("expired coupon rejected", ...)`. +- Use `testing.T.Parallel()` on independent subtests to surface ordering + assumptions and speed the suite. Capture the range variable first + (`tt := tt`) on Go versions before 1.22. + +## Error Behavior, Not Error Text + +Assert the error's identity, not its prose. Production messages get reworded; +behavior doesn't. + +```go +got := Withdraw(account, 999) +if !errors.Is(got, ErrInsufficientFunds) { + t.Errorf("Withdraw() error = %v, want ErrInsufficientFunds", got) +} +``` + +Use `errors.Is` for sentinel errors and `errors.As` for typed errors. Match on +a substring only when a specific value must appear (the offending filename), +never on the whole message. This mirrors `testing.md`'s error-behavior rule. + +## Fixtures: `testdata/` and Golden Files + +- Put fixture inputs in a `testdata/` directory — the Go tool ignores it for + builds, and it travels with the package. +- For large expected outputs, use the golden-file pattern: compare against + `testdata/<name>.golden` and regenerate with a `-update` flag. + +```go +var update = flag.Bool("update", false, "update golden files") +// ... if *update { os.WriteFile(golden, got, 0o644) } +``` + +- Use `t.TempDir()` for scratch directories and `t.Cleanup()` for teardown; + both are removed automatically and survive `t.Parallel()`. + +## Mocking at Boundaries — Via Interfaces + +Go's interfaces are the seam. Define a small interface the code under test +depends on, and pass a fake in the test. Don't mock concrete types you own. + +### Mock these (external boundaries): +- Network: use `net/http/httptest.Server` for HTTP clients, not a mocked + `http.Client` transport you hand-build. +- Time: inject a `func() time.Time` clock rather than calling `time.Now()` + directly in business logic. +- Filesystem: accept an `fs.FS` (or `io.Reader`/`io.Writer`) so a test can pass + `fstest.MapFS` or a buffer. +- Third-party service clients: depend on a narrow interface the package + defines, not the vendor's concrete client. + +### Never mock these (internal domain): +- Concrete structs and methods you own — call them directly with real inputs. +- Pure functions (parsing, encoding, calculation) — those are the work. +- The standard library's own behavior. + +If a test needs an elaborate fake to stand in for your own code, that's a +design signal: extract a smaller interface or split the function (see +`testing.md` § If Tests Are Hard to Write). + +## Measuring Coverage — `make coverage-summary` + +The bundle ships a coverage summary at `.claude/scripts/coverage-summary.go` +plus a Makefile fragment (`coverage-makefile.txt`) with `coverage` and +`coverage-summary` targets. After `make coverage` runs the suite with +`-coverprofile` and prints `go tool cover -func`'s per-function table, `make +coverage-summary` prints a file-weighted project number and every source file +absent from the profile. + +The number to watch is that missing-file count. `go test ./...` lists in-module +packages in the profile (at 0% when untested), so the missing list is usually +empty for in-module code — it earns its keep on build-tagged files and dirs +outside the `./...` compilation. The summary weights by file and counts an +absent file as 0%, so untested code stays visible instead of being averaged +away. It doesn't reimplement the per-function table — `go tool cover -func` +already prints that. Copy the fragment's targets into your own Makefile to +adopt it; the bundle never edits your Makefile. + +## What the Validate Hook Already Enforces + +A PostToolUse hook runs `gofmt` and `go vet` on every edited `.go` file (see +the bundle's `CLAUDE.md`). Formatting and compile errors are caught at edit +time, so tests don't need to re-assert them — write tests for behavior, not for +"it compiles." |
