test-planner

Test Plan Specification Skill (ISO/IEC/IEEE 29119-3 & E2E Testing Patterns)

Overview

Produce an authoritative Test Plan document compliant with ISO/IEC/IEEE 29119-3:2021 (superseding legacy IEEE 829) and incorporating modern E2E Testing Patterns (Headless Playwright / Cypress). The Test Plan defines test strategy, fixture architecture, boundary conditions, and full-stack containerized acceptance criteria for automated verification.

Role & Execution Timing

• Author: dev-tester (SDET)
• When Created: Early Stage 1 / Phase 3 (immediately after docs/sdd.md is published by dev-architech).
• Target Output Path: /opt/data/workspace/{project_name}/docs/test_plan.md

---

📐 Testing Pyramid & Triple-Gate Quality Standard

1. Pyramid Allocation

• Unit Tests (70%): Pure domain logic, model validations, helper utilities, schema serialization. Executed in milliseconds without external I/O.
• Integration Tests (20%): API Routers, database transactions, dependency injection overrides, authentication & permission middlewares.
• End-to-End (E2E) Container Tests (10%): Real browser / HTTP headless workflows executed against the live running Docker Compose stack (http://localhost).

2. Triple-Gate Quality Standard (🚦 Triple-Gate Acceptance Iron Law)

1. Module Pass Rate Gate: failed == 0 and errors == 0 (100% pass rate for unit and integration tests).
2. Code Coverage Gate: Backend & frontend core logic coverage $\ge 80%$.
3. Phase 6 Containerized E2E Gate: 100% passing E2E acceptance suite executed in headless mode against the live running Docker Compose environment before project release.

---

🛠️ Step-by-Step Procedure

Step 1: Read SRS, SDD, and E2E Testing Patterns

1. Read /opt/data/workspace/{project_name}/docs/srs.md and /opt/data/workspace/{project_name}/docs/sdd.md.
2. Extract all Use Cases (UC-XXX), API Endpoints, Database Entities, and Constraints.
3. Consult e2e-testing-patterns for Page Object Model (POM), selector strategies (getByRole, data-testid), and headless test execution.

Step 2: Define Test Architecture & Fixtures

• Unit/Integration: pytest (Python) or vitest / supertest (Node.js/TS).
• E2E Acceptance: Headless Playwright (npx playwright test / pure CLI automation — zero GUI, zero computer_use required).
• Database Strategy: In-memory / transactional DB rollback for unit tests; live PostgreSQL container for E2E tests.

Step 3: Author Test Suite Catalog (Unit, Integration & E2E Scenarios)

Map each UC-XXX to:

1. Unit test cases (TC-UNIT-XXX)
2. Integration API test cases (TC-INT-XXX)
3. E2E critical user journey test cases (TC-E2E-XXX)

Step 4: Define Boundary & Security Edge Cases

• Missing mandatory fields (HTTP 422 / 400).
• Duplicate unique constraints (HTTP 409).
• Expired / malformed JWT tokens (HTTP 401).
• Insufficient role permissions (HTTP 403).
• Non-existent resource lookups (HTTP 404).
• Boundary inputs (empty strings, maximum string length, negative numbers, special characters).

Step 5: Write Document to /docs/test_plan.md

Write the complete specification to /opt/data/workspace/{project_name}/docs/test_plan.md.

---

📄 Test Plan Document Template Structure

# Software Test Plan
## Project: {Project Name}
**Standard**: ISO/IEC/IEEE 29119-3:2021 (Superseding IEEE 829)  
**Version**: 1.0.0  
**Author**: dev-tester (SDET)  
**Status**: Baseline  
**References**: `docs/srs.md`, `docs/sdd.md`, `e2e-testing-patterns`  

---

## 1. Test Strategy & Objectives
### 1.1 Objective
Verify that the software fulfills all functional requirements in `docs/srs.md`, conforms to architecture in `docs/sdd.md`, and meets all quality and security gates.

### 1.2 Testing Pyramid Distribution
- **Unit Tests (70%)**: Fast, isolated tests for utility functions, model constraints, and domain logic.
- **Integration Tests (20%)**: API endpoint testing with database interactions.
- **E2E Scenario Tests (10%)**: Complete multi-step workflows validating end-to-end user journeys against live Docker stack.

---

## 2. Test Environment & Fixtures Architecture
- **Unit / Integration Runner**: Vitest / Pytest / Supertest
- **E2E Runner**: Headless Playwright CLI (executed against `http://localhost`)
- **Database Strategy**: Isolated transactional DB for unit tests; live container for E2E.
- **Auth Fixtures**: Pre-seeded standard and admin credentials.

---

## 3. Test Traceability Matrix (TTM)
| Test Case ID | Target UC | Test Tier | Target Endpoint / UI Component | Description | Expected Result |
| :--- | :--- | :--- | :--- | :--- | :--- |
| `TC-AUTH-001` | `UC-001` | Integration | `POST /api/v1/auth/register` | Successful registration | HTTP 201, User created |
| `TC-AUTH-002` | `UC-001` | Integration | `POST /api/v1/auth/register` | Duplicate email registration | HTTP 409 Conflict |
| `TC-AUTH-003` | `UC-002` | Integration | `POST /api/v1/auth/login` | Valid login | HTTP 200, JWT returned |
| `TC-E2E-001`  | `UC-001, UC-002` | E2E | `/register` -> `/login` -> `/` | Register new user, login, verify dashboard | Redirect to `/`, Token stored, UI rendered |
| `TC-E2E-002`  | `UC-003, UC-009` | E2E | `/meetings/create` -> `/meetings/:id` | Create meeting, add agenda items | Meeting card displayed, items listed |

---

## 4. Boundary & Security Test Matrix
| Category | Scenario | Test Input | Expected Status |
| :--- | :--- | :--- | :--- |
| Input Validation | Empty required field | `{"email": ""}` | HTTP 422 / 400 |
| String Length | Overly long input | 300-char string | HTTP 422 / 400 |
| Security | Missing Bearer token | No `Authorization` header | HTTP 401 |
| Security | Tampered JWT | Invalid signature | HTTP 401 |
| Authorization | Standard user accessing Admin API | Role `USER` on `/admin` | HTTP 403 |

---

## 5. End-to-End (E2E) Containerized Acceptance Test Suite
*Executed in Phase 6 against the live Docker Compose environment (`http://localhost`)*

### 5.1 Page Object Model (POM) Architecture
- `LoginPage`: Selectors (`getByLabel('Email address')`, `getByRole('button', { name: 'Sign in' })`)
- `RegisterPage`: Selectors (`getByLabel('Display name')`, `getByLabel('Password')`)
- `DashboardPage` & `MeetingDetailPage`: Selectors (`getByRole('button', { name: 'Create Meeting' })`, `data-testid`)

### 5.2 Critical User Journeys (E2E Scenarios)
1. **Journey 1: Account Onboarding & Session Persistence**
   - Navigate to `http://localhost/register`
   - Fill form, submit ➔ verify redirect to `/` or `/login`
   - Refresh page ➔ verify session remains authenticated
2. **Journey 2: Meeting Lifecycle & Real-Time Agenda Tracking**
   - Create meeting ➔ verify listed on `/meetings`
   - Open detail page ➔ add 2 agenda items ➔ toggle `isDiscussed`
   - Record decision ➔ create action item ➔ assign to attendee
3. **Journey 3: Admin Governance & Access Enforcement**
   - Login as standard user ➔ verify `/admin` redirects or 403
   - Login as admin ➔ inspect user list ➔ toggle status

---

## 6. Quality Acceptance Gates (Triple-Gate Standard)
1. **Module Pass Rate Gate**: `failed == 0` and `errors == 0` (100% pass rate).
2. **Code Coverage Gate**: Backend & frontend core logic $\ge 80\%$.
3. **E2E Container Gate**: 100% Pass Rate across all `TC-E2E-XXX` test scenarios in Phase 6.