---
created_date:
updated_date:
executor:
status: Draft            # Draft | Ready | Implemented | Verified — execution lifecycle
artifact-status: draft   # draft | approved
feature_ids: # comma-separated Feature IDs chained in this scenario
scenario_id:
---

# E2E Web Test Specification: {Scenario Name}

**Scenario**: [{Scenario_ID}]({SCENARIO_LINK})
**Features**: {feature_ids}
**Author**: @[executor]
**Created**: [created_date]
**Status**: [status] (Draft | Ready | Implemented | Verified)

---

## Test Framework

- **Framework**: Playwright
- **Config**: `apps/web/playwright.config.ts`
- **Script Location**: `apps/web/e2e/flows/{scenario-slug}.spec.ts`
- **Run Command**: `yarn e2e:flow:{scenario-slug}`

---

## Browser Matrix

| Browser | Engine | Version | Required |
|---------|--------|---------|----------|
| Chrome | Chromium | Latest | Yes |
| Firefox | Gecko | Latest | Yes |
| Safari | WebKit | Latest | Yes (via Playwright) |
| Edge | Chromium | Latest | No (covered by Chromium) |

---

## Viewport Testing

| Viewport | Width | Height | Test Required |
|----------|-------|--------|---------------|
| Mobile | 375px | 812px | Yes |
| Tablet | 768px | 1024px | Yes |
| Desktop | 1280px | 720px | Yes |
| Large Desktop | 1920px | 1080px | Optional |

---

## Test Cases

### Main Flow

| Test ID | Step | Page | Action | Expected | Browser | Viewport |
|---------|------|------|--------|----------|---------|----------|
| {PROJECT}_E2E_001_H | 1 | {Page} | {Action} | {Expected} | All | All |
| {PROJECT}_E2E_001_H | 2 | {Page} | {Action} | {Expected} | All | All |

### Cross-Browser Specific

| Test ID | Browser | Issue | Test Action | Expected |
|---------|---------|-------|-------------|----------|
| {ID}_BROWSER_001 | Firefox | {Known issue} | {Action} | {Expected} |
| {ID}_BROWSER_002 | WebKit | {Known issue} | {Action} | {Expected} |

### Responsive Specific

| Test ID | Viewport | Component | Test Action | Expected |
|---------|----------|-----------|-------------|----------|
| {ID}_RESP_001 | Mobile | {Nav menu} | {Hamburger menu test} | {Expected} |
| {ID}_RESP_002 | Tablet | {Layout} | {Grid layout test} | {Expected} |

---

## Playwright Configuration

```typescript
// playwright.config.ts additions for this scenario
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './e2e',
  timeout: 30000,
  retries: 1,
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    { name: 'mobile-chrome', use: { ...devices['Pixel 5'] } },
    { name: 'mobile-safari', use: { ...devices['iPhone 13'] } },
  ],
  reporter: [
    ['html', { outputFolder: 'reports/e2e' }],
    ['junit', { outputFile: 'reports/e2e-results.xml' }],
  ],
});
```

---

## Selectors Strategy

| Element Type | Selector Pattern | Example |
|-------------|-----------------|---------|
| Interactive | `data-testid` | `page.getByTestId('login-submit')` |
| Text | `getByText` | `page.getByText('Welcome')` |
| Role | `getByRole` | `page.getByRole('button', { name: 'Submit' })` |
| Label | `getByLabel` | `page.getByLabel('Email')` |

> Prefer `data-testid` for stability. Use semantic selectors (role, label) for accessibility validation.

---

## Network Handling

| Scenario | Mock/Real | Handler |
|----------|-----------|---------|
| API calls | Mock (route intercept) | `page.route('/api/**', handler)` |
| Auth token | From .env | `process.env.TEST_AUTH_TOKEN` |
| Slow network | Simulated | `page.route('**', route => setTimeout(() => route.continue(), 3000))` |
| Offline | Simulated | `context.setOffline(true)` |

---

## Accessibility Checks

- [ ] All interactive elements are keyboard accessible
- [ ] ARIA labels present on custom components
- [ ] Color contrast meets WCAG AA
- [ ] Screen reader navigation works for main flow
- [ ] Focus management correct during navigation

---

## Performance Budgets

| Metric | Target | Measurement |
|--------|--------|-------------|
| Page Load (LCP) | < 2.5s | Playwright metrics |
| Interaction (INP) | < 200ms | Playwright metrics |
| Layout Shift (CLS) | < 0.1 | Playwright metrics |
| JS Bundle | < 300KB | Build output |

---

## Success Criteria

- [ ] All test cases pass on Chromium
- [ ] All test cases pass on Firefox
- [ ] All test cases pass on WebKit
- [ ] All viewport tests pass (mobile, tablet, desktop)
- [ ] No flaky tests (100% pass on 3 runs)
- [ ] Total execution time < {X} minutes
- [ ] Accessibility checks pass
- [ ] Performance budgets met

---

## Changelog

| Date | Changes | Author |
|------|---------|--------|
| [created_date] | Initial web E2E spec created | @[executor] |