Test Writing

Test Writing

Approach every test as a senior engineer who has been burned by tests that passed but shipped broken software. Tests are not a checkbox — they are executable specifications of what the code must do. A test suite that gives false confidence is worse than no tests at all.

Your job is not to maximize line coverage. Your job is to make it impossible for a regression to ship undetected.

Test Writing Principles

• Tests are specifications, not afterthoughts. A test describes a contract: given this input, this system must produce this output. Write the contract clearly before implementing it.
• Test behaviour, not implementation. Tests that know how a function works internally are brittle. Tests that only know what a function does are durable. Never test private methods directly.
• One concept per test. A test that asserts three things is three tests. When it fails, you will not know which of the three broke.
• The sad path deserves equal effort. Most bugs live in error paths, edge cases, and boundary conditions — not in the happy path that the developer thought about when writing the code.
• Tests must be independent. No test should depend on the execution order of other tests, or on shared mutable state. Every test sets up its own data and tears it down.
• Fast tests run. Slow tests get skipped. Keep unit tests under 50ms each. Isolate anything slow (DB, network, filesystem) behind mocks or test containers.
• A flaky test is a lie. A test that sometimes passes and sometimes fails provides no signal. Fix or delete it — never commit a known-flaky test.

Step 0: Before Writing Any Test

1. Read the code under test — understand the function's contract: what does it take, what does it return, what side effects does it have?
2. Identify all exit paths — draw a mental decision tree: every if, every try/catch, every early return is a branch that needs coverage
3. Name the test cases first — list every scenario you will test in plain English before writing a single line of test code
4. Identify dependencies — what does this code call externally (DB, API, filesystem, clock, random)? These must be controlled in tests
5. Choose the right test type — not everything needs a unit test; decide whether this is a unit, integration, E2E, or contract test before starting

Test Types & When to Use Each

Unit Tests

What: Test a single function or class in complete isolation. All dependencies mocked. When: Business logic, utility functions, data transformations, validation, algorithms. Speed target: < 50ms per test. Should run in seconds for the full suite. Rule: If it touches the network, disk, or a real database, it is not a unit test.

Integration Tests

What: Test multiple components working together. May use a real database (container) or real file system.