testing.md

Go testing

Read ../testing.md, baseline.md, and mise.md before applying these Go testing specifics.

Go defaults

  • Use go test -v -race -count=5 -p=3 -timeout=5m ./... in development tasks.
  • Set CGO_ENABLED=1 for race-enabled test tasks. Builds and releases can still use CGO_ENABLED=0 when dependencies allow it.
  • Table-driven tests are the default for pure functions and parsers.
  • Use t.Parallel() when the test does not mutate env, package globals, filesystem globals, terminal probes, or shared services.
  • Copy loop variables before parallel subtests when needed.
  • Use t.TempDir() and t.Setenv() for isolation.
  • Restore package globals with t.Cleanup().
  • Use httptest for HTTP clients/servers.
  • Prefer go-cmp for structured diffs.

Behaviour and BDD

When behaviour is still being discovered, use the BDD discovery skill first if available.

Do not add gocuke implicitly. Ask whether this project wants gocuke/BDD automation. If yes, load testing-with-gocuke-and-gherkin after behaviour is formulated. If no, use ordinary Go tests.

Good fits for gocuke:

  • config merge/precedence rules
  • interactive flow rules
  • non-interactive CLI behaviour
  • lifecycle rules with many examples

Keep step definitions grouped by domain concept, not by feature-file name. Let gocuke print missing step signatures instead of hand-guessing them.

Property tests

Use pgregory.net/rapid around:

  • parsers and serializers
  • path/config expansion
  • state machines
  • merge logic
  • sorting/ranking invariants

Keep properties small and name the invariant clearly.

TUI tests

Load golang-tui for Bubble Tea harnesses, snapshots, and terminal-specific test patterns. Keep the regular race-enabled Go test task from mise.md. Add snapshot/golden update tasks only when the project actually has snapshot tests.

Wails/frontend tests

Backend logic should remain testable without Wails. Frontend tests are useful for non-trivial state reducers, parsing, and rendering helpers; do not require a browser stack for simple static views unless the project already has one.