suaveplan/openspec/changes/enterprise-testing-visual-regression/tasks.md

Tasks

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Catalog and dependency wiring

• 1.1 Add @storybook/test-runner to catalogs.testing in root /mnt/s/web/genesis/package.json (exact version, no bare strings).
• 1.2 Add the catalog ref to packages/testing/testing-dom/package.json dependencies.
• 1.3 Confirm Playwright already provides the e2e screenshot comparator — no extra dep for testing-e2e.
• 1.4 Run the nuclear clean install per openspec/AGENTS.md §1.

2. e2e visual helpers (@suaveplan/testing-e2e)

• 2.1 Create packages/testing/testing-e2e/src/visual/configure-visual-regression.ts exporting configureVisualRegression(config?).
• 2.2 Create src/visual/prepare-for-visual.ts exporting prepareForVisual(page) — disables animations, waits networkidle, awaits document.fonts.ready, sets prefers-reduced-motion: reduce.
• 2.3 Add VisualRegressionError subclass with codes TESTING_E2E.VISUAL.PIXEL_DIFF_EXCEEDED, BASELINE_MISSING, FONTS_NOT_READY, VIEWPORT_MISMATCH.
• 2.4 Add Zod schemas in sibling *.schemas.ts.
• 2.5 Add types in sibling *.types.ts.

3. Storybook visual helpers (@suaveplan/testing-dom)

• 3.1 Create packages/testing/testing-dom/src/storybook-visual/create-storybook-test-runner-config.ts.
• 3.2 Create src/storybook-visual/pin-story-environment.ts.
• 3.3 Add StorybookVisualError subclass with codes TESTING_DOM.STORYBOOK_VISUAL.PIXEL_DIFF_EXCEEDED, BASELINE_MISSING, RUNNER_LOAD_FAILED.
• 3.4 Add Zod schemas + types siblings.

4. Tests

• 4.1 Unit tests for configureVisualRegression — defaults, overrides, viewport pinning.
• 4.2 Unit tests for prepareForVisual — fonts.ready awaited, motion forced, network idle observed.
• 4.3 Integration test capturing a known-stable fixture page and comparing to a committed baseline.
• 4.4 Storybook unit tests for createStorybookTestRunnerConfig and pinStoryEnvironment.
• 4.5 Cross-cutting test: baselines stored under __snapshots__/<platform>/.
• 4.6 Property test over the threshold predicate using fast-check.

5. Docs

• 5.1 Sibling .md for each implementation file (≥200 words, basic + advanced examples, full API reference, implementation notes).
• 5.2 Update packages/testing/testing-e2e/README.md and packages/testing/testing-dom/README.md Modules sections.
• 5.3 Add a baseline-update workflow section to each README (separate review-tagged commits, never squashed into feature commits).

6. Subpath exports

• 6.1 Add "./visual/configure-visual-regression" and "./visual/prepare-for-visual" to testing-e2e/package.json exports.
• 6.2 Add "./storybook-visual/create-storybook-test-runner-config" and "./storybook-visual/pin-story-environment" to testing-dom/package.json exports.
• 6.3 Verify subpath count matches feature module count for both packages.

7. Adoption

• 7.1 Wire configureVisualRegression() into apps/testbed/playwright.config.ts.
• 7.2 Add expect(page).toHaveScreenshot() calls to every page-level spec in apps/testbed/e2e/.
• 7.3 Wire createStorybookTestRunnerConfig() into the Storybook test-runner script.
• 7.4 Update the existing ThemeDecorator and LocaleDecorator to honour pinStoryEnvironment.
• 7.5 Generate initial baselines on linux; commit under __snapshots__/linux/.
• 7.6 Cross-link the release-readiness gate in ../enterprise-testbed-verification so visual diffs fail the gate.

8. CI matrix

• 8.1 Add ubuntu-latest (linux) baseline lane.
• 8.2 Add macos-14 (darwin) lane — generate and commit darwin baselines on first run.
• 8.3 Document the windows-latest decision (gate or skip-with-warning) in apps/testbed/README.md.

9. Pre-publish gate

• 9.1 bunx turbo lint typecheck test --filter=@suaveplan/testing-e2e green.
• 9.2 bunx turbo lint typecheck test --filter=@suaveplan/testing-dom green.
• 9.3 bunx turbo test:coverage --filter=@suaveplan/testing-e2e at 100%.
• 9.4 bunx turbo test:coverage --filter=@suaveplan/testing-dom at 100%.
• 9.5 Banned-pattern scan clean.
• 9.6 Missing-.md scan clean.

10. Spec archive

• 10.1 Fold specs/testing-e2e/spec.md deltas into openspec/specs/testing-e2e/spec.md.
• 10.2 Fold specs/testing-dom/spec.md deltas into openspec/specs/testing-dom/spec.md.
• 10.3 Move this folder to openspec/archive/<yyyy-mm-dd>-enterprise-testing-visual-regression/.