Test Planning

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

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.

Test Types

Coverage Requirements

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

3. For each BR-: Define rule validation tests

   • Positive: Rule allows expected behavior
   • Negative: Rule blocks invalid behavior
   • Boundary: Edge cases at limits

4. For each UJ-: Define end-to-end flow tests

   • Complete journey from trigger to value moment

5. For each DBT-: Define data integrity tests

   • Constraints enforced (unique, not null)
   • Relationships maintained (FK integrity)

6. Create TEST- entries linked to implementation IDs

7. Add TEST- references back to EPIC-

TEST- Output Template

TEST-XXX: [Test Name]
Type: [Unit | Integration | E2E | Contract | Performance]
Tests: [API-XXX | BR-XXX | UJ-XXX | DBT-XXX]
EPIC: [EPIC-XXX]

Given: [Preconditions — initial state]
When: [Action/trigger — what happens]
Then: [Expected outcome — what should result]

Validation Method: [Automated | Manual | Both]
Automation: [Test file path when implemented]
Priority: [Critical | High | Medium | Low]

Example TEST- entries:

TEST-001: User creation succeeds with valid data
Type: Integration
Tests: API-001 (POST /users), BR-001 (email uniqueness)
EPIC: EPIC-01

Given: No user with email "test@example.com" exists
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)
  - Password is hashed (not plaintext)

Validation Method: Automated
Automation: tests/api/users.test.ts
Priority: Critical

TEST-002: User creation fails with duplicate email
Type: Integration
Tests: API-001, BR-001 (email uniqueness)
EPIC: EPIC-01

Given: User with email "existing@example.com" already exists
When: POST /api/users with { email: "existing@example.com", password: "Valid123!" }
Then:
  - Response status: 409 Conflict
  - Response body: { error: { code: "EMAIL_EXISTS", message: "..." } }
  - No new user record created

Validation Method: Automated
Automation: tests/api/users.test.ts
Priority: Critical

TEST-003: User creation fails with weak password
Type: Unit
Tests: BR-002 (password requirements)
EPIC: EPIC-01

Given: Password validation function
When: Validate password "weak"
Then:
  - Returns false
  - Error message indicates minimum length requirement

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

TEST-010: Onboarding journey completes successfully
Type: E2E
Tests: UJ-000 (onboarding)
EPIC: EPIC-01

Given: New user on signup page
When: User completes signup → email verification → profile setup
Then:
  - User arrives at dashboard (SCR-001)
  - Welcome message displayed
  - User session is active
  - KPI-001 (activation) event tracked

Validation Method: Both (Automated + Manual verification)
Automation: tests/e2e/onboarding.spec.ts
Priority: Critical

Test Priority Framework

Writing Good Given-When-Then

Good Examples

Given: User is logged in and has 3 existing reports
When: User clicks "Create Report" and fills required fields
Then: 4 reports now exist, new report appears at top of list

Given: User has reached the free tier limit of 5 reports
When: User attempts to create a 6th report
Then: Error message shows "Upgrade to create more reports"
      Create button is disabled
      Upgrade CTA is displayed

Bad Examples

Given: The system is working
When: User does something
Then: It works correctly

(Too vague — what does "working" mean?)

Given: User
When: API
Then: Success

(No specifics — useless as a test spec)

Test Categories by EPIC Phase

For Database Schema (Window 1)

TEST-XXX: [Table] enforces [constraint]
TEST-XXX: [Table] allows valid data
TEST-XXX: RLS policy restricts access correctly

For API Endpoints (Window 2)

TEST-XXX: [Method] [Path] returns [status] for [scenario]
TEST-XXX: [Method] [Path] enforces [BR-XXX]
TEST-XXX: [Method] [Path] handles [error case]

For UI Integration (Window 3)

TEST-XXX: [Screen] loads data from [API-XXX]
TEST-XXX: [Form] validates input per [BR-XXX]
TEST-XXX: [UJ-XXX] completes end-to-end

Anti-Patterns to Avoid

Quality Gates

Before proceeding to Implementation Loop:

• Every API- endpoint has at least 2 TEST- entries (happy + error)
• Every BR- rule has at least 1 TEST- entry
• Every core UJ- journey has an E2E TEST-
• Critical tests are marked for automation
• TEST- entries added to EPIC- Section 2
• Total test count is reasonable (30-50 for MVP)

Downstream Connections

TEST- entries feed into:

Detailed References

• Test planning examples: See references/examples.md
• TEST- entry template: See assets/test.md
• Test type decision guide: See references/test-types.md