Test discipline

<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

Test Discipline

Keep a test suite trustworthy as it grows. These are judgment rules, not lint — the deterministic floor (formatters, type checkers, the test runner itself) cannot catch a test that passes today but lies. Apply them when authoring or reviewing any automated test, in any language.

Isolation and ownership

• A test owns its inputs. Build the fixtures it needs and tear them down; never read or assert on state that another test, a previous run, or the developer's machine happened to leave behind — a test that reads state it did not create is broken even when it passes today.
• A test must pass alone, in any order, and in parallel: no shared mutable state, no reliance on execution order, no hidden dependency on a sibling running first.

Assert on behavior, not internals

• Assert on observable behavior and public contracts — return values, emitted output, externally visible side effects — not private fields, call counts, or internal structure a refactor should be free to change.
• A test that breaks on a pure refactor is testing the implementation, not the contract. Prefer the coarsest assertion that still proves the behavior.

Determinism

• Remove nondeterminism at the source: pin the clock, seed randomness, stub the network and the filesystem. A flaky test is a broken test, not a "sometimes" test — fix or quarantine it, never mask it with a blind retry.
• When you fix a bug, add the regression test that would have caught it first, and watch it fail before the fix so you know it exercises the defect.

Set up the condition the code actually reads

• When the code under test loads its own configuration, settings, or environment, put those values where that code reads them from — the file, the directory, the environment variable. A config object built in the test and handed to a helper never reaches a function that calls its own loader, so the test exercises the defaults and passes whatever you changed.
• Then prove the condition is live rather than merely arranged: assert that the input you set up actually moves the value the code branches on. A threshold left at its default, a window too small to trigger, a flag read from somewhere else — each leaves a test that stages a scenario the code never sees.
• The tell is a test that passes with the fix removed. Whenever a test is written after the fix it pins, delete the fix and watch it fail for the stated reason before trusting it.

A seam is not duplication

• A module-level alias or thin wrapper around an external dependency — a CLI, a clock, an HTTP client — is usually a deliberate test seam: it is the thing tests replace. Several modules each holding their own is not accidental repetition.
• So before consolidating duplicated access behind one shared helper, look at what the tests patch. Moving the call behind a new module silently bypasses every patch of the old alias, and the suite fails en masse for a reason unrelated to the refactor's intent.
• If the consolidation is still right, migrate the seam deliberately: move the patch points in the same commit, and keep one seam per module rather than one for the whole codebase.