Test Discipline

Keep a test suite true as it grows. These rules catch a test that passes today and lies, which no formatter, type checker or test runner can see.

Rules

• A test owns its inputs. Build each fixture it needs and remove it after. A test that reads state it did not make is broken, even when it passes.
• A test passes alone, in any order and in parallel. Share no mutable state, and do not depend on a sibling test that runs first.
• Assert on behavior, not internals. Assert on return values, output and visible side effects. A test that breaks on a pure refactor tests the implementation.
• Remove nondeterminism at the source. Pin the clock, seed randomness, and stub the network and the filesystem. Fix or quarantine a flaky test. Never hide it with a retry.
• Wait for a condition, not a duration. Measure time with a monotonic clock. Poll the predicate with a generous timeout, so that the assertion says that the event happened.
• Set a wall-clock limit to twice the time on the slowest runner in the CI matrix. A limit set from a local run fails on a slower runner.
• Watch a regression test fail before the fix. Then you know that it exercises the defect.

Read when needed

For fixture inputs, regression mutations, absence controls, test seams or platform differences, read test controls before editing the test.