tdd

Tests are read far more often than they are written, and a bad test is worse than no test: it fails when the code is fine, passes when the code is broken, or freezes a design decision nobody meant to commit to. These rules describe what good looks like. They are language-agnostic; worked examples in TypeScript live in references/examples.md.

What makes a good test

• Tests behavior, not implementation. Assert on what a caller can observe: return values, thrown errors, messages sent across a boundary, persisted state. Never on private fields, internal call counts, or the order of internal steps. A correct refactor must not break a good test.
• Fails for one reason you care about. A test can rarely have only one technical cause of failure, and chasing that is a dead end. The real rule is one behavior or requirement per test: when it goes red, the name alone should tell you which requirement broke.
• Deterministic. Same input, same result, on any machine, in any order, at any time of day. No real clocks, no real network, no reliance on test execution order or on state another test left behind.
• Readable as documentation. The test name states the requirement in domain language, not mechanics. Someone who has never seen the implementation should learn what it guarantees by reading the test.
• Structured as Arrange, Act, Assert by default. Set up the state, perform the one action under test, then assert on the outcome, with the three phases visually distinct (a blank line between them is enough). Default, not law: parameterized tests, property-based tests, and some integration tests do not map onto separated phases, and forcing the shape onto them makes them worse. Depart from AAA when the test genuinely does not fit it, not to save a few lines.

Anti-patterns

• Testing implementation details. Asserting that a helper was called, or reaching into private state. This is the most common way tests become a tax on refactoring instead of a safety net for it.
• Snapshot-everything. Broad snapshots assert on everything and therefore specify nothing. Every unrelated change produces a diff, and the habitual fix is to re-record the snapshot, which is not review. Snapshots are for genuinely opaque large output, and even then, prefer targeted assertions on the parts that carry meaning.
• Shared mutable fixtures. State built once and mutated by several tests couples them, makes failures order-dependent, and makes any single test unreadable in isolation. Construct fresh state per test.
• Tests that mirror the code. One test file per source file, one test per method, is a structure that follows the implementation rather than the requirements. Organize around behaviors instead, so that reshaping the code does not mean rewriting the suite.
• Tautological assertions. Computing the expected value with the same logic the code uses, or asserting a mock returns what it was configured to return. The test passes by construction and verifies nothing.
• Interleaved act and assert. Alternating actions and checks inside one test hides which action a failure belongs to. If several actions each need assertions, that is several tests, or one action whose observable outcome you assert once.