X2 — E2E flow tests + a11y pass (5 critical flows + WCAG 2.1 AA)

[Luis85]

Parent epic: #326 · Depends on: V1–V9 (verticals must be implementable end-to-end for the flows to run) · Stories: All 22 MVP stories (validation only — no new feature stories)

Problem

Unit and component tests cover each component in isolation, but the MVP's value emerges from cross-component lifecycles (proposal → merged PR, multi-issue nav with state preservation, task → agent chat, activity-feed navigation, PR merge gate). A11y is also a non-functional MVP requirement that we have not validated end-to-end.

Solution

A. Five Storybook + Playwright E2E flows

Under tests/e2e/:

1. ProposalLifecycleFlow.e2e.ts — agent creates 3 proposals on issue feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191 → user accepts 1, rejects 1, accepts the last → section header reads "✓ All reviewed" → accepted proposals appear in Related Files → reload plugin → state preserved (validates X1 too).
2. PRMergeGateFlow.e2e.ts — open PR with reviewStatus='review-required' → Merge button hidden → Approve → Merge unlocks (because CI is passing) → Merge → 800ms transition → PR row pill in sidebar → purple ✓ → breadcrumb back-nav to parent issue works.
3. MultiIssueNavigationFlow.e2e.ts — open issue feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191 (right=tasks) → click PR docs: define Specorator product vision #45 from Related Files → main=pr, right=pr → back to issue → right=tasks preserved → navigate to issue feat(plugin-shell): MCP server — workflow tools (6 tools) #192 via sidebar → no feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191 state leakage. Validates the sidebar active-row sync (Handoff's explicit warning).
4. TaskAgentChatFlow.e2e.ts — open issue feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191 → click in-progress task → main=task, right=agents → click agent → right=agent, messages stream in → user types message + Enter → optimistic append → back to agents list → unsubscribed cleanly.
5. ActivityFeedNavigationFlow.e2e.ts — open Activity Feed → click "Agent X completed task on issue feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191" → main=issue with active sidebar row → click "PR docs: define Specorator product vision #45 merged" event → main=pr, right=pr → each event-type→destination mapping validated.

Each flow uses tests/__fixtures__/specorator-mvp/ from F4. No real GitHub or agent runtime — Mock adapters from F3.

B. A11y audit + remediation

• Storybook a11y addon enabled with WCAG 2.1 AA ruleset; all atoms + components must pass with zero violations
• Manual keyboard-only walkthrough of each critical flow above; document any escapes in docs/a11y-checklist.md
• Required fixes:
  • Focus traps on all modals + LIFO Esc (validated by V9 but tested end-to-end here)
  • role="list" + role="listitem" + aria-selected on sidebar
  • aria-current="page" on terminal breadcrumb crumb
  • role="log" + aria-live="polite" on AgentChat message container
  • aria-label on every icon-only badge / button (status dots, draft/merged glyphs)
  • Reduced-motion respect for the breakdown-card delay, merge transition, typing indicator
• Color-contrast verification for the token map (F4): every --sp-* token meets WCAG AA against its expected background

C. Performance smoke tests

• Sidebar with 200 issues: paint < 100ms in Chromium headless
• Activity feed with 500 events: append-new without scroll-reset, scroll jank < 16ms / frame
• Agent chat with 200 messages: append-new at 60fps

Defer large-scale virtualization to X3; X2 sets the smoke baseline.

Acceptance criteria

• All five E2E flows exist under tests/e2e/ and pass via Playwright
• npm run test:storybook runs the a11y addon with zero violations on every story
• Manual keyboard walkthrough documented in docs/a11y-checklist.md with a screenshot per flow
• All required ARIA / aria-label fixes applied in the V-issue components
• Reduced-motion media query respected for animations
• Color-contrast script verifies all --sp-* tokens against expected backgrounds
• Performance smoke tests pass on the thresholds above
• npm run typecheck, npm run lint, npm run test, npm run test:storybook pass
• Coverage thresholds (80/70/80/80) hold

