# Test-type guide

Per-test-type purpose, structure, illustrative examples, and key rules. Load this when generating any of the six test-type sections in the test plan.

For each test type below, the **Structure** block shows the markdown shape of the plan entry. The corresponding output template in `templates/{type}-test-plan.md` (if present) is the authoritative output format — the structure here is illustrative.

---

## Unit Tests

Use the template from `templates/unit-test-plan.md` as the output format.

**Purpose:** Test individual functions and methods in isolation.

**Coverage targets:**
- 80% minimum overall coverage
- 100% for critical paths (auth, payments, data validation)
- All error paths tested
- All edge cases tested (null, empty, boundary values, overflow)

**What to include:**

```markdown
### Unit Tests

#### UT-001: Email validation accepts valid emails
- **File:** tests/unit/auth/validation.test.ts
- **Function under test:** validateEmail()
- **Scenarios:**
  - Valid standard email: user@example.com -> true
  - Valid with subdomain: user@sub.example.com -> true
  - Invalid missing @: userexample.com -> false
  - Invalid missing domain: user@ -> false
  - Empty string: "" -> false
  - Null input: null -> false
- **Traces to:** REQ-001, AC-001.1

#### UT-002: Password validation enforces minimum length
- **File:** tests/unit/auth/validation.test.ts
- **Function under test:** validatePassword()
- **Scenarios:**
  - Valid 8 chars: "abcd1234" -> true
  - Invalid 7 chars: "abcd123" -> false
  - Empty string: "" -> false
  - Exactly 8 chars boundary: "12345678" -> true
- **Traces to:** REQ-001, AC-001.2
```

**Key rules for unit tests:**
- One behavior per test (if name has "and", split it)
- Test behavior, not implementation
- Real code preferred over mocks
- Edge cases: null, undefined, empty, boundary, overflow, special characters

---

## Integration Tests

Use the template from `templates/integration-test-plan.md` as the output format.

**Purpose:** Test component interactions, API endpoints, database operations.

**What to include:**

```markdown
### Integration Tests

#### IT-001: POST /api/users rejects duplicate email
- **File:** tests/integration/auth/registration.test.ts
- **Components:** UserController -> UserService -> UserRepository -> Database
- **Setup:** Create existing user with email "test@example.com"
- **Action:** POST /api/users { email: "test@example.com", password: "valid123" }
- **Expected:** 409 Conflict, { error: { code: "EMAIL_EXISTS" } }
- **Cleanup:** Remove test users
- **Traces to:** REQ-001, AC-001.3
- **API contract ref:** api-contract.md, POST /api/users, error codes

#### IT-002: POST /api/users creates user successfully
- **File:** tests/integration/auth/registration.test.ts
- **Components:** UserController -> UserService -> UserRepository -> Database
- **Setup:** Clean database
- **Action:** POST /api/users { email: "new@example.com", password: "valid123", name: "Test" }
- **Expected:** 201 Created, { id: string, email: "new@example.com", name: "Test", createdAt: string }
- **Verify:** User exists in database with hashed password
- **Cleanup:** Remove test users
- **Traces to:** REQ-001, AC-001.4
- **API contract ref:** api-contract.md, POST /api/users, success response
```

**Key rules for integration tests:**
- Test against real database (use test database, not mocks)
- Validate against API contract shapes exactly
- Test both success and error paths per endpoint
- Clean up test data (use transactions or explicit cleanup)
- Test database constraints (unique, NOT NULL, foreign keys)

---

## E2E Tests

Use the template from `templates/e2e-test-plan.md` as the output format.

**Purpose:** Test complete user flows through the UI using Playwright.

**What to include:**

```markdown
### E2E Tests (Playwright)

#### E2E-001: User registration flow
- **File:** tests/e2e/auth/registration.spec.ts
- **Preconditions:** Application running, database clean
- **Steps:**
  1. Navigate to /register
  2. Fill in email: "e2e-test@example.com"
  3. Fill in password: "ValidPass123"
  4. Fill in name: "E2E Test User"
  5. Click "Create Account" button
  6. Wait for redirect to /dashboard
- **Expected results:**
  - Registration form accepts input
  - Loading state shown during submission
  - Redirected to /dashboard after success
  - Welcome message displays user name
  - User can log out and log back in with same credentials
- **Error scenarios:**
  - Submit with empty email -> validation error shown inline
  - Submit with short password -> validation error shown inline
  - Submit with duplicate email -> error message shown
- **Traces to:** REQ-001
- **Screenshots:** Capture at each step for visual regression
```

