Testing

Testing

Write high-value tests: tests that keep passing through refactors and fail only when observable behavior changes. A test is low value if renaming a private function, splitting a module, or swapping an implementation detail breaks it.

These rules are language-independent. Tool names, commands, and syntax live in a per-language reference; read the one for the language you are editing:

• references/python.md
• references/typescript.md
• Another language: apply the same rules with that language's idioms, and add a reference file for it in the same shape.

Rules

1. Test the public API only. The public API is the surface other packages or modules are already allowed to depend on: a library's api entry point, the module API that sibling modules use inside a package, and the application's facade or serialized events at the top. Do not import private modules or assert on private state. The one exception is a test whose point is a tricky implementation detail; mark that site test-isolation: <specific reason> in a comment.
2. No patching or mocking. Do not replace code at runtime (monkeypatching attributes, module mocking, spies, mock frameworks). It couples the test to how the code is written. Setting inputs is fine: environment variables, working directory, temp directories. If a test seems to need a patch, the code is missing a seam: inject the owning library's interface through a constructor argument or parameter, and pass a Fake implementation.
3. Integrate modules with Fakes. A Fake is an in-memory, faithful implementation of the same API, not a stub with canned answers. A Fake is never more capable or more forgiving than production: it reports the same supported capabilities (derived from the same definition), validates and loads state as strictly, and enforces the same limits. Whoever changes the real behavior updates the Fake in the same PR. The owning library ships one contract suite per interface; run it against every implementation, Fake and production, without skipping contract cases. See references/fakes-and-contracts.md.
4. Test properties, not instances. Default to property-based tests and fuzzing for parsers, serializers, validators, pure logic, and state machines. Use single examples only for a named scenario or a regression. Use golden fixtures where behavior reduces to a deterministic state snapshot. Test functional cores with pure properties over generated event sequences, including crash and replay at every durable intent boundary. Use no async, sleeps, or Fakes in core tests. See references/properties-and-goldens.md.
5. No flaky tests. Never depend on timeouts, sleeps, wall-clock time, scheduling order, or shared state. Inject clocks and simulate timeouts; do not wait for them. Never add retries. See references/flakiness.md.
6. Bug fixes. Add a regression test at the lowest layer that reproduces the symptom, through the public API, that fails at the merge base. Then add a property test that generalizes the pattern, so the whole class of bug is covered and not just the reported instance. Example: for an uppercase hypothesis id that broke workspace names, test every agent-supplied id with a property test, not only the uppercase one. The class is the mechanism named under the software-design skill's Mechanism checkpoint; a test that replays the one reply or exit path that triggered the bug does not cover it.
7. Test the unhappy paths at boundaries. Canned replies that match what the code expects test only the happy path. Where code meets an agent, a cluster, an MCP client, or a subprocess, drive it with generated behavior: agent output generated from the declared schema, including options the run does not offer, repeated mistakes, malformed output, and replies slower than the caller's deadline; and scheduled faults on the far side. For a scope that owns a resource, test as a property that an exit at any point (each step, exception, cancellation, signal, stop) releases the resource and ends in a typed terminal state. Composed-system chaos tests inject implementation failures and unknown exceptions; require a typed terminal state, never an implicit success. Test an agent tool server with synthesized tool calls and call sequences, not agents. Assert invariants, not one expected trace. See references/fault-injection.md.
8. Test process and signal code in process. Logic that runs in a child process or a signal handler is invisible to coverage and slow to test through subprocesses. Put it behind a function the test calls directly with injected I/O interfaces; keep at most one subprocess test per entry point to prove the wiring.