# 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) |