**Key rules for E2E tests:**
- Test complete user journeys, not individual components
- Include both happy path and error scenarios
- Test loading states, error states, empty states
- No skipping "obvious" flows (login, logout, navigation)
- Use realistic test data, not "test" and "12345"
- Capture screenshots for visual verification

---

## Smoke Tests

Use the template from `templates/smoke-test-plan.md` as the output format.

**Purpose:** Quick sanity check that critical paths work after deployment.

**What to include:**

```markdown
### Smoke Tests

#### SMOKE-001: Application starts and responds
- **Check:** GET /health returns 200
- **Timeout:** 5 seconds
- **Traces to:** Infrastructure

#### SMOKE-002: Authentication works
- **Check:** POST /api/auth/login with valid credentials returns 200 + token
- **Timeout:** 10 seconds
- **Traces to:** REQ-002

#### SMOKE-003: Core API responds
- **Check:** GET /api/users (authenticated) returns 200
- **Timeout:** 10 seconds
- **Traces to:** REQ-003

#### SMOKE-004: Database connected
- **Check:** Any database query succeeds
- **Timeout:** 5 seconds
- **Traces to:** Infrastructure
```

**Key rules for smoke tests:**
- Only critical paths (not comprehensive)
- Fast execution (under 60 seconds total)
- Run after every deployment
- Binary pass/fail (no partial success)

---

## Load/Stress Tests

Use the template from `templates/load-test-plan.md` as the output format.

**Purpose:** Verify performance under realistic and peak load.

**What to include:**

```markdown
### Load/Stress Tests

#### LOAD-001: Registration endpoint under load
- **Tool:** k6 / artillery
- **Endpoint:** POST /api/users
- **Scenarios:**
  - Normal load: 50 concurrent users, 5 min duration
  - Peak load: 200 concurrent users, 2 min duration
  - Stress: Ramp to 500 concurrent users, find breaking point
- **Thresholds:**
  - p95 response time < 500ms under normal load
  - p99 response time < 2000ms under peak load
  - Error rate < 1% under normal load
  - Error rate < 5% under peak load
- **Traces to:** NFR-001 (performance requirements)

#### LOAD-002: Authentication endpoint under load
- **Tool:** k6 / artillery
- **Endpoint:** POST /api/auth/login
- **Scenarios:**
  - Normal load: 100 concurrent users, 5 min duration
  - Peak load: 500 concurrent users, 2 min duration
- **Thresholds:**
  - p95 response time < 200ms under normal load
  - Error rate < 0.1% under normal load
- **Traces to:** NFR-001
```

**Key rules for load tests:**
- Define specific thresholds (not "should be fast")
- Test against realistic data volumes
- Include ramp-up period
- Test the most-called endpoints
- Only include if project profile indicates load testing is relevant

---

## API Contract Tests

**Purpose:** Verify frontend and backend agree on API shapes.

**What to include:**

```markdown
### API Contract Tests

#### CONTRACT-001: POST /api/users request/response shape
- **File:** tests/contract/auth/users.contract.test.ts
- **Contract source:** api-contract.md
- **Validates:**
  - Request body schema matches contract (required fields, types)
  - Success response (201) body schema matches contract
  - Error response (400) body schema matches contract
  - Error response (409) body schema matches contract
- **Traces to:** api-contract.md, POST /api/users

#### CONTRACT-002: GET /api/users/:id response shape
- **File:** tests/contract/auth/users.contract.test.ts
- **Contract source:** api-contract.md
- **Validates:**
  - Response (200) body schema matches contract
  - Response (404) body schema matches contract
  - All fields present with correct types
- **Traces to:** api-contract.md, GET /api/users/:id
```

**Key rules for contract tests:**
- Validate exact shapes (field names, types, required vs optional)
- Test all status codes defined in the contract
- Run on both frontend and backend independently
- Fail if contract changes without corresponding code change