playwright-component-testing

1---2name: playwright-component-testing3description: Set up component testing with Playwright using a story gallery — scaffold stories and a gallery dev page driven by the built-in mount fixture, no dedicated component-testing runtime. Use when asked to test React or Vue components in isolation with Playwright, or to migrate off @playwright/experimental-ct-react / -vue.4---5 6# Component Testing with Playwright7 8Test components with regular Playwright e2e tests against a small **story gallery** page hosted by the app's own dev server. No extra test runner, bundler integration or npm packages are required.9 10## Concept11 12- A **story** is a tiny wrapper component that embeds the component under test in one specific scenario: hard-coded props, mock data, providers, recorded callbacks. Stories live next to the component in `*.story.tsx` (or `.ts`/`.jsx`/`.js`/`.vue`) files; each named export is one story.13- The **gallery** is a single page you implement to `references/gallery-spec.md`: it exposes `window.mount(params)` / `window.unmount()` that render a story — resolved from your story files (e.g. with `import.meta.glob`) — into `#root`. It is framework-specific and yours to own — there is no template to copy for it.14- Tests are plain Playwright tests. The built-in **`mount(storyId, props?)` fixture** (from `@playwright/test`) drives the gallery's `window.mount` and returns a `Locator` for the gallery root (`#root`). Scope the queries from there — `component.getByRole('button').click()`, not `component.click()`. Nothing to scaffold for it.15 16Everything the component needs must be set up *inside the story* (it runs in the browser); everything the test asserts must be observable *through the page* (DOM, URL, network). Where the component takes callbacks, the story creates the state, provides the callbacks and records the state into a hidden form for the test to assert on. `mount(id, props)` passes plain serializable `props` to the story.17 18## Setup workflow19 201. **Detect the framework and bundler.** React vs Vue decides the framework notes and example story to follow. Then:21   - **App runs on Vite** (has `vite.config.*`): the gallery is served by the existing dev server at `/playwright/gallery/index.html` — Vite serves any `.html` file under the project root, the app's plugins/aliases/CSS apply automatically, and `vite build` ignores it. No extra server needed.22   - **Anything else** (Next.js, webpack, no dev server): run a small standalone dev server (e.g. Vite) that serves the gallery page, and point `baseURL` at it. Requires `vite` and the framework plugin as devDependencies.232. **Implement the gallery** to `references/gallery-spec.md`: a page at `<project>/playwright/gallery/` that renders the requested story into `#root`. Start from the worked example in the spec and the framework notes in `references/react.md` / `references/vue.md`. Keep story discovery (`import.meta.glob`) and the framework mount here — this is the only framework-specific glue, so keep it small. Import the app's global CSS the same way the app's own entry does.243. **Configure Playwright** — add to `playwright.config.ts`:25 26   ```ts27   projects: [28     {29       name: 'components',30       testDir: './tests/components',31       use: { ...devices['Desktop Chrome'], baseURL: 'http://localhost:5173/playwright/gallery/index.html', serviceWorkers: 'block', reuseContext: true },32     },33   ],34   webServer: {35     command: 'npm run dev',                                       // or: npx vite --config playwright/vite.config.ts36     url: 'http://localhost:5173/playwright/gallery/index.html',   // standalone server: http://localhost:3100/playwright/gallery/index.html37     reuseExistingServer: !process.env.CI,38   },39   ```40 41   Match the port to the dev server. `mount` navigates to `baseURL`, so set `baseURL` to the gallery's URL. `serviceWorkers: 'block'` keeps the app's own service worker from serving cached responses that would shadow your `page.route()` mocks. `reuseContext: true` reuses the browser context across tests in a worker (as the old component-testing runtime did) — a large speedup for component suites. If the config already has projects/webServer, merge instead of replacing.424. **Write a first story** next to an existing component, modeled on `templates/<react|vue>/Button.story.*`.435. **Write a first spec**, modeled on `templates/react/button.spec.ts`, importing `test`/`expect` from `@playwright/test`.446. **Run**: `npx playwright test --project=components`. Open `http://localhost:5173/playwright/gallery/index.html` in a browser to eyeball all stories.45 46## Conventions47 48- Story id: path under `src/` without the `.story.*` extension, plus the export name — `src/components/Button.story.tsx` export `Primary` → `components/Button/Primary`. Any unique suffix works too: `mount('Button/Primary')`. A `.story.vue` single-file component is one story, addressable by its path alone (its `default` export). With gallery types (`references/typing.md`) ids are prefixed with the package name: `acme-ui/components/Button/Primary`.49- One export per scenario. Prefer a new story export over parameterizing an existing one — stories are greppable, reviewable documentation of component states.50 51## Testing patterns52 53Examples are React; the Vue equivalents differ only in story syntax.54 55### Callbacks and events56 57**The story owns the state and provides the callbacks.** Where the component takes callbacks, create the state inside the story, wire the callbacks to it, and record the state into a hidden form next to the component. Tests perform operations and assert on the recorded values:58 59```tsx60export const Stateful = () => {61  const [expanded, setExpanded] = useState(false);62  return <>63    <Expandable expanded={expanded} setExpanded={setExpanded} title="Title">Details</Expandable>64    <form hidden><input data-testid="expanded" readOnly value={String(expanded)} /></form>65  </>;66};67```68 69```ts70test('click should expand', async ({ mount }) => {71  const component = await mount('components/Expandable/Stateful');72  await component.locator('.codicon-chevron-right').click();73  await expect(component.getByTestId('expanded')).toHaveValue('true');74});75```76 77This keeps the whole scenario in the browser: no callback marshalling, the story doubles as documentation, and the recorded state is visible when eyeballing the gallery. Record each observed value in its own `data-testid` input (`String(...)` or `JSON.stringify(...)` for payloads) and assert with `toHaveValue()` — a web-first assertion that retries until the state lands. The negative direction works the same way: perform the operation, then assert the value did **not** change.78 79### Per-test props80 81When a scenario is genuinely parametric (e.g. a boundary-value sweep), pass props as the second argument to `mount`; the gallery hands them to the story as its props. Keep props to plain serializable data — callbacks belong inside the story.82 83```tsx84export const WithTitle = ({ title = 'Default' }: { title?: string }) =>85  <Button title={title} />;86```87 88```ts89const component = await mount('components/Button/WithTitle', { title: 'Hello' });90```91 92Props are type-checked in two optional ways, see `references/typing.md`: pass the story type as a template argument (`mount<typeof WithTitle>('components/Button/WithTitle', { title: 'Hello' })`, no setup), or generate gallery types with a small Vite plugin so the id itself is typed (`mount('acme-ui/components/Button/WithTitle', { title: 'Hello' })`, with autocomplete and rename safety). Vue stories must additionally declare the props at runtime — see the `Typed props` sections in `references/react.md` / `references/vue.md`.93 94### Prop transitions with `update()`95 96To test how a component reacts to a prop change **without remounting** (state preserved), call `component.update(newProps)` — it re-renders the same story with new props on the existing root:97 98```ts99const component = await mount('components/Counter/Default', { value: 1 });100await expect(component.getByTestId('value')).toHaveText('1');101await component.update({ value: 2 });102await expect(component.getByTestId('value')).toHaveText('2');103```104 105This requires the gallery to reuse its root/instance (`references/gallery-spec.md`); state survives as long as the story stays the same.106 107### Multiple states in one test108 109Each `mount()` navigates fresh, so tests are fully isolated and mounting several stories in one test is cheap:110 111```ts112await expect(await mount('Button/Primary')).toHaveScreenshot('primary.png');113await expect(await mount('Button/Disabled')).toHaveScreenshot('disabled.png');114```115 116For visual comparison, screenshot the returned root locator (as above), not the page, to avoid asserting on browser chrome.117 118### Network mocking119 120Use `page.route()` as usual — register routes before `mount()`, since mounting navigates. `serviceWorkers: 'block'` (set in the config above) keeps the app's own service worker from serving cached responses that shadow the routes. Teams with MSW handler libraries can start the worker inside a story or decorator instead.121 122### Debugging stories123 124Open your gallery URL (`baseURL`) in a browser and call `await window.mount({ story: 'components/Button/Primary' })` from the devtools console — that is exactly what the `mount` fixture does. An unknown story rejects `window.mount`, which surfaces as the test's `mount()` throwing with a real stack. To browse without the console, give your gallery an optional index page.125 126## Decision points127 128- **Monorepos / non-`src` layouts**: change the glob and the id derivation in your gallery (`references/gallery-spec.md`) to match, and prefix ids with the package name (`references/typing.md`).129- **Global providers** (theme, i18n, store, router): create a shared `decorator` helper next to the gallery and wrap components in stories; see `references/react.md` / `references/vue.md`.130## References131 132- `references/gallery-spec.md` — the gallery endpoint contract to implement (**start here**).133- `references/typing.md` — optional typing for `mount`: explicit story types vs generated gallery types, with the Vite plugin.134- `references/react.md` — React walkthrough: providers, StrictMode, CSS.135- `references/vue.md` — Vue walkthrough: `.story.ts` and `.story.vue` stories, plugins.136- `references/migration.md` — migrating off `@playwright/experimental-ct-react` / `-vue`.137