p19-bug-fixes

e2e/docs/test-strategy.md

@@ -0,0 +1,185 @@
+# 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