writing-unit-tests-quick

Quick Unit Tests

A compact standard for everyday unit testing: enough to keep tests honest, short enough to read in one pass.

Framework-agnostic - match whatever runner, assertion style, and file layout the project already uses. If none exists, ask which runner to target before writing anything.

When to Use

1. Add tests for one function, class, or small module.
2. Sanity-check a handful of tests someone just wrote.
3. Cover a bug fix or a small new branch.

Escalate to writing-unit-tests when the job is a legacy backfill, a flaky or slow suite, a full-suite review, or heavy test-double design. Use test-driven-development when the tests should come before the code.

The Rules

1. Test behavior, not implementation. Assert what the public interface returns, throws, or emits. Never touch private state.
2. One reason to fail. If the test name needs "and", split it.
3. Name the behavior and the condition. returns zero when the cart is empty - the CI log alone should say what broke.
4. Arrange - Act - Assert, visibly separated, with exactly one call to the unit under test.
5. Expected values are independent literals. Never recompute them the way the code does, and never import the implementation's own constant - that test can only agree with the code.
6. Assert specific values. Not truthy, not defined. For errors, assert the type and the meaningful part of the message.
7. No logic in the test. No loops or conditionals - use the runner's parameterized/table-driven API so each case reports separately.
8. Control nondeterminism. Inject or freeze time, randomness, and IDs; use fake timers instead of real delays; await every promise and assert rejections directly.
9. Mock only what you do not own. Network, storage, clock. Never stub your own modules - that freezes the design and breaks on every refactor.
10. No real I/O. If proving the behavior needs a database, HTTP call, or browser, say so and route it to integration coverage instead of mocking around it.
11. Synthetic test data only. No credentials, tokens, or real personal data - a fixture committed once stays in history forever.
12. Leave nothing skipped silently. A skip or only carries an issue link and an owner, or it does not land.
13. Do not reshape the code to suit the test. Hard-to-test code is a design finding to raise, not something to restructure inside a test-adding change.