test

Essential Principles

Test what the code does, not what the mocks do.

1. Real code over mocks. Mocks hide integration bugs and make tests brittle to refactoring — use real implementations. Mock only external services, non-deterministic inputs, or expensive I/O. If the function under test accepts a callback or dependency — pass a real one.
2. Assert on behavior, not internals. Assert on return values, thrown errors, observable side effects. Never assert on call counts, internal state, or framework internals (e.g., setTimeout spy).
3. One behavior per test. "and" in the test name → split it. Each test verifies one observable outcome.
4. Names describe behavior. Test name = what the code does, stated as behavior. Good: retries 3 times then throws the last error. Bad: respects maxAttempts.
5. No duplicate coverage. Two tests proving the same behavior = delete one. Each test must verify something no other test covers.

Quick Start

Before writing any test, ask:

1. What observable behavior am I testing?
2. Can I test this with real code instead of mocks?
3. Does the test name describe what broke if it fails?

If any answer is unclear, return to ## Essential Principles before writing the test.