clawfort/e2e/docs/test-strategy.md

# ClawFort UI/UX Test Strategy

## Capability-to-Test Mapping

This document maps OpenSpec capabilities to Playwright test coverage.

### New Capabilities

#### `playwright-ui-ux-regression-suite`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Capability-mapped suite execution | All files | Tests organized by capability in directory structure |
| Theme and breakpoint matrix coverage | `responsive/*.spec.ts`, `accessibility/*.spec.ts` | Cross-theme and cross-viewport test execution |
| Failure artifact collection | `playwright.config.ts` | Trace, screenshot, video on failure enabled |

### Modified Capabilities

#### `end-to-end-system-testing`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Core user flow E2E | `core-journeys/hero-feed.spec.ts` | Hero loading, feed browsing, modal flows |
| Browser-native interaction E2E | `modal-experience/*.spec.ts` | Modal open/close, source links, share actions |
| Edge-case workflows | `core-journeys/edge-cases.spec.ts` | Empty data, invalid permalinks, error states |
| UI failure-path resilience | `accessibility/modal.spec.ts` | Fallback messages, navigable error states |

#### `platform-quality-gates`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Release quality gates | CI workflow | Smoke profile gates PR, full profile gates main |
| Playwright gate failure blocks release | CI workflow | Fail-on-regression policy enforced |
| Gate manifest | `playwright.config.ts` | Explicit browser/tool versions |
| Gate profiles documented | This file | Smoke vs full profile criteria defined |

#### `wcag-2-2-aa-accessibility`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Keyboard-only interaction flow | `accessibility/keyboard.spec.ts` | Modal navigation, icon-only controls, focus visibility |
| Contrast and non-text alternatives | `accessibility/contrast.spec.ts` | Color contrast assertions across themes |
| Accessibility CI gate | CI workflow | Automated accessibility checks in pipeline |
| Interactive accessibility states | `accessibility/states.spec.ts` | Focus-visible, keyboard traversal, accessible names |

#### `responsive-device-agnostic-layout`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Mobile layout behavior | `responsive/breakpoints.spec.ts` | No overflow, reachable controls |
| Desktop and tablet adaptation | `responsive/breakpoints.spec.ts` | Layout reflow, no clipping |
| Sticky shrinking glass header | `responsive/sticky.spec.ts` | Header behavior across scroll |
| Sticky footer overlap | `responsive/sticky.spec.ts` | Content readability, control accessibility |
| Breakpoint regression matrix | `responsive/*.spec.ts` | Overflow/clipping detection across breakpoints |

#### `summary-modal-experience`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Open summary modal | `modal-experience/summary.spec.ts` | Modal opens with correct content order |
| Close summary modal | `modal-experience/summary.spec.ts` | Modal dismisses, returns to feed |
| Permalink-driven modal open | `modal-experience/deep-link.spec.ts` | Direct article URL opens modal |
| Keyboard dismissal and focus continuity | `modal-experience/summary.spec.ts` | Escape closes, focus returns |
| Source link-out from modal | `modal-experience/summary.spec.ts` | Source opens in new tab |
| Modal exposes share entry points | `modal-experience/summary.spec.ts` | Share controls available |
| Modal interaction regression coverage | `modal-experience/*.spec.ts` | All entry paths tested |

#### `share-and-contact-microinteractions`
| Requirement | Test File | Scenarios |
|-------------|-----------|-----------|
| Supported share providers | `microinteractions/share.spec.ts` | X, WhatsApp, LinkedIn icons present |
| Light-theme icon visibility | `microinteractions/share.spec.ts` | Contrast, keyboard focusability |
| Copy-link share action | `microinteractions/share.spec.ts` | Clipboard write, no navigation |
| Share controls state accessibility | `microinteractions/share.spec.ts` | States perceivable across themes |
| Config present/absent footer links | `microinteractions/footer.spec.ts` | GitHub/contact conditional rendering |
| Contact link visible when configured | `microinteractions/footer.spec.ts` | CONTACT_EMAIL shows affordance |
| Randomized helper tooltip | `microinteractions/tooltip.spec.ts` | Hover shows safe message |
| Keyboard-triggered helper tooltip | `microinteractions/tooltip.spec.ts` | Focus shows tooltip, blur dismisses |

## Scenario Taxonomy

### Journey Scenarios
- Hero article loading and display
- Feed browsing and pagination
- Modal open/close from hero
- Modal open/close from feed
- Source link navigation
- Deep-link direct modal open

### Accessibility-State Scenarios
- Keyboard navigation through all interactive elements
- Focus-visible indicators on all controls
- Color contrast for text and UI components
- Accessible names for icon-only controls
- Screen reader compatibility for dynamic content

### Responsive Scenarios
- Mobile viewport (375x667): No horizontal overflow, touch targets sized
- Tablet viewport (768x1024): Layout reflow, readable content
- Desktop viewport (1280x720): Full layout, all features accessible
- Widescreen viewport (1920x1080): Max-width constraints

### Modal Scenarios
- Summary modal: Open from hero, open from feed, open from permalink
- Policy modals: Terms, Attribution, open/close, escape key
- Focus containment within modals
- Focus return on modal close

### Microinteraction Scenarios
- Share button hover/focus states
- Copy link success feedback
- Contact tooltip hover/move/leave
- Contact tooltip keyboard focus/blur
- Back-to-top visibility on scroll
- Theme switch animation

### Deep-Link Scenarios
- Valid article permalink opens modal
- Invalid article permalink shows error state
- Policy permalink opens policy modal
- Hash-based navigation

## Execution Profiles

### Smoke Profile
**Trigger:** Pull request validation
**Duration:** ~2-3 minutes
**Browsers:** Chromium only
**Coverage:**
- Hero loads with content
- Feed displays articles
- Modal opens and closes
- Basic keyboard navigation
- One theme (dark)
- One viewport (desktop)

### Full Profile
**Trigger:** Main branch merge, nightly builds
**Duration:** ~15-20 minutes
**Browsers:** Chrome, Firefox, Safari
**Coverage:**
- All journey scenarios
- All accessibility scenarios across themes
- All responsive breakpoints
- All modal interaction paths
- All microinteraction states
- Cross-browser compatibility

## CI Integration

### Pull Request Quality Gate
```yaml
- name: Playwright Smoke Tests
  run: npm run test:smoke
  env:
    BASE_URL: http://localhost:8000
  continue-on-error: false
```

### Main/Nightly Pipeline
```yaml
- name: Playwright Full Regression
  run: npm run test:full
  env:
    BASE_URL: http://localhost:8000
  continue-on-error: false
  
- name: Upload Test Artifacts
  uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-report
    path: e2e/playwright-report/
    retention-days: 30
```

## Test Data Assumptions

Tests assume:
1. Application serves at least one article in hero position
2. Feed contains multiple articles for pagination testing
3. Backend API responds within 5 seconds
4. Images load within 10 seconds (or placeholder shown)
5. No authentication required for public content

## Failure Triage

1. **Smoke test failures:** Block PR merge, immediate investigation required
2. **Full regression failures:** Create issue, assign to UI owner, fix before release
3. **Flaky tests:** Quarantine after 3 consecutive failures, investigate separately
4. **Browser-specific failures:** Check for polyfill or feature support issues