unit-test

Go Unit Test

Create and refine Go tests for this repository with table-driven cases and explicit bug-hunting rules.

Quick Reference

Hard Rules

• Name test files as <target_file>_test.go, co-located with source.
• Assertion strategy (adapt to project):
  • If project uses testify: require for fatal preconditions, assert for value checks.
  • If project uses standard library only: use t.Fatalf for fatal preconditions, t.Errorf for value checks. Include got/want in messages: t.Errorf("Name = %q, want %q", got, want).
  • If project uses go-cmp: use cmp.Diff for deep struct comparison. Prefer over field-by-field assertion for complex output.
  • Detection: Check existing _test.go files for "github.com/stretchr/testify" imports. Follow project convention.
• Keep tests deterministic; isolate time, randomness, environment, and network.
  • Prefer t.Setenv for env changes; avoid leaking global state between tests. Note: t.Setenv panics under t.Parallel() (see Go Version Gate) — for a parallel subtest that needs env isolation, inject config explicitly instead of mutating the process environment.
• Prefer stable fakes/stubs over heavy mock chains.
  • Unit tests SHOULD NOT require real external services (DB/Redis/HTTP) unless explicitly requested; that belongs to integration tests.
• Do NOT test constructors (NewXxx) or private helpers unless explicitly requested OR they contain non-trivial logic (validation/defaulting/option-merging) that can break runtime invariants.
• For service-layer code with interfaces, focus on methods declared in the interface. For pure functions/handlers, focus on exported functions/endpoints.
• Run with the race detector (go test -race). Scope is the tested package set, not always ./...: PR mode narrows it to changed packages, and a Light pure-function target with no go/chan/sync may run -race on just that package rather than the whole repo. Precedence when the rules below disagree: race.required config > PR scope > mode default. race.required: false disables -race entirely (state it in the report); otherwise -race is required on every tested package.
• Killer Case hard constraint (Standard + Strict): each test target (interface method / exported function / handler endpoint) must include at least 1 "killer case" (fault-injection or boundary-kill case) that is expected to fail on a known bad mutation/path.
• In the report, for each killer case, name its critical assertion(s) and report Kill: Verified — you injected the named defect through go test -overlay (never by editing the source), re-ran the test, observed the FAIL, and quote the failure line — or Kill: Unverified plus why you could not run it. An unverified kill is a defect hypothesis, not a demonstrated result: never write it as one.
• Do NOT claim an assertion is indispensable unless you checked that separately. Injecting the defect shows the case catches it; only deleting the named assertion while the defect is still injected and seeing the test PASS shows that assertion is what catches it. Redundant assertions are normal — report Assertion necessity only when that removal check was actually run, never as a blanket statement. → recipe: references/killer-case-patterns.md § Verifying the Kill.