# E2E Test Plan

# E2E Test Plan

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

## 1. E2E Testing Objectives

<!-- GUIDANCE: E2E tests are expensive to write and maintain. Be clear about what value they provide and limit scope to what matters most. -->

**Objectives:**
1. Validate that the {{COUNT}} most critical user journeys work end-to-end in a production-like environment
2. Catch integration failures between frontend, backend, and third-party services that unit/integration tests cannot detect
3. Provide confidence before every production deployment
4. Serve as living documentation of critical user flows

**What E2E tests are NOT for:**
- Complete feature coverage (that's for unit/integration tests)
- Testing every error state (too expensive to maintain)
- Performance benchmarking (use performance tests)
- Visual pixel-perfection (use visual regression tests separately)

---

## 2. Critical User Journeys

<!-- GUIDANCE: Define each journey as the user sees it, not the technical steps. Prioritize by business impact. -->

### Journey 1: {{JOURNEY_1_NAME}}

| Field | Value |
|-------|-------|
| **Priority** | Critical |
| **Business Impact** | {{IMPACT}} <!-- e.g., "Core revenue path" --> |
| **Frequency** | {{FREQUENCY}} <!-- How often real users do this --> |
| **Test File** | `{{TEST_PATH}}` |

**Steps:**
1. {{STEP_1}} <!-- e.g., "User lands on homepage" -->
2. {{STEP_2}} <!-- e.g., "Searches for a product" -->
3. {{STEP_3}} <!-- e.g., "Selects and adds to cart" -->
4. {{STEP_4}} <!-- e.g., "Proceeds to checkout" -->
5. {{STEP_5}} <!-- e.g., "Completes payment with test card" -->
6. {{STEP_6}} <!-- e.g., "Sees order confirmation" -->

**Assertions:**
- {{ASSERTION_1}} <!-- e.g., "Confirmation email trigger verified" -->
- {{ASSERTION_2}} <!-- e.g., "Order appears in user account" -->
- {{ASSERTION_3}} <!-- e.g., "Inventory decremented correctly" -->

---

### Journey 2: {{JOURNEY_2_NAME}}

| Field | Value |
|-------|-------|
| **Priority** | Critical |
| **Business Impact** | {{IMPACT}} |
| **Frequency** | {{FREQUENCY}} |
| **Test File** | `{{TEST_PATH}}` |

**Steps:**
1. {{STEP_1}}
2. {{STEP_2}}
3. {{STEP_3}}

<!-- TODO: Add all critical user journeys. Typical minimum: registration, login, core workflow, payment/conversion, logout -->

---

### All Journeys Summary

<!-- GUIDANCE: Once all journeys are defined above, populate this summary table. -->

| Journey | Priority | Est. Duration | Automated | Last Pass |
|---------|----------|--------------|-----------|-----------|
| {{JOURNEY_1_NAME}} | Critical | {{DURATION}}s | Yes | {{DATE}} |
| {{JOURNEY_2_NAME}} | Critical | {{DURATION}}s | Yes | {{DATE}} |
| User registration + email verification | Critical | 60s | Yes | — |
| Password reset flow | High | 45s | Yes | — |
| Account settings update | Medium | 30s | Yes | — |

---

## 3. Browser & Device Matrix

<!-- GUIDANCE: Define the minimum browser/device coverage required. Balance coverage vs maintenance cost. -->

### Desktop Browsers

| Browser | Version | OS | Priority | Notes |
|---------|---------|-----|----------|-------|
| Chrome | Latest stable | Windows, macOS | Critical | Highest market share |
| Firefox | Latest stable | Windows, macOS | High | |
| Safari | Latest stable | macOS | High | WebKit engine |
| Edge | Latest stable | Windows | Medium | Chromium-based |

### Mobile Browsers

| Browser | Platform | Version | Priority | Notes |
|---------|----------|---------|----------|-------|
| Safari | iOS | Latest | Critical | Highest mobile share |
| Chrome | Android | Latest | Critical | |

### Screen Resolutions

| Category | Resolution | Test Priority |
|----------|------------|--------------|
| Desktop HD | 1920×1080 | Critical |
| Desktop | 1366×768 | High |
| Laptop | 1280×800 | Medium |
| Tablet (landscape) | 1024×768 | High |
| Mobile L | 428×926 | Critical |
| Mobile M | 375×667 | Critical |

**Matrix in CI:** Run Critical priority browser/resolution combinations on every deployment. Full matrix on nightly schedule.

---

## 4. Test Data Setup & Teardown

<!-- GUIDANCE: E2E tests must be idempotent — they should work the same way every time, regardless of order. -->

### Setup Strategy

| Data Type | Method | Scope |
|-----------|--------|-------|
| Test user accounts | Pre-seeded before test run | Test suite |
| {{DATA_TYPE}} | Created via API in `beforeAll` | Test suite |
| Isolated test data | Created via API in `beforeEach` | Individual test |

**Seed command:** `bash scripts/e2e-seed.sh {{ENVIRONMENT}}`
**Seed verification:** `bash scripts/verify-seed.sh {{ENVIRONMENT}}`

### Teardown Strategy

| Cleanup Item | Method | Trigger |
|-------------|--------|---------|
| Test-specific records | DELETE via API | `afterEach` |
| Test session data | Clear browser storage | `afterEach` |
| Emails in test inbox | API clear | `afterAll` |
| Payment test data | Stripe test mode auto-cleanup | Daily job |

**Rule:** Tests must not leave state that affects other tests. Tests must be executable in any order.

### Test Accounts

<!-- GUIDANCE: Maintain dedicated test accounts. Never use accounts that could be mistaken for real users. -->

| Account | Email | Role | Purpose |
|---------|-------|------|---------|
| Standard user | `e2e-user@test.{{DOMAIN}}` | User | Standard journeys |
| Admin user | `e2e-admin@test.{{DOMAIN}}` | Admin | Admin panel journeys |
| {{ROLE}} user | `e2e-{{ROLE}}@test.{{DOMAIN}}` | {{ROLE}} | {{PURPOSE}} |

Credentials stored in: {{CREDENTIAL_STORE}} (never hardcoded in tests)

---

## 5. Authentication Handling in Tests

<!-- GUIDANCE: Repeated login UI flows waste test time. Use API-based auth where possible. -->

**Strategy:** {{AUTH_STRATEGY}} <!-- API-based auth / UI login once + save state / Cookie injection -->

**Recommended approach (Playwright):**
```typescript
// tests/fixtures/auth.ts
// Authenticate via API, save storage state
// Reuse state across tests in the same suite
// Only use UI login when testing the login flow itself
```

**Session reuse:**
- Session state saved per role after first auth
- Reused for all tests requiring that role
- Invalidated and refreshed if expired

---

## 6. Test Environment Requirements

<!-- GUIDANCE: E2E tests need a stable, production-like environment. Document exact requirements. -->

| Requirement | Specification |
|-------------|--------------|
| Environment | Staging (`staging.{{DOMAIN}}`) |
| Database | Dedicated E2E database, seeded before run |
| External services | Sandbox / test mode (Stripe test, email sandbox) |
| Stability | No active deployments during E2E run |
| Data persistence | Isolated — not shared with manual testing |
| Response times | < {{TIMEOUT}}s for all endpoints (E2E assertions time out at 2× this) |

**Environment locking:** CI acquires a lock before E2E run to prevent concurrent deployments
**Lock mechanism:** {{LOCK_MECHANISM}}

---

## 7. Flaky Test Management Strategy

<!-- GUIDANCE: Flaky tests destroy trust in the test suite. They must be managed systematically. -->

**Definition:** A test that fails inconsistently for the same code

**Prevention:**
- Use explicit waits (not `sleep`) — wait for elements/network, not time
- Isolate test data (no shared state between tests)
- Use retry-on-assertion, not retry-on-run
- Avoid animation timing issues with `prefers-reduced-motion` in test env

**Detection:**
- Track flakiness rate per test in CI
- Any test failing > {{FLAKY_THRESHOLD}}% of runs without code changes = flaky

**Response:**
- Immediately tag flaky test with `@flaky` annotation
- Create bug ticket with priority based on journey criticality
- Quarantine (run separately, don't block CI) while fixing
- Fix within {{FLAKY_FIX_SLA}} days or remove the test
- Monthly flaky test review

---

## 8. Visual Regression Testing

<!-- GUIDANCE: Visual regression catches unintended UI changes. Run on UI-touching PRs. -->

**Tool:** {{VIS_TOOL}} <!-- Playwright screenshots / Percy / Chromatic / Storybook visual tests -->
**Baseline:** Stored in {{BASELINE_STORAGE}}
**Threshold:** Allow up to {{VIS_THRESHOLD}}% pixel difference for font rendering

| Check | Scope | Trigger |
|-------|-------|---------|
| Full page screenshots | Critical pages | UI-touching PRs |
| Component snapshots | UI components | Component changes |
| Responsive layout | Mobile + desktop | Layout changes |

**Review process:** Visual diffs in PR requiring explicit approval before merge

---

## 9. Performance Assertions Within E2E

<!-- GUIDANCE: Basic performance checks within E2E catch obvious regressions without full load testing. -->

| Assertion | Metric | Threshold | Journey |
|-----------|--------|-----------|---------|
| Page load | Time to Interactive | < {{TTI}}ms | All critical pages |
| Core Web Vitals — LCP | Largest Contentful Paint | < {{LCP}}ms | Homepage, landing pages |
| Core Web Vitals — CLS | Cumulative Layout Shift | < {{CLS}} | All pages |
| API response | Time in test assertions | < {{API_TIMEOUT}}ms | All API calls |

---

## 10. CI Integration

<!-- GUIDANCE: E2E tests in CI must be fast enough to provide timely feedback while being thorough. -->

**Trigger:** Post-staging deployment

**Parallelization:**
- Test sharding: {{SHARD_COUNT}} shards
- Browser parallelism: {{BROWSER_WORKERS}} workers per shard
- Estimated total time: {{E2E_TOTAL_TIME}} minutes

**CI configuration:**
```yaml
# Reference: {{CI_CONFIG_PATH}}
# Key settings:
# - Shards: {{SHARD_COUNT}}
# - Retries: {{RETRY_COUNT}} (for non-flaky tests only)
# - Timeout per test: {{TEST_TIMEOUT}}ms
# - Timeout total: {{SUITE_TIMEOUT}}min
```

**On failure:**
- Collect screenshots, videos, traces as artifacts
- Retain artifacts for {{ARTIFACT_RETENTION}} days
- Alert Slack channel `#e2e-failures`

---

## 11. Test Report Format & Artifacts

<!-- GUIDANCE: Good test reports help debug failures quickly without having to re-run locally. -->

**Report format:** {{REPORT_FORMAT}} <!-- HTML / JUnit XML / Allure -->
**Report location:** {{REPORT_URL}} or CI artifacts

**Artifacts collected on failure:**

| Artifact | Format | When Collected |
|----------|--------|----------------|
| Screenshot | PNG | On step failure |
| Screen recording | WebM video | On test failure |
| Network trace | HAR file | On test failure |
| Browser console log | JSON | On test failure |
| Playwright trace | `.zip` (trace viewer) | On test failure |

---

## 12. Maintenance Strategy

<!-- GUIDANCE: E2E tests rot quickly. Define how you keep them maintained. -->

**Page Object Pattern:**
- All page interactions wrapped in Page Object classes
- Selectors centralized — change in one place
- Location: `tests/e2e/pages/`

**Selector strategy:**
1. `data-testid` attributes (preferred — stable, intent-clear)
2. ARIA roles + accessible name (good for accessibility alignment)
3. Text content (acceptable for static text)
4. CSS class names (avoid — coupled to styling)
5. XPath (never — fragile)

**Review cadence:**
- Test suite reviewed monthly for relevance
- Remove tests for deprecated features immediately
- Update tests before merging feature changes (tests are part of the PR)

---

## Related Documents

- [Test Strategy](./test-strategy.md)
- [Test Plan](./test-plan.md)
- [Test Case Template](./test-case-template.md)
- [CI/CD Pipeline](../INFRASTRUCTURE/cicd-pipeline.md)

---

## Approval
| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Approver | | | |