Initial Commit

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

@@ -0,0 +1,80 @@
+# 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/`.