Out of scope

• Browser matrix beyond Chromium (Obsidian's runtime)
• Production-adapter tests (those are X3)
• Visual regression beyond a11y + smoke (out-of-band Percy snapshots are nice-to-have, not required)

Affected files

File	Action
tests/e2e/ProposalLifecycleFlow.e2e.ts	New
tests/e2e/PRMergeGateFlow.e2e.ts	New
tests/e2e/MultiIssueNavigationFlow.e2e.ts	New
tests/e2e/TaskAgentChatFlow.e2e.ts	New
tests/e2e/ActivityFeedNavigationFlow.e2e.ts	New
tests/performance/*.test.ts	New (3 smoke tests)
docs/a11y-checklist.md	New
scripts/check-token-contrast.ts	New
V-issue component files	Apply ARIA / keyboard fixes

References

• inputs/specorator-mvp-design-2026-05/SYNTHESIS.md §"Cross-cutting concerns" — a11y items
• QA review §"Cross-Component / E2E Flows" (the five flows above are directly from there)
• ADR-009 testing conventions

[Luis85]

Cross-cutting review (X2) — readiness: M, headline finding: per-flow V-issue dependency map is missing, a11y-addon failure → CI failure wiring is unspecified, and tests/e2e/ is greenfield (no existing pattern to copy).

Review findings

1. tests/e2e/ is brand-new ground. Verified there's no existing tests/e2e/ directory in the repo. ADR-009 covers Vitest + Storybook conventions but doesn't yet cover Playwright runners. Decisions to land before writing flows: (a) Playwright config location (playwright.config.ts at repo root or under tests/e2e/); (b) Storybook test-runner vs. raw Playwright + Vite dev server — the npm run test:storybook script already targets Storybook/Playwright per CLAUDE.md, so prefer the test-runner so a11y addon runs against the same render path. (c) data-testid policy is already enforced by ESLint per ADR-009 — extend to e2e too.

2. "No real GitHub" means which adapter is wired? The flows must run against MockGitHubAdapter + MockAgentRuntimeAdapter from F3, with the proposal repo backed by a vault fake (so X1's persistence is actually exercised by ProposalLifecycleFlow.e2e.ts). For Storybook this means a top-level decorator that injects mock ports via the InjectionKeys at src/infrastructure/bridge/ports.ts. Make this a single shared decorator (tests/e2e/decorators/mock-ports.ts) — not per-story wiring.

3. a11y addon → CI failure. Storybook's @storybook/addon-a11y reports violations to the UI by default but does not fail the test runner unless you wire it via @storybook/test-runner's preVisit/postVisit hooks calling axe-playwright's checkA11y (or the addon's own getA11yReport). Add a tests/storybook-runner.ts (referenced via STORYBOOK_TEST_RUNNER_CONFIG) that throws on violations of impact serious or critical. Color-contrast violations should fail the build. Cosmetic ARIA-completeness lints (e.g. region) can be allowlisted but documented in docs/a11y-checklist.md.

4. Fixture wiring. F4's tests/__fixtures__/specorator-mvp/ is the canonical fixture root. Each e2e flow should import factory helpers (createIssue, createProposal, etc.) rather than literal JSON — so when the domain shape evolves the flows refactor instead of silently passing on stale data. Include a seed.ts per flow that documents the starting state in comments.

5. Performance smoke thresholds. "Paint < 100ms" / "scroll jank < 16ms / frame" need a measurement method. Recommend Playwright's page.metrics() + performance.now() deltas, captured during a page.evaluate. 60fps assertion via requestAnimationFrame sampling for ≥500ms. Failure-mode unknown: a flaky smoke test will block CI — set per-flow retries to 2 with an explicit // FIXME: flaky ban.

6. Reduced-motion verification. Use page.emulateMedia({ reducedMotion: 'reduce' }) in a dedicated e2e variant and assert that the breakdown-card 700ms delay, merge transition, and typing indicator are skipped (snapshot DOM at t=0 vs. t=100ms).

EARS requirements

• REQ-MVP-X2-001 — While the Storybook test runner is executing any story, the system shall fail the test run if the a11y addon reports any serious or critical WCAG 2.1 AA violation.
• REQ-MVP-X2-002 — When ProposalLifecycleFlow.e2e.ts reloads the plugin after accepting/rejecting proposals, the system shall restore the exact set of pending/accepted/rejected proposals from the previous session.
• REQ-MVP-X2-003 — When PRMergeGateFlow.e2e.ts invokes Merge before both reviewStatus === 'approved' and checks === 'passing', the system shall reject the merge at the use-case layer with a MergeGateNotSatisfied error.
• REQ-MVP-X2-004 — While the prefers-reduced-motion: reduce media query is active, the system shall complete state transitions in a single frame without enter/exit animations.
• REQ-MVP-X2-005 — When the user navigates from issue feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191 to issue feat(plugin-shell): MCP server — workflow tools (6 tools) #192 via the sidebar, the system shall not leak any panel state from feat(plugin-shell): MCP server — write proposal queue (PendingProposal mechanism) #191 (right-panel mode reset to default).
• REQ-MVP-X2-006 — When tests/performance/sidebar.test.ts renders 200 issues, the system shall complete first paint in under 100ms in the Chromium CI environment.

Acceptance-criteria additions

• playwright.config.ts committed; npm run test:e2e script added; CI runs it as part of npm run verify.
• Storybook test-runner config fails on serious/critical axe violations; allowlist (if any) documented in docs/a11y-checklist.md.
• Each e2e flow imports from tests/__fixtures__/specorator-mvp/factories.ts, not literal JSON.
• Mock-port decorator file: tests/e2e/decorators/mock-ports.ts, reused by every flow.
• Reduced-motion variant of PRMergeGateFlow confirms zero animation latency.
• Performance smokes measure via performance.now() + RAF sampling, with retries=2 and explicit thresholds.
• CI artifact: a11y violations report uploaded as a Storybook test-runner artifact for each PR.

Dependency cross-check

Depends on: V1–V9 — broadly correct, but per flow:

Flow	Strictly requires merged
ProposalLifecycleFlow	V3 (issue workspace), V9 (DiffModal proposal variant), X1 (persistence reload)
PRMergeGateFlow	V4 (PR detail), V8 (PR panel + merge gate), V2 (breadcrumb)
MultiIssueNavigationFlow	V1 (sidebar), V2 (breadcrumb), V3, V4, V6 (right=tasks default)
TaskAgentChatFlow	V3, V6 (tasks panel), V7 (agents + chat)
ActivityFeedNavigationFlow	V1 (sidebar entry), V5 (activity feed), V3 + V4 (destinations)

X1 is a real dependency for ProposalLifecycleFlow's reload step — list it explicitly.

Test strategy

• Storybook test-runner runs unit + a11y + smoke on every PR.
• Playwright runs the 5 flow files headless in CI; with retries=2.
• Token-contrast script (scripts/check-token-contrast.ts) runs as part of npm run verify; reads src/ui/styles/specorator-tokens.css, asserts each --sp-* foreground token meets ≥4.5:1 against documented background token.
• Coverage thresholds (80/70/80/80) unaffected by e2e (e2e tests aren't part of vitest coverage).

Risks / unknowns (need decisions before implementation)

• Playwright in CI — npm run test:storybook already requires Chromium; confirm the GitHub Actions runner image includes it or document npx playwright install --with-deps chromium.
• a11y allowlist policy — who reviews waivers? Recommend QA reviewer approval required for each entry in docs/a11y-checklist.md.
• Flaky-test policy — a flow that's flaky 1/20 should block, not flake-pass. Confirm zero-flake target.

---

Generated by Claude Code