atelier/domains/testing/pyramid.md

Test Pyramid — Derived Rules

Derives from domains/testing/first-principles.md P4 (Fast Feedback), P5 (Coverage of Behavior), P10 (No Test Theater).

The Pyramid

        /\
       /e2e\        few, slow, integration
      /------\
     /  integ  \    some, medium, contract
    /----------\
   /    unit    \   many, fast, isolated
  /--------------\

• Unit (many): test a function/class in isolation. Fast (< 10ms each). The bulk of tests.
• Integration (some): test components together (DB, API client, queue). Medium (< 1s each).
• E2E (few): test the whole system from outside. Slow (> 1s each). The tip of the pyramid.

Why a Pyramid (P4 Fast Feedback)

• A pyramid inverts to a "ice cream cone" (many e2e, few unit) when devs avoid unit tests.
• Inverted pyramids are slow and flaky. The feedback loop breaks.
• The pyramid shape preserves fast feedback: most failures are unit failures, found in < 10ms.

What Goes Where

Test Type	What it Covers	Speed	Count
Unit	A function, a class, a pure module	< 10ms	Many
Integration	DB queries, API contract, queue behavior	< 1s	Some
E2E	A user flow, an API request → response end-to-end	> 1s	Few

• A unit test does not hit the database. A unit test does not make a network call.
• An integration test does not test business logic; it tests the integration.
• An e2e test does not test edge cases; it tests the happy path. Edge cases are unit tests.

Anti-Patterns (P10 No Test Theater)

• Ice cream cone: many e2e, few unit. Slow, flaky, no signal.
• Cupcake: same count at every level. No pyramid shape. Slow.
• Only unit: 100% unit coverage, 0% integration. The system is untested as a whole.
• Only e2e: every edge case is an e2e test. The suite takes an hour.

Coverage (P5)

• Unit coverage of behavior: every branch, every edge case, every error path.
• Integration coverage of contracts: every API endpoint, every DB query, every queue interaction.
• E2E coverage of flows: the top 3–5 critical user flows. Not every permutation.

What Violates the Pyramid

Violation	Principle
E2E test for an edge case	P4 (slow feedback)
Unit test that hits the DB	P2 (not isolated)
0 integration tests	P5 (no coverage of contracts)
500 e2e tests, 50 unit tests	P10 (theater)
A 30-second test suite	P4 (feedback loop broken)