Component testing has a new story — try it and tell us what you think

With v1.62, Playwright shipped a new approach to component testing built on stories and a gallery page, driven by the built-in mount fixture of plain @playwright/test. It REPLACES the @playwright/experimental-ct-react and @playwright/experimental-ct-vue packages, which are now deprecated.

The new workflow is intentionally minimal, and parts of it — the mount API in particular — are still taking their final shape. We want your feedback before we lock it in. This issue explains why we made the change, how to try it, what we already know is rough, and what we'd like to hear from you.

Why we moved away from experimental-ct

The experimental packages let tests write JSX inline:

const component = await mount(<Button title='Submit' onClick={() => ++clicks} />);

It looks great in a snippet, but to make that single line work, Playwright had to control your entire pipeline: scan test files for components, compile a bundle with its own copy of Vite and its own config, serve it from its own server, and marshal props and callbacks across the Node.js/browser boundary.

That design is what kept the packages experimental for years:

• It only worked when your setup matched ours. Path aliases, plugins and CSS handling had to be mirrored into ctViteConfig by hand. Projects on webpack, Next.js or custom pipelines could not use their own build at all. Every framework needed its own package with its own runtime glue.
• The Node.js/browser boundary leaked. JSX written in a test was compiled in Node.js and reassembled in the browser. Live objects could not cross, callbacks only half-worked through marshalling, and module mocks silently did not apply.

These were not bugs we could fix — they were consequences of the architecture. So we inverted it.

The new model: stories and a gallery you own

Three small concepts replace the whole machine:

• A story is a tiny wrapper component that embeds the component under test in one specific scenario — hard-coded props, providers, mock data, recorded callbacks. Stories live next to the component in *.story.tsx files; each named export is one story.
• The gallery is a single page, served by your own dev server, that exposes window.mount()/window.unmount() to render a story into a root element. It is a few dozen lines of framework-specific glue — and it is yours.
• The built-in mount fixture navigates to the gallery, mounts a story by id, and returns a Locator:

import { test, expect } from '@playwright/test';

test('click should expand', async ({ mount }) => {
  const component = await mount('components/Expandable/Stateful');
  await component.getByRole('button').click();
  await expect(component.getByTestId('expanded')).toHaveValue('true');
});

What this buys you:

• Your pipeline, unchanged. Components are built and served by your dev server, with your plugins, your aliases, your CSS. If your app can render it, Playwright can test it.
• Framework-agnostic. React, Vue, Svelte, Solid — the only framework-specific piece is the gallery page you own. No more per-framework packages.
• No leaky boundary. The whole scenario runs in the browser. Callbacks live in the story and record their effects into the DOM, where web-first assertions pick them up.
• Stable. Tests import from plain @playwright/test, and mount is a documented built-in fixture. No experimental package to depend on.
• Stories are an asset. They are greppable, reviewable documentation of your component states, and the gallery doubles as a living catalog you can open in a browser.

Where coding agents come in

The gallery is application code, so Playwright does not ship it — instead, it ships the entire methodology as an agent skill. The fastest way to get set up:

npx playwright init-skills

then ask your coding agent (Claude Code, GitHub Copilot or similar):

Set up component testing using the playwright-component-testing skill.

The agent detects your framework and bundler, implements the gallery for your stack, adds a Playwright project to your config, and writes the first story and spec. It can also migrate an existing experimental-ct suite — see the migration guide.

Prefer to stay hands-on? The installed skill contains the full gallery specification with worked React and Vue examples (references/gallery-spec.md) — writing it by hand is entirely supported.

Known issues and limitations

Early adopters have already sent great feedback — thank you. Here is what we know is rough today:

• Story ids are strings, so type safety is incomplete (#42083). There is no autocompletion for story ids, and a typo or a renamed story fails at runtime rather than compile time. mount<typeof Story> type-checks props against the story, but does not tie the props to the id you passed. We are exploring a story-registry design (generated types plus declaration merging, in the spirit of TanStack Router) — this is the main reason the mount signature is not final yet.

Design choices

• Setup leans on a coding agent (#42084, #41996). There is no deterministic npx playwright setup-ct scaffold, and agent results vary across agents and models.
• No official per-framework gallery packages (#41996). The gallery runs through your own dev server precisely so that your pipeline keeps working.
• Per-test JSX is gone. Every composition becomes a named story export.

What we would like from you

1. Try the setup on a real project. Which framework, bundler and coding agent/model did you use? Did it work on the first prompt? Share transcripts of failures if you can.
2. Migrate an experimental-ct suite — with the skill — and tell us where the friction was.
3. Weigh in on the mount API: string ids vs. a typed registry, the update()/unmount() surface, how props should be typed.
4. Tell us what is missing before you would rely on this for your component tests.

Reply below with your experience — including "it just worked", which is signal too. The experimental-ct packages remain available while we finalize this, but all new investment is going into the gallery workflow, so now is the moment your feedback shapes the API.

📖 Docs: https://playwright.dev/docs/test-components