Backend Testing Strategy by Architecture Layer

System Overview

Different architectural layers have different responsibilities, and tests should be structured to verify those specific responsibilities without over-specifying internal implementation details. This skill provides rules for matching the right testing style (unit, integration, feature) to the correct layer.

Principles Behind Good Tests

• Arrange, Act, Assert (AAA). One logical flow per test: set up the scenario, perform the one action under test, assert the outcome. Keep the "Given" visibly in the test body.
• Isolation. Each test owns its data and runs independently of others, in any order. No shared mutable state, no order dependence. Deterministic tests are the only ones worth having.
• Mock only at boundaries. Replace slow or non-deterministic collaborators (databases, HTTP, queues) with doubles. Do not mock the database inside a repository test (test the repository against a real test DB) and do not mock the very object under test. Mocking everything while asserting on call order verifies the implementation, not the behavior — a brittle test that breaks on every refactor.
• Assert behavior, not internals. Assert on the resulting state, returned value, or recorded events — not on private methods or the exact internal call sequence. A test that survives a legitimate refactor is a test worth keeping.
• Coverage is a guide, not a target. Aim for meaningful coverage of business logic and unhappy paths; 100% is not the goal and can incentivize worthless assertions.

See clean-code-foundations.md for the encapsulation/DRY lenses that apply here.

Numbered Workflows