Codegen Test Skill

Purpose

• •Lock down the spec (expected behavior) based on README.md / Issue and run Red → Green → Refactor.
• •Write idiomatic, readable, maintainable Go tests (table-driven, subtests, small helpers).
• •Avoid focusing only on branch coverage; also add boundary, black-box (behavior), and regression perspectives.
• •Do not make coverage the “goal.” Do not write tests that reduce maintainability.
• •Avoid mocks as much as possible; implement in a more classicist style.

When to use

• •When you want to write tests first for a feature, bug fix, or refactor.
• •When existing behavior is unclear and you want to build consensus (freeze the spec) via tests.
• •When you want to add regression tests to prevent recurrence.

Deliverables (expected output)

• •Tests that transition from failing → passing (Red → Green is observable)
• •Test code aligned with the project’s existing test style
• •Commands executed (go test / race / optionally bench) and brief result notes

Execution steps (follow this order)

0) Safety measures before changes

• •Tests become the spec (contract). Do not contradict README/Issue.
• •If existing tests act as the de-facto spec, prioritize and do not break them.
• •Start with the minimum necessary tests, then incrementally add perspectives as needed.

1) Understand the spec (README.md / Issue)

• •From README.md / docs / comments / Issue, finalize acceptance criteria (expected behavior) as bullet points.
• •Break them down (ideally usable as test case names):
  • •Representative happy-path cases
  • •Error cases (invalid input, broken preconditions, dependency failures)
  • •Boundary values (empty, 0, min/max, off-by-one)
  • •Concurrency (simultaneous execution, ordering, shared state)
  • •Compatibility (preserve past behavior, regression prevention)

2) Follow existing test conventions (highest priority)

• •Do not introduce additional external modules.
• •Search existing _test.go files and match the following:
  • •Package style (package x vs package x_test)
  • •Assertion approach (stdlib testing vs an existing assertion library already used)
  • •Table-driven style (tests / tt, field naming patterns)
  • •Helper locations, naming, fixture patterns
  • •Test data layout (whether testdata/ exists)

This skill is not about imposing new rules; it prioritizes matching the existing conventions.

3) Test design principles

• •Prefer black-box testing (behavior of the public API).
• •Do not directly test implementation details (private functions/internal state).
  • •Exception: Only when “hard to observe from the outside” requirements matter (e.g., performance or race-safety), and only with minimal supplemental tests.
• •Do not write trivial tests (e.g., “assert the type”).

4) Use table-driven tests as the default shape

• •If multiple conditions exercise the same logic, use a table-driven test.
• •Recommended structure:
  • •tests := []struct{ name string; input ...; want ... }{ ... }
  • •for _, tt := range tests { t.Run(tt.name, func(t *testing.T) { ... }) }
• •Prefer input / want prefixes for field names.
• •Do not stuff functions or complex branching (e.g., shouldX, setupMocks func...) into the table.
  • •If it becomes complex, split the table or split the test function.

5) Balance branch coverage (white-box) with behavior/boundaries (black-box)

• •Branch coverage: ensure each if/switch branch is exercised at least once.
• •Boundaries: add empty/min/max and just-before/just-after cases (off-by-one).
• •Behavior: include “what must be guaranteed” in the test name so it’s understandable to readers.

6) Avoid mocks as much as possible (classicist)

• •Principle: use something “close to real.”
  • •Examples: in-memory implementations, bytes.Buffer, httptest, t.TempDir(), net.Pipe()
• •Do not over-introduce interfaces (often harms design and maintainability).
• •If external dependencies must be cut, swap them at the smallest boundary.
  • •If large mock setups are required, prefer splitting the unit under test into smaller components.

7) Concurrency tests (only when needed, carefully)

• •Make race-prone areas verifiable with -race.
• •If using t.Parallel(), always rebind loop variables:
  • •Do tt := tt immediately before t.Run to avoid capture bugs.
• •For concurrent cases, explicitly state what is being guaranteed (no races, ordering, idempotency, etc.).

8) Run and verify (required)

• •Run package-level (or full) tests including race checks:
  • •task go:test
• •If performance is a key concern, add/run benchmarks (only when necessary):
  • •task go:bench

Prohibited (do not do)

• •Tests that are hard to read/brittle written only to raise coverage
• •Complex branching inside table-driven tests or excessive flags (hurts maintainability)
• •Tests tightly coupled to implementation details (not refactor-friendly)
• •Unnecessary interfaces or heavy reliance on mocks

Final report about test code and approach (keep it short)

• •Output as a Markdown report:
  • •Filename: <issue_number>_<datetime>_test_report.md
• •Include:
  • •Spec summary (acceptance criteria from README/Issue)
  • •Added test perspectives (branches/boundaries/behavior/regression/concurrency)
  • •Commands executed (test / race / bench)
  • •Reasons for tests intentionally not written (e.g., avoiding excessive mocks), if needed