Writing Tests

Writing Tests

A useful test fails when behavior is wrong, passes when it is right, and explains the failure without a debugger. Follow repository instructions first.

Prove the behavior

• Choose the lowest layer that proves the contract: unit for local logic, integration for real boundaries, CLI/UI/E2E only for behavior unavailable below them.
• Exercise production code. Do not copy its logic into the test or mock the unit under test.
• A bug fix needs a focused regression test. Where practical, revert or mutate the fix and confirm that exact test fails.
• Assert observable results, not private calls or incidental structure.
• Print expected and actual values, variants, exit status, stderr, and case labels needed to diagnose a rare CI failure.
• Cover material success, failure, boundary, default, and state transitions. Do not add combinations without a concrete regression risk.

Control every input

• Inject clocks; fix timezone and locale when formatting matters.
• Seed randomness and print the replay seed on failure.
• Use semantic unordered equality when order is not a contract. Do not hide a required order by sorting expected output.
• Give each test an isolated environment, home, working directory, config root, database state, cache, and temporary directory.
• Bind servers to port 0 and retain the listener. Never find, close, and rebind a "free" port.
• Avoid process-global mutation from parallel tests. Use helpers that restore state automatically.

Synchronize; do not sleep

Replace sleeps and grace periods with a happens-before edge: channel receive, barrier, latch, event, condition, queue drain, file close, EOF, process exit, or application readiness.

Use fake time only when time is the contract. Know which clock it controls. Use a timeout only around an observable wait as an outer deadlock detector; expiry must fail with diagnostics. Never use a sleep, retry, timeout increase, or looser assertion as a race fix.

For processes, establish the required order: start output readers, close stdin when EOF is required, drain stdout and stderr, observe exit, then clean up. Preserve output even when finalization fails.

Own resources and cleanup

Register cleanup immediately after acquisition. Teardown in dependency order: stop producers, cancel work, drain or join consumers, flush, close resources, then delete storage. Surface cleanup failures.

Parallel tests need separate resources. A shared temp path, port, database row, clock, fake timer, module cache, or mutable global is a race even if it usually passes.

Use a local implementation of the real protocol at boundaries: an in-process HTTP server, transaction-isolated database, or controlled fake implementing the real interface. Do not put live third-party availability, credentials, mutable data, or rate limits in required tests.

Snapshots, properties, and fuzzing

Normalize only fields proven volatile, such as generated IDs or temp roots. Broad normalization can erase the bug. Golden updates must be explicit and reviewed.

Use property, fuzz, differential, or metamorphic tests when examples cannot cover the input space or no simple expected value exists. Retain the minimized input or seed so every discovery becomes a deterministic regression.

E2E, browser, CLI, and TUI

Wait for the exact readiness needed by the next action: health response, UI state, log event, or prompt. Do not use arbitrary sleep or generic network idle. Prefer user-visible and accessibility-based locators plus retrying assertions.

Control browser, viewport, fonts, animation, and dynamic content for visual tests. Assert CLI/TUI exit status and relevant stdout/stderr after complete drain. For AI-backed behavior, assert an objective observable contract, not one exact natural-language answer unless the text itself is the contract.

Language mechanics

Go

• Use t.TempDir, t.Setenv, t.Cleanup, httptest.Server, the race detector, and shuffled runs where relevant. Record shuffle seeds.
• Process-global environment and working-directory changes are incompatible with parallel tests.
• FailNow and testify require must run on the test goroutine. From handlers or spawned goroutines, report errors to the test goroutine and synchronize.
• Use channels and WaitGroup; use testing/synctest only when supported by the repository's Go version.
• Compare maps semantically or sort a copied key set for golden output.