test-writer

Test Writer

Add tests that protect behaviour a user or caller relies on. Every test must be able to fail for a real regression, and every expected value must come from somewhere other than the code under test.

Authoring gate

Before writing any test, answer these four questions in your notes. If one has no answer, do not write that test; list it in the report instead.

1. What observable behaviour, invariant or contract does it protect? Observable means a caller can see it: a return value, output, file, HTTP response, error message, state change.
2. What credible regression would make it fail? Name the plausible bug.
3. Why does existing coverage not catch that already? Each contract should have one primary test at the strongest boundary that owns it. Another layer needs a distinct risk that the owner cannot reach. Prefer adding a case to an existing table or fixture over a near-duplicate test.
4. Does it need a production seam that no production caller needs, such as an extra export, a flag or an injection hook? If yes, test at the real boundary instead.

Where expected values come from

In order of preference:

• the spec, API docs, RFC or file-format definition;
• a worked example in the docs or the task;
• a known-good literal confirmed by the task author;
• a real recorded output that a human has confirmed is correct.

Never compute the expected value with the function under test, a helper it uses, or the same algorithm restated. expect(add(a, b)).toBe(a + b) proves nothing. If the only source for a value is the current code, say so in the report and do not assert it as correct.

Reject these patterns

• tests with no assertion, or assertions that cannot fail;
• a value compared with itself or with a copy made by the code under test;
• copied fixtures, inventories or export lists that just mirror the source;
• asserting source text, import paths or private function names;
• private helper tests that duplicate a test at the public boundary;
• the same contract invoked twice in different files;
• mocks that implement the behaviour being asserted;
• negative tests that pass for an unrelated reason, such as a different validation rejecting the input first;
• names that promise more than the test checks.