suaveplan/openspec/changes/enterprise-browser-storybook-test-utils/tasks.md

Tasks: enterprise-browser-storybook-test-utils

Change ID: enterprise-browser-storybook-test-utils Package: @suaveplan/storybook-test-utils Target path: browser/dev/storybook-test-utils Prerequisite packages on Verdaccio: none (no workspace runtime deps)

---

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. Scaffold

• Create directory tree per proposal.md.
• package.json v0.0.0, "sideEffects": false.
  • dependencies: @suaveplan/logger workspace:^, tslib catalog:build
  • peerDependencies: @playwright/test (move from devDependencies)
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, @playwright/test catalog:testing, @suaveplan/testing workspace:^
  • Subpath exports: ".", "./navigation", "./waiting", "./iframe", "./args", "./interactions", "./forms", "./ports", "./story-index", "./assertions", "./fixtures"
• tsconfig.json, vitest.config.ts (pool: forks).

---

2. Types (src/types/types.ts)

• StoryMetadata, WaitOptions, UrlOptions, StoryIndex, StoryIndexEntry, AxeOptions, AxeResult.
• Write types.md.

---

3. STORYBOOK_PORTS registry (src/ports/)

• registry.ts — STORYBOOK_PORTS: Record<string, number> mapping package names to ports (react-ui=6001, react-audio=6004, react-auth=6010, r3f-camera=6019, etc.); storyUrl(pkg, storyId, opts?).
• Write registry.test.ts (lookup known port, unknown package throws, storyUrl formats correctly). Write registry.md.

---

4. Navigation (src/navigation/)

• navigation.ts — navigateToStory, navigateToStoryWithUI, switchToStory, reloadStory.
• Drive a stub Storybook HTTP server in tests (serve iframe.html + /?path=/story/… fixtures).
• Write navigation.test.ts. Write navigation.md.

---

5. Waiting (src/waiting/)

• waiting.ts — waitForStoryLoaded, waitForStorybookIframe, waitForStoryInteractive.
• Handle SB7 vs SB8 iframe selector differences via auto-detection.
• Write waiting.test.ts. Write waiting.md.

---

6. Iframe access (src/iframe/)

• iframe.ts — getStorybookFrame, getStoryCanvas.
• Write iframe.test.ts. Write iframe.md.

---

7. Args (src/args/)

• args.ts — getStoryArgs, updateStoryArgs<T>.
• Write args.test.ts. Write args.md.

---

8. Interactions (src/interactions/)

• interactions.ts — clickWithFallback, getClickableElement (handles autoplay policies, strict-mode locator).
• Write interactions.test.ts. Write interactions.md.

---

9. Forms (src/forms/)

• forms.ts — getFormFromStory.
• Write forms.test.ts. Write forms.md.

---

10. Story-index discovery (src/story-index/)

• index-loader.ts — loadStoryIndex(baseUrl) fetches index.json; defineStoryId(kind, name) returns canonical ID.
• Write index-loader.test.ts (stub server, parse, missing story throws). Write index-loader.md.

---

11. Assertions (src/assertions/)

• console.ts — expectNoConsoleErrors(page, opts?) captures console logs during test and fails on unexpected errors.
• network.ts — expectNoFailedRequests(page), expectAllFontsLoaded(page).
• a11y.ts — auditAccessibility(page, opts?) runs axe-core in the story iframe; returns AxeResult.
• Write tests for each (stub page + intercepted events). Write .md per module.

---

12. Playwright fixture (src/fixtures/)

• playwright.ts — test.extend({ storybook: [storybookFixture, { scope: 'test' }] }) pre-configured with port registry.
• Write playwright.md.

---

13. Integration test (tests/integration.test.ts)

• Spin up an in-process HTTP server serving stub Storybook HTML.
• Run navigateToStory → waitForStoryLoaded → getStoryCanvas → updateStoryArgs → expectNoConsoleErrors.

---

14. Docs + verify

• Write .md per module (≥200 words, API reference, examples).
• Write README.md with subpath table, port-registry guide, story-index guide, assertion guide.
• bunx turbo lint typecheck test --filter=@suaveplan/storybook-test-utils — green.
• bunx turbo test:coverage — 100% (currently 0%).
• No @ts-expect-error in src/. @playwright/test declared as peerDependency.
• STORYBOOK_PORTS registry replaces at least three consumer hard-coded ports.
• bun scripts/publish.ts --package @suaveplan/storybook-test-utils.
• Archive to openspec/archive/2026-04-24-enterprise-browser-storybook-test-utils/.