prd-v07-test-planning

# Test Planning

Position in workflow: v0.7 Epic Scoping → **v0.7 Test Planning** → v0.7 Implementation Loop

## Consumes

This skill requires prior work from v0.7 Epic Scoping and v0.6 specifications:

- **EPIC-\* entries** (from v0.7 Epic Scoping) — EPIC scope defines test boundaries; test plan must cover all APIs/BRs/UJs within EPIC Context & IDs section
- **API-\* endpoint contracts** (from v0.6 Technical Specification) — Each endpoint has request/response shape and error codes that must be tested
- **DBT-\* data model specifications** (from v0.6 Technical Specification) — Schema constraints, relationships, and business rules enforce data integrity tests
- **BR-\* business rules** (from v0.3 Commercial Model) — Each rule must have at least one test verifying positive (rule allows) and negative (rule blocks) cases
- **UJ-\* user journey entries** (from v0.4 User Journeys) — Critical journeys need E2E tests verifying complete flow from trigger to value moment

This skill assumes EPIC- entries are complete with full API-/DBT-/BR-/UJ- references in Context & IDs section.

## Produces

This skill creates/updates:

- **TEST-\* entries** (test case specifications, automation path) — Concrete, verifiable test cases with Given-When-Then format, test type, and coverage mapping to upstream IDs
- **Test coverage matrix** (per EPIC) — Validation showing every API- endpoint, BR- rule, and core UJ- journey has TEST- entries; identifies gaps
- **Test automation specification** — For each Critical/High priority TEST-, identifies test file path and automation framework (unit/integration/E2E)

All TEST- entries are **acceptance criteria specifications**, not confidence-based. They are:
- **Derivable from upstream IDs** (every TEST- ties to specific API-/BR-/UJ-/DBT-)
- **Executable** (Given-When-Then format is testable; automation paths are specified)
- **Complete for acceptance** (passing all TEST- for EPIC means EPIC is done)
- **Focused on behavior** (tests what the system does, not implementation details)

Example TEST- entry (API endpoint test):
```markdown
TEST-001: User creation succeeds with valid data
Type: Integration
Tests: API-001 (POST /users), BR-001 (email uniqueness), DBT-010 (users table)
EPIC: EPIC-01

Given: No user with email "test@example.com" exists, database ready
When: POST /api/users with { email: "test@example.com", password: "Valid123!" }
Then:
  - Response status: 201 Created
  - Response body contains user id and email
  - User record exists in DBT-010 (users table)
  - Password is hashed, not plaintext
  - Email verification email queued

Validation Method: Automated
Automation: tests/api/users.test.ts (Integration test)
Priority: Critical
```

Example TEST- entry (Business rule test):
```markdown
TEST-005: Password validation enforces minimum length
Type: Unit
Tests: BR-002 (password requirements)
EPIC: EPIC-01

Given: Password validation function configured per BR-002
When: Validate password "weak" (length 4)
Then:
  - Returns validation failure
  - Error message: "Password must be at least 8 characters"
  - No user record created

Validation Method: Automated
Automation: tests/unit/validation.test.ts
Priority: High
```

Example TEST- entry (User journey E2E test):
```markdown
TEST-010: Onboarding journey completes successfully
Type: E2E
Tests: UJ-000 (onboarding), API-001 (signup), API-002 (login), SCR-001 (dashboard)
EPIC: EPIC-01

Given: New user on signup page, all services ready
When: User enters email/password → submits → verifies email → enters profile info → confirms
Then:
  - User redirected to dashboard (SCR-001)
  - Welcome message displayed with user name
  - User session is active and persisted
  - KPI-001 (activation) event tracked with timestamp
  - UJ-000 completion confirmed

Validation Method: Both (Automated + manual verification of final state)
Automation: tests/e2e/onboarding.spec.ts
Priority: Critical
```

## Core Principle: Test-First

> Tests are not an afterthought. They are the **contract** that defines what "done" means.
> If you can't write the test, you don't understand the requirement.

Write TEST- entries **before** writing code. This forces clarity about what you're building.

If you cannot write a concrete Given-When-Then for a specification, the requirement is ambiguous. Do not write a vague test and move on. Instead, identify the specific ID (API-XXX, BR-XXX) that is unclear, note the competing interpretations, and log an AMBIGUITY in the EPIC's Assumptions & Ambiguities table. A test you cannot write precisely is more valuable as a flagged gap than a test you write by guessing.

## Test Types

| Type | What It Tests | When to Use | Scope |
|------|---------------|-------------|-------|
| **Unit** | Single function/method | Business logic, calculations | Smallest unit |
| **Integration** | Component boundaries | API ↔ Database | Module level |
| **E2E** | Full user flow | Critical journeys | System level |
| **Contract** | API shape/types | External integrations | Interface level |
| **Performance** | Speed/load | Critical paths | Benchmark |

## Coverage Requirements

| ID Type | Minimum Coverage | Rationale |
|---------|------------------|-----------|
| **API-** | 1 happy path + 1 error case per endpoint | Endpoints are integration points |
| **BR-** | 1 test per rule, including boundary cases | Rules are product logic |
| **UJ-** | 1 E2E test per core journey | Journeys are user value |
| **DBT-** | Constraint tests for critical fields | Data integrity is foundational |

## Test Planning Process

1. **Pull EPIC- scope**
   - Which APIs, DBTs, BRs are included?

2. **For each API-**: Define request/response tests
   - Happy path: Valid input → expected output
   - Error cases: Invalid input, auth failures, not found
   - **Verify first**: Can you state the exact response body shape and every error code from the spec? If API- says "returns error" without specifying the code/shape, flag it: "API-XXX spec missing [specific gap]." Do not