test-plan-format

name	test-plan-format
description	Test plan structure, naming conventions, edge case generation rules, and file saving conventions for QA test plans.
activation	Load when creating or formatting QA test plans

Test Plan Format

File Conventions

• Location: docs/testing/plans/
• Naming: YYYY-MM-DD-<topic>-test-plan.md where <topic> is a slugified summary (lowercase, hyphens, no spaces)
• Create directory if needed: mkdir -p docs/testing/plans

---

Plan Structure

Every test plan MUST follow this exact structure:

# Test Plan: <title>

## Source
- Type: <PR #N / branch <name> / last N commits / staged changes>
- Base: <main/master>
- Date: <YYYY-MM-DD>

## Changes Summary

<Brief description of what changed and what needs testing. List affected areas.>

## Detected Tools
- Playwright: <available/unavailable>
- HTTP client: <curl/httpie/unavailable>
- Database access: <psql/sqlite3/mysql/unavailable>

## FE Test Scenarios

### FE-01: <scenario name>
- **Area:** <component/page>
- **Preconditions:** <what must be true before test>
- **Steps:**
  1. <action>
  2. <action>
  3. <verification>
- **Expected:** <expected result>
- **Edge cases:**
  - <edge case 1>
  - <edge case 2>

## BE Test Scenarios

### BE-01: <scenario name>
- **Area:** <endpoint/service>
- **Method:** <HTTP method> <path>
- **Headers:** <required headers, e.g. Authorization: Bearer TOKEN>
- **Payload:** `<JSON body>`
- **Expected:** <status code>, <response body description>
- **DB Check:** `<SQL query>` — <expected state>
- **Edge cases:**
  - <edge case with expected response>

---

Scenario Naming

• FE scenarios: FE-01, FE-02, ... FE-NN (zero-padded two digits)
• BE scenarios: BE-01, BE-02, ... BE-NN (zero-padded two digits)
• Numbering is sequential within each section, starting from 01

---

Edge Case Generation Rules

For EVERY scenario, consider and include relevant edge cases from:

Input boundaries

• Empty/null/missing values
• Maximum length strings
• Special characters (unicode, HTML entities, SQL metacharacters)
• Negative numbers, zero, boundary values (MAX_INT)

Authentication & Authorization

• Unauthenticated request (no token)
• Expired token
• Valid token but insufficient permissions
• Another user's resource (IDOR)

State

• Resource does not exist (404)
• Duplicate creation attempt (409)
• Concurrent modifications (race conditions)
• Resource in unexpected state (e.g., already deleted, already processed)

Data integrity

• Required fields missing (422)
• Invalid data types (string where number expected)
• Referential integrity (foreign key does not exist)

FE-specific

• Slow/no network connection
• Empty state (no data to display)
• Very long content (overflow, truncation)
• User not logged in
• Browser back/forward during operation

---

Section Omission Rules

• If changes are FE-only: omit the ## BE Test Scenarios section entirely
• If changes are BE-only: omit the ## FE Test Scenarios section entirely
• If a tool is unavailable: note it in ## Detected Tools and mark dependent scenarios with (skip — <tool> unavailable) in the scenario name

---

Plan Quality Checklist

Before saving the plan, verify:

• Every scenario has at least 2 edge cases
• Every BE scenario has an expected status code
• Every FE scenario has concrete steps (not "test the form")
• DB Checks use actual table/column names from the codebase
• API paths match actual routes from the codebase
• No placeholder text (TBD, TODO, fill in later)