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

- name: Playwright Smoke Tests
  run: npm run test:smoke
  env:
    BASE_URL: http://localhost:8000
  continue-on-error: false

Main/Nightly Pipeline

- 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