Skip to content

Playwright is a framework for Web Testing and Automation. It allows testing Chromium, Firefox and WebKit with a single API.

feat(skills): add component-testing agent skill (#41738)

Pavel Feldmandc272b99fdd6
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 00d6e5ebba..4cce0bdb63 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -54,6 +54,7 @@ const ignores = [
"packages/playwright-core/types/*",
"packages/playwright-ct-core/src/generated/*",
"packages/playwright/bundles/expect/third_party/",
+ "packages/skills/",
"packages/html-reporter/bundle.ts",
"packages/html-reporter/playwright.config.ts",
"packages/html-reporter/playwright/*",
diff --git a/examples/ct-react-vite/.gitignore b/examples/ct-react-vite/.gitignore
new file mode 100644
index 0000000000..5bb1c7684c
--- /dev/null
+++ b/examples/ct-react-vite/.gitignore
@@ -0,0 +1,4 @@
+node_modules
+dist
+test-results
+playwright-report
diff --git a/examples/ct-react-vite/index.html b/examples/ct-react-vite/index.html
new file mode 100644
index 0000000000..cf3a13303c
--- /dev/null
+++ b/examples/ct-react-vite/index.html
@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <link rel="icon" type="image/svg+xml" href="/src/assets/favicon.svg" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Vite App</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/src/main.tsx"></script>
+ </body>
+</html>
diff --git a/examples/ct-react-vite/package.json b/examples/ct-react-vite/package.json
new file mode 100644
index 0000000000..0479b93f1b
--- /dev/null
+++ b/examples/ct-react-vite/package.json
@@ -0,0 +1,25 @@
+{
+ "name": "ct-react-vite-example",
+ "private": true,
+ "version": "0.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc && vite build",
+ "test": "playwright test",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "react": "^18.2.0",
+ "react-dom": "^18.2.0",
+ "react-router-dom": "^6.6.1"
+ },
+ "devDependencies": {
+ "@playwright/test": "^1.56.0",
+ "@types/react": "^18.0.26",
+ "@types/react-dom": "^18.0.10",
+ "@vitejs/plugin-react": "^6.0.3",
+ "typescript": "^5.2.2",
+ "vite": "^8.1.0"
+ }
+}
diff --git a/examples/ct-react-vite/playwright.config.ts b/examples/ct-react-vite/playwright.config.ts
new file mode 100644
index 0000000000..8be33427cb
--- /dev/null
+++ b/examples/ct-react-vite/playwright.config.ts
@@ -0,0 +1,28 @@
+import { defineConfig, devices } from '@playwright/test';
+
+// Component testing with Playwright, following the playwright-component-testing skill.
+// The gallery (playwright/gallery/index.html) is served by the app's own Vite dev server;
+// `baseURL` points the built-in `mount` fixture at it.
+export default defineConfig({
+ // Specs live next to their components as trios: Button.tsx / Button.story.tsx / Button.spec.tsx.
+ testDir: './src',
+ forbidOnly: !!process.env.CI,
+ retries: process.env.CI ? 2 : 0,
+ reporter: process.env.CI ? 'html' : 'line',
+ webServer: {
+ command: 'npm run dev',
+ url: 'http://localhost:5173/playwright/gallery/index.html',
+ reuseExistingServer: !process.env.CI,
+ },
+ use: {
+ baseURL: 'http://localhost:5173/playwright/gallery/index.html',
+ serviceWorkers: 'block',
+ reuseContext: true,
+ trace: 'on-first-retry',
+ },
+ projects: [
+ { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+ { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+ { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+ ],
+});
diff --git a/examples/ct-react-vite/playwright/gallery/index.html b/examples/ct-react-vite/playwright/gallery/index.html
new file mode 100644
index 0000000000..2dfb0a5b57
--- /dev/null
+++ b/examples/ct-react-vite/playwright/gallery/index.html
@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Component gallery</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="./main.tsx"></script>
+ </body>
+</html>
diff --git a/examples/ct-react-vite/playwright/gallery/main.tsx b/examples/ct-react-vite/playwright/gallery/main.tsx
new file mode 100644
index 0000000000..5822ceca54
--- /dev/null
+++ b/examples/ct-react-vite/playwright/gallery/main.tsx
@@ -0,0 +1,38 @@
+// Playwright component gallery — implements the contract in the playwright-component-testing
+// skill (references/gallery-spec.md): a single page exposing window.mount()/window.unmount().
+// The built-in `mount` fixture navigates here (baseURL) and calls window.mount via
+// page.evaluate(..., { exposeFunctions: true }), so props may carry real callbacks.
+import { flushSync } from 'react-dom';
+import { createRoot, type Root } from 'react-dom/client';
+import '../../src/assets/index.css';
+
+// import.meta.glob must stay inline: Vite analyzes it statically, relative to this file.
+const stories = import.meta.glob('../../src/**/*.story.tsx');
+const id = (f: string) => f.replace(/^(\.\.\/)+src\//, '').replace(/\.story\.\w+$/, '');
+
+// Story id is '<path under src, without .story.tsx>/<ExportName>', e.g. 'components/Button/Default'.
+async function resolve(storyId: string) {
+ const sep = storyId.lastIndexOf('/');
+ const [path, name] = [storyId.slice(0, sep), storyId.slice(sep + 1)];
+ const file = Object.keys(stories).find(f => id(f) === path || id(f).endsWith('/' + path));
+ const mod = (file && await stories[file]()) as Record<string, any> | undefined;
+ return mod?.[name] ?? mod?.default;
+}
+
+const rootEl = document.getElementById('root')!;
+let root: Root | undefined;
+
+(window as any).mount = async ({ story, props }: { story: string, props?: Record<string, any> }) => {
+ const Story = await resolve(story);
+ if (!Story)
+ throw new Error(`Unknown story: ${story}`);
+ // Reuse the root so component.update() reconciles in place and preserves state.
+ root ??= createRoot(rootEl);
+ // flushSync so a render error rejects the promise instead of being swallowed.
+ flushSync(() => root!.render(<Story {...props} />));
+};
+
+(window as any).unmount = async () => {
+ root?.unmount();
+ root = undefined;
+};
diff --git a/examples/ct-react-vite/src/App.spec.tsx b/examples/ct-react-vite/src/App.spec.tsx
new file mode 100644
index 0000000000..3e01da7173
--- /dev/null
+++ b/examples/ct-react-vite/src/App.spec.tsx
@@ -0,0 +1,18 @@
+import { test, expect } from '@playwright/test';
+
+test('navigate to a page by clicking a link', async ({ mount }) => {
+ const component = await mount('App/Routing');
+ await expect(component.getByRole('main')).toHaveText('Login');
+ await component.getByRole('link', { name: 'Dashboard' }).click();
+ await expect(component.getByRole('main')).toHaveText('Dashboard');
+});
+
+test('update does not reset the router', async ({ mount }) => {
+ const component = await mount('App/Routing', { title: 'before' });
+ await expect(component.getByRole('heading')).toHaveText('before');
+ await expect(component.getByRole('main')).toHaveText('Login');
+
+ await component.update({ title: 'after' });
+ await expect(component.getByRole('heading')).toHaveText('after');
+ await expect(component.getByRole('main')).toHaveText('Login');
+});
diff --git a/examples/ct-react-vite/src/App.story.tsx b/examples/ct-react-vite/src/App.story.tsx
new file mode 100644
index 0000000000..66a9b8d229
--- /dev/null
+++ b/examples/ct-react-vite/src/App.story.tsx
@@ -0,0 +1,6 @@
+import { MemoryRouter } from 'react-router-dom';
+import App from './App';
+
+// Providers (here a router) are wired inside the story — the skill's decorator pattern.
+// MemoryRouter is used so routing starts at '/' regardless of the gallery's own URL.
+export const Routing = (props: any) => <MemoryRouter><App {...props} /></MemoryRouter>;
diff --git a/examples/ct-react-vite/src/App.tsx b/examples/ct-react-vite/src/App.tsx
new file mode 100644
index 0000000000..fd004390f3
--- /dev/null
+++ b/examples/ct-react-vite/src/App.tsx
@@ -0,0 +1,21 @@
+import { Routes, Route, Link } from 'react-router-dom';
+import logo from './assets/logo.svg';
+import LoginPage from './pages/LoginPage';
+import DashboardPage from './pages/DashboardPage';
+
+export default function App({ title }: { title?: string }) {
+ return <>
+ <header>
+ <img src={logo} alt="logo" width={125} height={125} />
+ {title && <h1>{title}</h1>}
+ <Link to="/">Login</Link>
+ <Link to="/dashboard">Dashboard</Link>
+ </header>
+ <Routes>
+ <Route path="/">
+ <Route index element={<LoginPage />} />
+ <Route path="dashboard" element={<DashboardPage />} />
+ </Route>
+ </Routes>
+ </>
+}
diff --git a/examples/ct-react-vite/src/assets/favicon.svg b/examples/ct-react-vite/src/assets/favicon.svg
new file mode 100644
index 0000000000..de4aeddc12
--- /dev/null
+++ b/examples/ct-react-vite/src/assets/favicon.svg
@@ -0,0 +1,15 @@
+<svg width="410" height="404" viewBox="0 0 410 404" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M399.641 59.5246L215.643 388.545C211.844 395.338 202.084 395.378 198.228 388.618L10.5817 59.5563C6.38087 52.1896 12.6802 43.2665 21.0281 44.7586L205.223 77.6824C206.398 77.8924 207.601 77.8904 208.776 77.6763L389.119 44.8058C397.439 43.2894 403.768 52.1434 399.641 59.5246Z" fill="url(#paint0_linear)"/>
+<path d="M292.965 1.5744L156.801 28.2552C154.563 28.6937 152.906 30.5903 152.771 32.8664L144.395 174.33C144.198 177.662 147.258 180.248 150.51 179.498L188.42 170.749C191.967 169.931 195.172 173.055 194.443 176.622L183.18 231.775C182.422 235.487 185.907 238.661 189.532 237.56L212.947 230.446C216.577 229.344 220.065 232.527 219.297 236.242L201.398 322.875C200.278 328.294 207.486 331.249 210.492 326.603L212.5 323.5L323.454 102.072C325.312 98.3645 322.108 94.137 318.036 94.9228L279.014 102.454C275.347 103.161 272.227 99.746 273.262 96.1583L298.731 7.86689C299.767 4.27314 296.636 0.855181 292.965 1.5744Z" fill="url(#paint1_linear)"/>
+<defs>
+<linearGradient id="paint0_linear" x1="6.00017" y1="32.9999" x2="235" y2="344" gradientUnits="userSpaceOnUse">
+<stop stop-color="#41D1FF"/>
+<stop offset="1" stop-color="#BD34FE"/>
+</linearGradient>
+<linearGradient id="paint1_linear" x1="194.651" y1="8.81818" x2="236.076" y2="292.989" gradientUnits="userSpaceOnUse">
+<stop stop-color="#FFEA83"/>
+<stop offset="0.0833333" stop-color="#FFDD35"/>
+<stop offset="1" stop-color="#FFA800"/>
+</linearGradient>
+</defs>
+</svg>
diff --git a/examples/ct-react-vite/src/assets/iconfont.woff2 b/examples/ct-react-vite/src/assets/iconfont.woff2
new file mode 100644
index 0000000000..ed1f4f34a4
Binary files /dev/null and b/examples/ct-react-vite/src/assets/iconfont.woff2 differ
diff --git a/examples/ct-react-vite/src/assets/index.css b/examples/ct-react-vite/src/assets/index.css
new file mode 100644
index 0000000000..dd2a6fa726
--- /dev/null
+++ b/examples/ct-react-vite/src/assets/index.css
@@ -0,0 +1,29 @@
+body {
+ margin: 0;
+ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Roboto', 'Oxygen',
+ 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans', 'Helvetica Neue',
+ sans-serif;
+ -webkit-font-smoothing: antialiased;
+ -moz-osx-font-smoothing: grayscale;
+}
+
+code {
+ font-family: source-code-pro, Menlo, Monaco, Consolas, 'Courier New',
+ monospace;
+}
+
+@media (prefers-color-scheme: light) {
+ :root {
+ color: #e3e3e3;
+ background-color: #1b1b1d;
+ }
+}
+
+@font-face {
+ font-family: 'pwtest-iconfont';
+ /* See tests/assets/webfont/README.md */
+ src: url('./iconfont.woff2') format('woff2');
+ font-weight: normal;
+ font-style: normal;
+ font-display: swap;
+}
diff --git a/examples/ct-react-vite/src/assets/logo.svg b/examples/ct-react-vite/src/assets/logo.svg
new file mode 100644
index 0000000000..6b60c1042f
--- /dev/null
+++ b/examples/ct-react-vite/src/assets/logo.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 841.9 595.3">
+ <g fill="#61DAFB">
+ <path d="M666.3 296.5c0-32.5-40.7-63.3-103.1-82.4 14.4-63.6 8-114.2-20.2-130.4-6.5-3.8-14.1-5.6-22.4-5.6v22.3c4.6 0 8.3.9 11.4 2.6 13.6 7.8 19.5 37.5 14.9 75.7-1.1 9.4-2.9 19.3-5.1 29.4-19.6-4.8-41-8.5-63.5-10.9-13.5-18.5-27.5-35.3-41.6-50 32.6-30.3 63.2-46.9 84-46.9V78c-27.5 0-63.5 19.6-99.9 53.6-36.4-33.8-72.4-53.2-99.9-53.2v22.3c20.7 0 51.4 16.5 84 46.6-14 14.7-28 31.4-41.3 49.9-22.6 2.4-44 6.1-63.6 11-2.3-10-4-19.7-5.2-29-4.7-38.2 1.1-67.9 14.6-75.8 3-1.8 6.9-2.6 11.5-2.6V78.5c-8.4 0-16 1.8-22.6 5.6-28.1 16.2-34.4 66.7-19.9 130.1-62.2 19.2-102.7 49.9-102.7 82.3 0 32.5 40.7 63.3 103.1 82.4-14.4 63.6-8 114.2 20.2 130.4 6.5 3.8 14.1 5.6 22.5 5.6 27.5 0 63.5-19.6 99.9-53.6 36.4 33.8 72.4 53.2 99.9 53.2 8.4 0 16-1.8 22.6-5.6 28.1-16.2 34.4-66.7 19.9-130.1 62-19.1 102.5-49.9 102.5-82.3zm-130.2-66.7c-3.7 12.9-8.3 26.2-13.5 39.5-4.1-8-8.4-16-13.1-24-4.6-8-9.5-15.8-14.4-23.4 14.2 2.1 27.9 4.7 41 7.9zm-45.8 106.5c-7.8 13.5-15.8 26.3-24.1 38.2-14.9 1.3-30 2-45.2 2-15.1 0-30.2-.7-45-1.9-8.3-11.9-16.4-24.6-24.2-38-7.6-13.1-14.5-26.4-20.8-39.8 6.2-13.4 13.2-26.8 20.7-39.9 7.8-13.5 15.8-26.3 24.1-38.2 14.9-1.3 30-2 45.2-2 15.1 0 30.2.7 45 1.9 8.3 11.9 16.4 24.6 24.2 38 7.6 13.1 14.5 26.4 20.8 39.8-6.3 13.4-13.2 26.8-20.7 39.9zm32.3-13c5.4 13.4 10 26.8 13.8 39.8-13.1 3.2-26.9 5.9-41.2 8 4.9-7.7 9.8-15.6 14.4-23.7 4.6-8 8.9-16.1 13-24.1zM421.2 430c-9.3-9.6-18.6-20.3-27.8-32 9 .4 18.2.7 27.5.7 9.4 0 18.7-.2 27.8-.7-9 11.7-18.3 22.4-27.5 32zm-74.4-58.9c-14.2-2.1-27.9-4.7-41-7.9 3.7-12.9 8.3-26.2 13.5-39.5 4.1 8 8.4 16 13.1 24 4.7 8 9.5 15.8 14.4 23.4zM420.7 163c9.3 9.6 18.6 20.3 27.8 32-9-.4-18.2-.7-27.5-.7-9.4 0-18.7.2-27.8.7 9-11.7 18.3-22.4 27.5-32zm-74 58.9c-4.9 7.7-9.8 15.6-14.4 23.7-4.6 8-8.9 16-13 24-5.4-13.4-10-26.8-13.8-39.8 13.1-3.1 26.9-5.8 41.2-7.9zm-90.5 125.2c-35.4-15.1-58.3-34.9-58.3-50.6 0-15.7 22.9-35.6 58.3-50.6 8.6-3.7 18-7 27.7-10.1 5.7 19.6 13.2 40 22.5 60.9-9.2 20.8-16.6 41.1-22.2 60.6-9.9-3.1-19.3-6.5-28-10.2zM310 490c-13.6-7.8-19.5-37.5-14.9-75.7 1.1-9.4 2.9-19.3 5.1-29.4 19.6 4.8 41 8.5 63.5 10.9 13.5 18.5 27.5 35.3 41.6 50-32.6 30.3-63.2 46.9-84 46.9-4.5-.1-8.3-1-11.3-2.7zm237.2-76.2c4.7 38.2-1.1 67.9-14.6 75.8-3 1.8-6.9 2.6-11.5 2.6-20.7 0-51.4-16.5-84-46.6 14-14.7 28-31.4 41.3-49.9 22.6-2.4 44-6.1 63.6-11 2.3 10.1 4.1 19.8 5.2 29.1zm38.5-66.7c-8.6 3.7-18 7-27.7 10.1-5.7-19.6-13.2-40-22.5-60.9 9.2-20.8 16.6-41.1 22.2-60.6 9.9 3.1 19.3 6.5 28.1 10.2 35.4 15.1 58.3 34.9 58.3 50.6-.1 15.7-23 35.6-58.4 50.6zM320.8 78.4z"/>
+ <circle cx="420.9" cy="296.5" r="45.7"/>
+ <path d="M520.5 78.1z"/>
+ </g>
+</svg>
diff --git a/examples/ct-react-vite/src/components/Button.spec.tsx b/examples/ct-react-vite/src/components/Button.spec.tsx
new file mode 100644
index 0000000000..fd2d401151
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Button.spec.tsx
@@ -0,0 +1,34 @@
+import { test, expect } from '@playwright/test';
+
+test('render props', async ({ mount }) => {
+ const component = await mount('components/Button/Default');
+ await expect(component).toContainText('Submit');
+});
+
+test('render attributes', async ({ mount }) => {
+ const component = await mount('components/Button/Default', { className: 'primary' });
+ await expect(component).toHaveClass('primary');
+});
+
+test('execute callback when the button is clicked', async ({ mount }) => {
+ const messages: string[] = [];
+ const component = await mount('components/Button/Default', {
+ onClick: (data: string) => messages.push(data),
+ });
+ await component.click();
+ expect(messages).toEqual(['hello']);
+});
+
+test('unmount', async ({ mount, page }) => {
+ const component = await mount('components/Button/Default');
+ await expect(page.locator('#root')).toContainText('Submit');
+ await component.unmount();
+ await expect(page.locator('#root')).not.toContainText('Submit');
+});
+
+test('mount, unmount, then mount again', async ({ mount }) => {
+ let component = await mount('components/Button/Default');
+ await component.unmount();
+ component = await mount('components/Button/Default', { title: 'Save' });
+ await expect(component).toContainText('Save');
+});
diff --git a/examples/ct-react-vite/src/components/Button.story.tsx b/examples/ct-react-vite/src/components/Button.story.tsx
new file mode 100644
index 0000000000..34d0dd117c
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Button.story.tsx
@@ -0,0 +1,4 @@
+import Button from './Button';
+
+// Spreads props so a test can pass `title`, `className`, or a real `onClick` callback.
+export const Default = (props: any) => <Button title="Submit" {...props} />;
diff --git a/examples/ct-react-vite/src/components/Button.tsx b/examples/ct-react-vite/src/components/Button.tsx
new file mode 100644
index 0000000000..8785b878d0
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Button.tsx
@@ -0,0 +1,13 @@
+import { ButtonHTMLAttributes } from "react";
+
+type ButtonProps = {
+ title: string;
+ onClick?(props: string): void;
+ className?: string;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'>;
+
+export default function Button({ onClick, title, ...attributes }: ButtonProps) {
+ return <button {...attributes} onClick={() => onClick?.('hello')}>
+ {title}
+ </button>
+}
diff --git a/examples/ct-react-vite/src/components/CheckChildrenProp.spec.tsx b/examples/ct-react-vite/src/components/CheckChildrenProp.spec.tsx
new file mode 100644
index 0000000000..755e1b5d06
--- /dev/null
+++ b/examples/ct-react-vite/src/components/CheckChildrenProp.spec.tsx
@@ -0,0 +1,6 @@
+import { test, expect } from '@playwright/test';
+
+test('absence of children', async ({ mount }) => {
+ const component = await mount('components/CheckChildrenProp/NoChildren');
+ await expect(component).toContainText('No Children');
+});
diff --git a/examples/ct-react-vite/src/components/CheckChildrenProp.story.tsx b/examples/ct-react-vite/src/components/CheckChildrenProp.story.tsx
new file mode 100644
index 0000000000..7c3f8410ae
--- /dev/null
+++ b/examples/ct-react-vite/src/components/CheckChildrenProp.story.tsx
@@ -0,0 +1,3 @@
+import CheckChildrenProp from './CheckChildrenProp';
+
+export const NoChildren = () => <CheckChildrenProp />;
diff --git a/examples/ct-react-vite/src/components/CheckChildrenProp.tsx b/examples/ct-react-vite/src/components/CheckChildrenProp.tsx
new file mode 100644
index 0000000000..3e8f405a5b
--- /dev/null
+++ b/examples/ct-react-vite/src/components/CheckChildrenProp.tsx
@@ -0,0 +1,7 @@
+import type { PropsWithChildren } from 'react';
+
+type DefaultChildrenProps = PropsWithChildren<{}>;
+
+export default function CheckChildrenProp(props: DefaultChildrenProps) {
+ return <>{'children' in props ? props.children : 'No Children'}</>
+}
diff --git a/examples/ct-react-vite/src/components/ComponentAsProp.spec.tsx b/examples/ct-react-vite/src/components/ComponentAsProp.spec.tsx
new file mode 100644
index 0000000000..1e8c2156f6
--- /dev/null
+++ b/examples/ct-react-vite/src/components/ComponentAsProp.spec.tsx
@@ -0,0 +1,12 @@
+import { test, expect } from '@playwright/test';
+
+test('render component as a prop', async ({ mount }) => {
+ const component = await mount('components/ComponentAsProp/WithButton');
+ await expect(component.getByRole('button', { name: 'Submit' })).toBeVisible();
+});
+
+test('render a jsx array as a prop', async ({ mount }) => {
+ const component = await mount('components/ComponentAsProp/WithArray');
+ await expect(component.getByRole('heading', { level: 4 })).toHaveText('4');
+ await expect(component.getByRole('paragraph')).toHaveText('[2,3]');
+});
diff --git a/examples/ct-react-vite/src/components/ComponentAsProp.story.tsx b/examples/ct-react-vite/src/components/ComponentAsProp.story.tsx
new file mode 100644
index 0000000000..9c3db66e3c
--- /dev/null
+++ b/examples/ct-react-vite/src/components/ComponentAsProp.story.tsx
@@ -0,0 +1,7 @@
+import { ComponentAsProp } from './ComponentAsProp';
+import Button from './Button';
+
+// The rendered node passed as a prop is baked into the story (JSX can't travel from the test).
+export const WithButton = () => <ComponentAsProp component={<Button title="Submit" />} />;
+
+export const WithArray = () => <ComponentAsProp component={[<h4>{[4]}</h4>, [[<p>[2,3]</p>]]]} />;
diff --git a/examples/ct-react-vite/src/components/ComponentAsProp.tsx b/examples/ct-react-vite/src/components/ComponentAsProp.tsx
new file mode 100644
index 0000000000..67b8813207
--- /dev/null
+++ b/examples/ct-react-vite/src/components/ComponentAsProp.tsx
@@ -0,0 +1,9 @@
+import { ReactNode } from "react";
+
+type ComponentAsProp = {
+ component: ReactNode[] | ReactNode;
+};
+
+export function ComponentAsProp({ component }: ComponentAsProp) {
+ return <div>{component}</div>
+}
diff --git a/examples/ct-react-vite/src/components/Counter.spec.tsx b/examples/ct-react-vite/src/components/Counter.spec.tsx
new file mode 100644
index 0000000000..5e7640bb77
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Counter.spec.tsx
@@ -0,0 +1,36 @@
+import { test, expect } from '@playwright/test';
+
+// component.update(props) re-renders the same story on the reused root, so state survives —
+// remount-count stays 1 throughout.
+test('update props without remounting', async ({ mount }) => {
+ const component = await mount('components/Counter/Default', { count: 9001 });
+ await expect(component.getByTestId('props')).toContainText('9001');
+
+ await component.update({ count: 1337 });
+ await expect(component).not.toContainText('9001');
+ await expect(component.getByTestId('props')).toContainText('1337');
+
+ await expect(component.getByTestId('remount-count')).toContainText('1');
+});
+
+test('update callbacks without remounting', async ({ mount }) => {
+ const component = await mount('components/Counter/Default');
+
+ const messages: string[] = [];
+ await component.update({ onClick: (message: string) => messages.push(message) });
+ await component.click();
+ expect(messages).toEqual(['hello']);
+
+ await expect(component.getByTestId('remount-count')).toContainText('1');
+});
+
+test('update children without remounting', async ({ mount }) => {
+ const component = await mount('components/Counter/Default', { children: 'Default Slot' });
+ await expect(component).toContainText('Default Slot');
+
+ await component.update({ children: 'Test Slot' });
+ await expect(component).not.toContainText('Default Slot');
+ await expect(component).toContainText('Test Slot');
+
+ await expect(component.getByTestId('remount-count')).toContainText('1');
+});
diff --git a/examples/ct-react-vite/src/components/Counter.story.tsx b/examples/ct-react-vite/src/components/Counter.story.tsx
new file mode 100644
index 0000000000..fc5e31281e
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Counter.story.tsx
@@ -0,0 +1,5 @@
+import Counter from './Counter';
+
+// Spreads props (count, onClick, children) so tests can drive it and, crucially, call
+// component.update(newProps) to re-render in place — remount-count stays 1.
+export const Default = (props: any) => <Counter {...props} />;
diff --git a/examples/ct-react-vite/src/components/Counter.tsx b/examples/ct-react-vite/src/components/Counter.tsx
new file mode 100644
index 0000000000..18e999de73
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Counter.tsx
@@ -0,0 +1,25 @@
+import { useLayoutEffect, useRef, useState } from "react"
+
+ type CounterProps = {
+ count?: number;
+ onClick?(props: string): void;
+ children?: any;
+ }
+
+ let _remountCount = 1;
+
+ export default function Counter(props: CounterProps) {
+ const [remountCount] = useState(_remountCount);
+ const didMountRef = useRef(false)
+ useLayoutEffect(() => {
+ if (!didMountRef.current) {
+ didMountRef.current = true;
+ _remountCount++;
+ }
+ }, [])
+ return <button onClick={() => props.onClick?.('hello')}>
+ <span data-testid="props">{ props.count }</span>
+ <span data-testid="remount-count">{ remountCount }</span>
+ { props.children }
+ </button>
+ }
diff --git a/examples/ct-react-vite/src/components/DefaultChildren.spec.tsx b/examples/ct-react-vite/src/components/DefaultChildren.spec.tsx
new file mode 100644
index 0000000000..bd41ae3221
--- /dev/null
+++ b/examples/ct-react-vite/src/components/DefaultChildren.spec.tsx
@@ -0,0 +1,31 @@
+import { test, expect } from '@playwright/test';
+
+test('render a default child', async ({ mount }) => {
+ const component = await mount('components/DefaultChildren/Text');
+ await expect(component).toContainText('Main Content');
+});
+
+test('render a component as a child', async ({ mount }) => {
+ const component = await mount('components/DefaultChildren/WithButton');
+ await expect(component).toContainText('Submit');
+});
+
+test('render multiple children', async ({ mount }) => {
+ const component = await mount('components/DefaultChildren/Multiple');
+ await expect(component.getByTestId('one')).toContainText('One');
+ await expect(component.getByTestId('two')).toContainText('Two');
+});
+
+test('render a number as a child', async ({ mount }) => {
+ const component = await mount('components/DefaultChildren/Number');
+ await expect(component).toContainText('1337');
+});
+
+test('execute callback when a child node is clicked', async ({ mount }) => {
+ let clickFired = false;
+ const component = await mount('components/DefaultChildren/ClickableChild', {
+ onChildClick: () => (clickFired = true),
+ });
+ await component.getByText('Main Content').click();
+ expect(clickFired).toBeTruthy();
+});
diff --git a/examples/ct-react-vite/src/components/DefaultChildren.story.tsx b/examples/ct-react-vite/src/components/DefaultChildren.story.tsx
new file mode 100644
index 0000000000..59254c743e
--- /dev/null
+++ b/examples/ct-react-vite/src/components/DefaultChildren.story.tsx
@@ -0,0 +1,18 @@
+import DefaultChildren from './DefaultChildren';
+import Button from './Button';
+
+// Children cannot cross the test/browser boundary as JSX, so each composition is its own story.
+export const Text = () => <DefaultChildren>Main Content</DefaultChildren>;
+
+export const WithButton = () => <DefaultChildren><Button title="Submit" /></DefaultChildren>;
+
+export const Multiple = () => <DefaultChildren>
+ <div data-testid="one">One</div>
+ <div data-testid="two">Two</div>
+</DefaultChildren>;
+
+export const Number = () => <DefaultChildren>{1337}</DefaultChildren>;
+
+// A clickable child whose handler is supplied by the test as a callback prop.
+export const ClickableChild = (props: { onChildClick?: () => void }) =>
+ <DefaultChildren><span onClick={props.onChildClick}>Main Content</span></DefaultChildren>;
diff --git a/examples/ct-react-vite/src/components/DefaultChildren.tsx b/examples/ct-react-vite/src/components/DefaultChildren.tsx
new file mode 100644
index 0000000000..691b6a0806
--- /dev/null
+++ b/examples/ct-react-vite/src/components/DefaultChildren.tsx
@@ -0,0 +1,15 @@
+type DefaultChildrenProps = {
+ children?: any;
+}
+
+export default function DefaultChildren(props: DefaultChildrenProps) {
+ return <div>
+ <h1>Welcome!</h1>
+ <main>
+ {props.children}
+ </main>
+ <footer>
+ Thanks for visiting.
+ </footer>
+ </div>
+}
diff --git a/examples/ct-react-vite/src/components/EmptyFragment.spec.tsx b/examples/ct-react-vite/src/components/EmptyFragment.spec.tsx
new file mode 100644
index 0000000000..cf656897c2
--- /dev/null
+++ b/examples/ct-react-vite/src/components/EmptyFragment.spec.tsx
@@ -0,0 +1,7 @@
+import { test, expect } from '@playwright/test';
+
+test('render an empty component', async ({ mount, page }) => {
+ const component = await mount('components/EmptyFragment/Default');
+ expect(await page.evaluate(() => 'props' in window && (window as any).props)).toEqual({});
+ await expect(component).toHaveText('');
+});
diff --git a/examples/ct-react-vite/src/components/EmptyFragment.story.tsx b/examples/ct-react-vite/src/components/EmptyFragment.story.tsx
new file mode 100644
index 0000000000..95ba94b540
--- /dev/null
+++ b/examples/ct-react-vite/src/components/EmptyFragment.story.tsx
@@ -0,0 +1,3 @@
+import EmptyFragment from './EmptyFragment';
+
+export const Default = () => <EmptyFragment />;
diff --git a/examples/ct-react-vite/src/components/EmptyFragment.tsx b/examples/ct-react-vite/src/components/EmptyFragment.tsx
new file mode 100644
index 0000000000..b424841462
--- /dev/null
+++ b/examples/ct-react-vite/src/components/EmptyFragment.tsx
@@ -0,0 +1,4 @@
+export default function EmptyFragment(props: unknown) {
+ Object.assign(window, { props });
+ return <>{[]}</>;
+}
diff --git a/examples/ct-react-vite/src/components/Fetcher.spec.tsx b/examples/ct-react-vite/src/components/Fetcher.spec.tsx
new file mode 100644
index 0000000000..e6a9fb3302
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Fetcher.spec.tsx
@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+
+// Network mocking is standard Playwright routing — set the route before mounting.
+test('mock a fetch with page.route', async ({ mount, page }) => {
+ await page.route('**/data.json', route => route.fulfill({ json: { name: 'John Doe' } }));
+ const component = await mount('components/Fetcher/Default');
+ await expect(component.getByTestId('name')).toHaveText('John Doe');
+});
diff --git a/examples/ct-react-vite/src/components/Fetcher.story.tsx b/examples/ct-react-vite/src/components/Fetcher.story.tsx
new file mode 100644
index 0000000000..8613c48ed3
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Fetcher.story.tsx
@@ -0,0 +1,3 @@
+import Fetcher from './Fetcher';
+
+export const Default = () => <Fetcher />;
diff --git a/examples/ct-react-vite/src/components/Fetcher.tsx b/examples/ct-react-vite/src/components/Fetcher.tsx
new file mode 100644
index 0000000000..2f1322d148
--- /dev/null
+++ b/examples/ct-react-vite/src/components/Fetcher.tsx
@@ -0,0 +1,32 @@
+import { useEffect, useState } from "react"
+
+export default function Fetcher() {
+ const [data, setData] = useState<{ name: string }>({ name: '<none>' });
+ const [fetched, setFetched] = useState(false);
+
+ useEffect(() => {
+ const doFetch = async () => {
+ try {
+ const response = await fetch('/data.json');
+ setData(await response.json());
+ } catch {
+ setData({ name: '<error>' });
+ }
+ setFetched(true);
+ }
+
+ if (!fetched)
+ doFetch();
+ }, [fetched, setFetched, setData]);
+
+ return <div>
+ <div data-testid='name'>{data.name}</div>
+ <button onClick={() => {
+ setFetched(false);
+ setData({ name: '<none>' });
+ }}>Reset</button>
+ <button onClick={() => {
+ fetch('/post', { method: 'POST', body: 'hello from the page' });
+ }}>Post it</button>
+ </div>;
+}
diff --git a/examples/ct-react-vite/src/components/MultiRoot.spec.tsx b/examples/ct-react-vite/src/components/MultiRoot.spec.tsx
new file mode 100644
index 0000000000..61705e0fa2
--- /dev/null
+++ b/examples/ct-react-vite/src/components/MultiRoot.spec.tsx
@@ -0,0 +1,15 @@
+import { test, expect } from '@playwright/test';
+
+test('render a multi-root component', async ({ mount, page }) => {
+ await mount('components/MultiRoot/Default');
+ await expect(page.locator('#root')).toContainText('root 1');
+ await expect(page.locator('#root')).toContainText('root 2');
+});
+
+test('unmount a multi-root component', async ({ mount, page }) => {
+ const component = await mount('components/MultiRoot/Default');
+ await expect(page.locator('#root')).toContainText('root 1');
+ await expect(page.locator('#root')).toContainText('root 2');
+ await component.unmount();
+ await expect(page.locator('#root')).not.toContainText('root 1');
+});
diff --git a/examples/ct-react-vite/src/components/MultiRoot.story.tsx b/examples/ct-react-vite/src/components/MultiRoot.story.tsx
new file mode 100644
index 0000000000..8defa20579
--- /dev/null
+++ b/examples/ct-react-vite/src/components/MultiRoot.story.tsx
@@ -0,0 +1,3 @@
+import MultiRoot from './MultiRoot';
+
+export const Default = () => <MultiRoot />;
diff --git a/examples/ct-react-vite/src/components/MultiRoot.tsx b/examples/ct-react-vite/src/components/MultiRoot.tsx
new file mode 100644
index 0000000000..f29e397c0f
--- /dev/null
+++ b/examples/ct-react-vite/src/components/MultiRoot.tsx
@@ -0,0 +1,6 @@
+export default function MultiRoot() {
+ return <>
+ <div>root 1</div>
+ <div>root 2</div>
+ </>
+}
diff --git a/examples/ct-react-vite/src/components/MultipleChildren.spec.tsx b/examples/ct-react-vite/src/components/MultipleChildren.spec.tsx
new file mode 100644
index 0000000000..e6ca55f961
--- /dev/null
+++ b/examples/ct-react-vite/src/components/MultipleChildren.spec.tsx
@@ -0,0 +1,8 @@
+import { test, expect } from '@playwright/test';
+
+test('render named children', async ({ mount }) => {
+ const component = await mount('components/MultipleChildren/Default');
+ await expect(component).toContainText('Header');
+ await expect(component).toContainText('Main Content');
+ await expect(component).toContainText('Footer');
+});
diff --git a/examples/ct-react-vite/src/components/MultipleChildren.story.tsx b/examples/ct-react-vite/src/components/MultipleChildren.story.tsx
new file mode 100644
index 0000000000..4ea9ac411a
--- /dev/null
+++ b/examples/ct-react-vite/src/components/MultipleChildren.story.tsx
@@ -0,0 +1,7 @@
+import MultipleChildren from './MultipleChildren';
+
+export const Default = () => <MultipleChildren>
+ <div>Header</div>
+ <div>Main Content</div>
+ <div>Footer</div>
+</MultipleChildren>;
diff --git a/examples/ct-react-vite/src/components/MultipleChildren.tsx b/examples/ct-react-vite/src/components/MultipleChildren.tsx
new file mode 100644
index 0000000000..63bd0104c6
--- /dev/null
+++ b/examples/ct-react-vite/src/components/MultipleChildren.tsx
@@ -0,0 +1,18 @@
+
+type MultipleChildrenProps = {
+ children?: [any, any, any];
+}
+
+export default function MultipleChildren(props: MultipleChildrenProps) {
+ return <div>
+ <header>
+ {props.children?.at(0)}
+ </header>
+ <main>
+ {props.children?.at(1)}
+ </main>
+ <footer>
+ {props.children?.at(2)}
+ </footer>
+</div>
+}
diff --git a/examples/ct-react-vite/src/components/TitleWithFont.css b/examples/ct-react-vite/src/components/TitleWithFont.css
new file mode 100644
index 0000000000..9fc7e0a7c0
--- /dev/null
+++ b/examples/ct-react-vite/src/components/TitleWithFont.css
@@ -0,0 +1,3 @@
+.title-with-font {
+ font-family: pwtest-iconfont, sans-serif;
+}
diff --git a/examples/ct-react-vite/src/components/TitleWithFont.spec.tsx b/examples/ct-react-vite/src/components/TitleWithFont.spec.tsx
new file mode 100644
index 0000000000..a5ea2761ff
--- /dev/null
+++ b/examples/ct-react-vite/src/components/TitleWithFont.spec.tsx
@@ -0,0 +1,11 @@
+import { test, expect } from '@playwright/test';
+
+// The gallery imports the app's global CSS, so the story's @font-face triggers a real font load.
+test('load a web font', async ({ mount, page }) => {
+ const promise = page.waitForEvent('requestfinished', r => r.url().includes('iconfont'));
+ await mount('components/TitleWithFont/Default');
+ const request = await promise;
+ const response = await request.response();
+ const body = await response!.body();
+ expect(body.length).toBe(348);
+});
diff --git a/examples/ct-react-vite/src/components/TitleWithFont.story.tsx b/examples/ct-react-vite/src/components/TitleWithFont.story.tsx
new file mode 100644
index 0000000000..b684d31300
--- /dev/null
+++ b/examples/ct-react-vite/src/components/TitleWithFont.story.tsx
@@ -0,0 +1,3 @@
+import TitleWithFont from './TitleWithFont';
+
+export const Default = () => <TitleWithFont />;
diff --git a/examples/ct-react-vite/src/components/TitleWithFont.tsx b/examples/ct-react-vite/src/components/TitleWithFont.tsx
new file mode 100644
index 0000000000..ad783205c3
--- /dev/null
+++ b/examples/ct-react-vite/src/components/TitleWithFont.tsx
@@ -0,0 +1,5 @@
+import './TitleWithFont.css';
+
+export default function TitleWithFont() {
+ return <div className='title-with-font'>+-</div>
+}
diff --git a/examples/ct-react-vite/src/main.tsx b/examples/ct-react-vite/src/main.tsx
new file mode 100644
index 0000000000..f3fe4a896d
--- /dev/null
+++ b/examples/ct-react-vite/src/main.tsx
@@ -0,0 +1,13 @@
+import * as React from 'react';
+import { createRoot } from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import App from './App';
+import './assets/index.css';
+
+createRoot(document.getElementById("root")!).render(
+ <React.StrictMode>
+ <BrowserRouter>
+ <App />
+ </BrowserRouter>
+ </React.StrictMode>
+);
diff --git a/examples/ct-react-vite/src/pages/DashboardPage.tsx b/examples/ct-react-vite/src/pages/DashboardPage.tsx
new file mode 100644
index 0000000000..64307e87f3
--- /dev/null
+++ b/examples/ct-react-vite/src/pages/DashboardPage.tsx
@@ -0,0 +1,3 @@
+export default function DashboardPage() {
+ return <main>Dashboard</main>
+}
diff --git a/examples/ct-react-vite/src/pages/LoginPage.tsx b/examples/ct-react-vite/src/pages/LoginPage.tsx
new file mode 100644
index 0000000000..96adc431ed
--- /dev/null
+++ b/examples/ct-react-vite/src/pages/LoginPage.tsx
@@ -0,0 +1,3 @@
+export default function LoginPage() {
+ return <main>Login</main>
+}
diff --git a/examples/ct-react-vite/src/vite-env.d.ts b/examples/ct-react-vite/src/vite-env.d.ts
new file mode 100644
index 0000000000..11f02fe2a0
--- /dev/null
+++ b/examples/ct-react-vite/src/vite-env.d.ts
@@ -0,0 +1 @@
+/// <reference types="vite/client" />
diff --git a/examples/ct-react-vite/tsconfig.json b/examples/ct-react-vite/tsconfig.json
new file mode 100644
index 0000000000..c84ccd8aca
--- /dev/null
+++ b/examples/ct-react-vite/tsconfig.json
@@ -0,0 +1,18 @@
+{
+ "compilerOptions": {
+ "target": "ESNext",
+ "useDefineForClassFields": true,
+ "lib": ["DOM", "DOM.Iterable", "ESNext"],
+ "skipLibCheck": true,
+ "allowSyntheticDefaultImports": true,
+ "strict": true,
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "resolveJsonModule": true,
+ "isolatedModules": true,
+ "noEmit": true,
+ "jsx": "react-jsx",
+ "types": ["vite/client"]
+ },
+ "include": ["src", "playwright"]
+}
diff --git a/examples/ct-react-vite/vite.config.ts b/examples/ct-react-vite/vite.config.ts
new file mode 100644
index 0000000000..b1b5f91e5f
--- /dev/null
+++ b/examples/ct-react-vite/vite.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+
+// https://vitejs.dev/config/
+export default defineConfig({
+ plugins: [react()]
+})
diff --git a/packages/playwright-ct-core/src/mount.ts b/packages/playwright-ct-core/src/mount.ts
index 4486d17b79..294a83cd33 100644
--- a/packages/playwright-ct-core/src/mount.ts
+++ b/packages/playwright-ct-core/src/mount.ts
@@ -29,7 +29,7 @@ interface MountResult extends Locator {
update: (options: ObjectComponentOptions | JsxComponent) => Promise<void>;
}
-type TestFixtures = PlaywrightTestArgs & PlaywrightTestOptions & {
+type TestFixtures = Omit<PlaywrightTestArgs, 'mount'> & PlaywrightTestOptions & {
mount: (component: any, options: any) => Promise<MountResult>;
router: RouterFixture;
};
diff --git a/packages/playwright/src/index.ts b/packages/playwright/src/index.ts
index 7bb29dc0d2..7b2ba2575a 100644
--- a/packages/playwright/src/index.ts
+++ b/packages/playwright/src/index.ts
@@ -494,6 +494,33 @@ const playwrightFixtures: Fixtures<TestFixtures, WorkerFixtures, UtilityTestFixt
page = await context.newPage();
await use(page);
},
+
+ mount: async ({ page, baseURL }, use) => {
+ // exposeFunctions turns any callbacks in props into real, browser-callable
+ // functions that dispatch back to the test.
+ const callMount = (params: { story: string, props?: Record<string, any> }) =>
+ page.evaluate(async p => {
+ const w = window as any;
+ if (typeof w.mount !== 'function')
+ throw new Error('The gallery page does not define window.mount().');
+ await w.mount(p);
+ }, params, { exposeFunctions: true });
+ await use(async (storyId: string, props?: Record<string, any>) => {
+ if (!baseURL)
+ throw new Error('mount() requires `baseURL` to point at the component gallery. Set it in your Playwright config.');
+ // The gallery is a single page (served at baseURL) that exposes window.mount()/window.unmount().
+ await page.goto(baseURL);
+ await callMount({ story: storyId, props });
+ return Object.assign(page.locator('#root >> internal:control=component'), {
+ // update() re-renders the same story with new props without navigating; if the gallery
+ // reuses its root/instance, the framework reconciles and component state is preserved.
+ update: (newProps?: Record<string, any>) => callMount({ story: storyId, props: newProps }),
+ unmount: () => page.evaluate(async () => {
+ await (window as any).unmount?.();
+ }),
+ });
+ });
+ },
});
type ScreenshotOption = PlaywrightWorkerOptions['screenshot'] | undefined;
diff --git a/packages/playwright/types/test.d.ts b/packages/playwright/types/test.d.ts
index 16d6d4d166..472c9e021a 100644
--- a/packages/playwright/types/test.d.ts
+++ b/packages/playwright/types/test.d.ts
@@ -7865,6 +7865,9 @@ export interface PlaywrightTestArgs {
*
*/
request: APIRequestContext;
+ // Experimental, undocumented: mount a story from the component gallery and return a locator
+ // for the mounted component, augmented with update()/unmount(). See the playwright-component-testing skill.
+ mount: (storyId: string, props?: Record<string, any>) => Promise<Locator & { update(props?: Record<string, any>): Promise<void>, unmount(): Promise<void> }>;
}
type ExcludeProps<A, B> = {
diff --git a/packages/skills/component-testing/SKILL.md b/packages/skills/component-testing/SKILL.md
new file mode 100644
index 0000000000..54e8bc218e
--- /dev/null
+++ b/packages/skills/component-testing/SKILL.md
@@ -0,0 +1,140 @@
+---
+name: playwright-component-testing
+description: 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.
+---
+
+# Component Testing with Playwright
+
+Test 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.
+
+## Concept
+
+- 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.
+- 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.
+- 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 mounted component (the single element rendered into `#root`, or `#root` itself when the story renders a fragment) — so specs read just like the old component tests. Nothing to scaffold for it.
+
+Everything 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). `mount(id, props)` passes `props` to the component, and props may include **callbacks** — the component calls them in the browser and your test-side function runs in Node.
+
+## Setup workflow
+
+1. **Detect the framework and bundler.** React vs Vue decides the framework notes and example story to follow. Then:
+ - **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.
+ - **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.
+2. **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.
+3. **Configure Playwright** — add to `playwright.config.ts`:
+
+ ```ts
+ projects: [
+ {
+ name: 'components',
+ testDir: './tests/components',
+ use: { ...devices['Desktop Chrome'], baseURL: 'http://localhost:5173/playwright/gallery/index.html', serviceWorkers: 'block', reuseContext: true },
+ },
+ ],
+ webServer: {
+ command: 'npm run dev', // or: npx vite --config playwright/vite.config.ts
+ url: 'http://localhost:5173/playwright/gallery/index.html', // standalone server: http://localhost:3100/playwright/gallery/index.html
+ reuseExistingServer: !process.env.CI,
+ },
+ ```
+
+ 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.
+4. **Write a first story** next to an existing component, modeled on `templates/<react|vue>/Button.story.*`.
+5. **Write a first spec**, modeled on `templates/react/button.spec.ts`, importing `test`/`expect` from `@playwright/test`.
+6. **Run**: `npx playwright test --project=components`. Open `http://localhost:5173/playwright/gallery/index.html` in a browser to eyeball all stories.
+
+## Conventions
+
+- 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).
+- One export per scenario. Prefer a new story export over parameterizing an existing one — stories are greppable, reviewable documentation of component states.
+
+## Testing patterns
+
+Examples are React; the Vue equivalents differ only in story syntax.
+
+### Callbacks and events
+
+**Pass the callback straight to `mount`** — it runs in Node, so you assert directly on what the component called it with:
+
+```ts
+test('fires onSubmit with the form data', async ({ mount }) => {
+ const calls: any[] = [];
+ const component = await mount('components/Form/Default', { onSubmit: (data: any) => calls.push(data) });
+ await component.getByRole('button', { name: 'Save' }).click();
+ expect(calls).toEqual([{ name: 'Ada' }]);
+});
+```
+
+Callbacks may be async and return a value the component `await`s — the return travels back from Node:
+
+```ts
+await mount('components/Field/Default', { validate: async (v: string) => v.length > 0 });
+```
+
+**Or record the effect in the DOM** inside the story — handy when you also want the state visible when eyeballing the gallery:
+
+```tsx
+export const CountsClicks = () => {
+ const [clicks, setClicks] = useState(0);
+ return <>
+ <Button title="Submit" onClick={() => setClicks(c => c + 1)} />
+ <output data-testid="click-count">{clicks}</output>
+ </>;
+};
+```
+
+### Per-test props
+
+When 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. Props may include functions.
+
+```tsx
+export const WithTitle = ({ title = 'Default' }: { title?: string }) =>
+ <Button title={title} />;
+```
+
+```ts
+const component = await mount('components/Button/WithTitle', { title: 'Hello' });
+```
+
+### Prop transitions with `update()`
+
+To 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:
+
+```ts
+const component = await mount('components/Counter/Default', { value: 1 });
+await expect(component.getByTestId('value')).toHaveText('1');
+await component.update({ value: 2 });
+await expect(component.getByTestId('value')).toHaveText('2');
+```
+
+This requires the gallery to reuse its root/instance (`references/gallery-spec.md`); state survives as long as the story stays the same.
+
+### Multiple states in one test
+
+Each `mount()` navigates fresh, so tests are fully isolated and mounting several stories in one test is cheap:
+
+```ts
+await expect(await mount('Button/Primary')).toHaveScreenshot('primary.png');
+await expect(await mount('Button/Disabled')).toHaveScreenshot('disabled.png');
+```
+
+For visual comparison, screenshot the component locator (as above), not the page, to avoid asserting on gallery chrome.
+
+### Network mocking
+
+Use `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.
+
+### Debugging stories
+
+Open 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.
+
+## Decision points
+
+- **Monorepos / non-`src` layouts**: change the glob and the id derivation in your gallery (`references/gallery-spec.md`) to match.
+- **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`.
+## References
+
+- `references/gallery-spec.md` — the gallery endpoint contract to implement (**start here**).
+- `references/react.md` — React walkthrough: providers, StrictMode, CSS.
+- `references/vue.md` — Vue walkthrough: `.story.ts` and `.story.vue` stories, plugins.
+- `references/migration.md` — migrating off `@playwright/experimental-ct-react` / `-vue`.
diff --git a/packages/skills/component-testing/references/gallery-spec.md b/packages/skills/component-testing/references/gallery-spec.md
new file mode 100644
index 0000000000..315b854063
--- /dev/null
+++ b/packages/skills/component-testing/references/gallery-spec.md
@@ -0,0 +1,149 @@
+# Gallery contract
+
+The **gallery** is a single page, served by your dev server at the URL you set as `baseURL` in your
+Playwright config, that exposes two methods on `window` for Playwright to drive:
+
+- `window.mount(params)` — render a story.
+- `window.unmount()` — unmount the current story.
+
+The built-in `mount` fixture navigates to the gallery, then calls `window.mount` via
+`page.evaluate(fn, params, { exposeFunctions: true })`. Because `exposeFunctions` turns functions
+in the arguments into real, browser-callable functions, **props may include callbacks** — the
+component invokes them in the browser and your test-side function runs in Node (and can return a
+value back).
+
+## `window.mount(params)`
+
+`params` is `{ story, props }`, straight from the test's `mount(story, props)` call:
+
+- `story` — the story id (string). Resolve it (see id grammar) to a component.
+- `props` — the props object passed to the component. May contain **functions**; they are real
+ callbacks, not data — call them and, if you like, `await` their result.
+
+Render the resolved component with `props` into `#root`. Return a `Promise` that resolves once the
+component is mounted and **rejects on failure** (unknown story, render throw). The rejection
+surfaces as the test's `await mount(...)` throwing, with a real stack — there is no HTTP-status or
+DOM-attribute signalling.
+
+**Reuse the root across calls.** The test's `component.update(props)` calls `window.mount` again
+with the same story and new props, **without navigating**. If you render into the same root /
+instance rather than recreating it, the framework reconciles and component-internal state is
+preserved — that is CT's `update()`. Recreating the root each call (or navigating) resets state, so
+reuse it: create it on first mount and render into it on every call. The framework reconciles,
+remounting on its own only when the story (component type) changes.
+
+**`window.mount` is your setup/teardown hook.** It is the browser-side equivalent of CT's
+`beforeMount` / `afterMount`: install providers or plugins, seed a store, start an in-browser mock
+server *before* you render, and run post-render work *after* — all inside this one function,
+branched on the `story` / `props` the test passed. There is no separate hook registry; the function
+you own is the hook.
+
+## `window.unmount()`
+
+Unmount the current story from `#root` and return a `Promise`. The test calls it via
+`component.unmount()`. Needed only to assert teardown/cleanup effects — each `mount` navigates
+fresh, so tests are already isolated.
+
+## `#root`
+
+Render the component into an element with `id="root"`. `mount` returns a `Locator` for the mounted
+component itself — the single element child of `#root` — so `component.click()` and
+`expect(component).toHaveClass(...)` target the component. When
+the story renders a fragment (several top-level elements, e.g. the component plus an `<output>`
+recording events), the locator falls back to `#root`; tests then scope their queries
+(`component.getByRole('button')`).
+
+## Story id grammar (recommended)
+
+The gallery owns resolution; `mount` passes the id through untouched. Recommended scheme:
+
+- `<path under src, without the .story.* extension>/<ExportName>` — e.g.
+ `src/components/Button.story.tsx` export `Primary` → `components/Button/Primary`.
+- Any unique trailing suffix resolves too: `Button/Primary`.
+- A single-file-component story (`Button.story.vue`) is one story, addressed by its path alone
+ (its default export): `components/Button`.
+
+## Worked example (React + Vite SPA)
+
+An illustration of the contract, **not** a file to copy — implement the equivalent for your stack.
+`import.meta.glob` stays inline here: Vite analyzes it statically, relative to this file, so it
+cannot be moved into shared/shipped code. That is exactly why the gallery is yours to own.
+
+```tsx
+// playwright/gallery/main.tsx
+import { flushSync } from 'react-dom';
+import { createRoot, type Root } from 'react-dom/client';
+
+const stories = import.meta.glob('../../src/**/*.story.{tsx,jsx}');
+const id = (f: string) => f.replace(/^(\.\.\/)+src\//, '').replace(/\.story\.\w+$/, '');
+
+async function resolve(storyId: string) {
+ const sep = storyId.lastIndexOf('/');
+ const [path, name] = [storyId.slice(0, sep), storyId.slice(sep + 1)];
+ const file = Object.keys(stories).find(f => id(f) === path || id(f).endsWith('/' + path));
+ const mod = (file && await stories[file]()) as Record<string, any> | undefined;
+ return mod?.[name] ?? mod?.default;
+}
+
+const rootEl = document.getElementById('root')!;
+let root: Root | undefined;
+
+(window as any).mount = async ({ story, props }: { story: string, props?: Record<string, any> }) => {
+ const Story = await resolve(story);
+ if (!Story)
+ throw new Error(`Unknown story: ${story}`);
+ root ??= createRoot(rootEl); // reuse the root so update() reconciles and preserves state
+ // flushSync so a render error rejects the promise instead of being swallowed.
+ flushSync(() => root!.render(<Story {...props} />));
+};
+
+(window as any).unmount = async () => {
+ root?.unmount();
+ root = undefined;
+};
+```
+
+```html
+<!-- playwright/gallery/index.html -->
+<!DOCTYPE html>
+<div id="root"></div>
+<script type="module" src="./main.tsx"></script>
+```
+
+## Vue variant (state-preserving)
+
+Vue's `createApp(...).mount()` builds a fresh instance each call, so mount a small **reactive host**
+once and update its refs — updating them re-renders in place, which is what preserves state across
+`update()`:
+
+```ts
+// playwright/gallery/main.ts
+import { createApp, h, shallowRef, type App, type Component } from 'vue';
+
+// resolve() and the import.meta.glob are the same as the React example.
+const story = shallowRef<Component | null>(null);
+const props = shallowRef<Record<string, any>>({});
+const host = { render: () => (story.value ? h(story.value, props.value) : null) };
+let app: App | undefined;
+
+(window as any).mount = async ({ story: id, props: next }: { story: string, props?: Record<string, any> }) => {
+ const resolved = await resolve(id);
+ if (!resolved)
+ throw new Error(`Unknown story: ${id}`);
+ story.value = resolved;
+ props.value = next ?? {};
+ if (!app) { // mount once; the ref updates above re-render in place
+ app = createApp(host);
+ app.mount('#root');
+ }
+};
+
+(window as any).unmount = async () => {
+ app?.unmount();
+ app = undefined;
+};
+```
+
+A callback prop just arrives as a function — `props.onSave?.(data)` inside the component runs the
+test's callback. Keep the story-resolution glob and the framework mount in this file; everything
+else lives in your stories and tests.
diff --git a/packages/skills/component-testing/references/migration.md b/packages/skills/component-testing/references/migration.md
new file mode 100644
index 0000000000..326f428d9a
--- /dev/null
+++ b/packages/skills/component-testing/references/migration.md
@@ -0,0 +1,82 @@
+# Migrating from @playwright/experimental-ct-react / -vue
+
+The CT packages compiled JSX in the test file and marshalled it into the browser. The gallery
+pattern splits that in two: **structure** (which component, its children, providers) moves into a
+story export that runs natively in the browser; **data and behavior** (props, callbacks) stay in
+the test and travel through `mount(storyId, props)`. Callbacks, `update()` and `unmount()` work as
+before, so most specs port mechanically.
+
+## Concept mapping
+
+| `@playwright/experimental-ct-*` | Gallery pattern |
+|---|---|
+| `mount(<Button title="…" onClick={spy} />)` | Story export `Default = props => <Button title="…" {...props} />` + `mount('Button/Default', { onClick: spy })` |
+| Props / callback props from the test | Unchanged in spirit: `mount(id, props)` — functions cross and run in Node, may be async and return values |
+| JSX children / slots from the test | Cannot cross — bake each composition into its own story export (Vue: `.story.vue` for slot-heavy scenarios) |
+| `component.update(<Button count={2} />)` | `component.update({ count: 2 })` — state-preserving, needs the gallery to reuse its root (`gallery-spec.md`) |
+| `component.unmount()` | `component.unmount()` — backed by the gallery's `window.unmount()` |
+| `beforeMount`/`afterMount` in `playwright/index.ts` | The body of the gallery's `window.mount` (global), or story decorators (per-story) |
+| `hooksConfig` per-test variation | Props: `mount('App/Routing', { route: '/dashboard' })` — the story/decorator interprets them |
+| `router` fixture / MSW handlers in Node | `page.route()` in the test, or MSW `setupWorker` inside a story/decorator |
+| `playwright/index.html` (styles, fonts, theme) | The gallery's `index.html` / entry module imports |
+| `ctViteConfig`, `ctPort`, `ctTemplateDir`, `ctCacheDir` | Gone — the gallery runs through the app's own dev server; port lives in `webServer` + `baseURL`; location is `playwright/gallery/` |
+| `defineConfig` from `@playwright/experimental-ct-react` | Plain `defineConfig` from `@playwright/test`, with `baseURL` = gallery URL, `serviceWorkers: 'block'`, `reuseContext: true` (see `SKILL.md`) |
+
+## Steps
+
+1. Set up the gallery and config per `SKILL.md`. Keep the old CT project running until the last
+ spec is migrated.
+2. For each CT spec, split every `mount(<…/>)` call: JSX structure becomes a story export next to
+ the component; test-supplied props and callbacks stay in the test as `mount`'s second argument.
+ A call site that only varies props/callbacks usually needs just one generic story that spreads
+ them: `export const Default = (props: ButtonProps) => <Button title="Submit" {...props} />`.
+3. Rewrite the spec: import `test`/`expect` from `@playwright/test`; `mount(<X a={1} onB={spy}/>)`
+ → `mount('X/Default', { a: 1, onB: spy })`; `update(<X a={2}/>)` → `update({ a: 2 })`;
+ `unmount()` unchanged. Callback spies and their assertions survive verbatim.
+4. Port `beforeMount` hooks: app-wide setup into the gallery's `window.mount`; per-test
+ `hooksConfig` branches into props interpreted by a story or decorator.
+5. When all specs are green, delete the CT project from the config, drop the
+ `@playwright/experimental-ct-*` dependency, and remove `playwright/index.html`,
+ `playwright/index.ts*` and `playwright/.cache`.
+
+## Gotchas
+
+- **Story ids are strings.** Renaming or moving a story breaks specs at runtime, not compile time
+ — and the suffix-matching resolution can silently match a different story after a rename.
+- **Per-test JSX is gone.** Any test that built a different JSX tree per test (children matrices,
+ inline wrappers) becomes one story export per composition.
+
+## Before / after
+
+```tsx
+// Before (CT)
+import { test, expect } from '@playwright/experimental-ct-react';
+import Button from '../src/components/Button';
+
+test('click', async ({ mount }) => {
+ const messages: string[] = [];
+ const component = await mount(<Button title="Submit" onClick={data => messages.push(data)} />);
+ await component.click();
+ expect(messages).toEqual(['hello']);
+});
+```
+
+```tsx
+// After: src/components/Button.story.tsx
+import Button from './Button';
+
+export const Default = (props: { onClick?: (data: string) => void }) =>
+ <Button title="Submit" {...props} />;
+```
+
+```ts
+// After: src/components/Button.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('click', async ({ mount }) => {
+ const messages: string[] = [];
+ const component = await mount('components/Button/Default', { onClick: (data: string) => messages.push(data) });
+ await component.click();
+ expect(messages).toEqual(['hello']);
+});
+```
diff --git a/packages/skills/component-testing/references/react.md b/packages/skills/component-testing/references/react.md
new file mode 100644
index 0000000000..1d142a5377
--- /dev/null
+++ b/packages/skills/component-testing/references/react.md
@@ -0,0 +1,50 @@
+# React setup
+
+Follow the setup workflow in `SKILL.md`. Implement the gallery per `references/gallery-spec.md` (which has a React worked example); this page covers React-specific details.
+
+## Files
+
+- `playwright/gallery/` — the gallery you implement to `references/gallery-spec.md` (an `index.html` + a `main.tsx` module). Requires `react` and `react-dom` 18+ (`createRoot`).
+- Stories: `src/**/*.story.tsx` (the glob also picks up `.story.jsx`); example in `templates/react/Button.story.tsx`.
+
+## StrictMode
+
+Wrap the rendered story in `<React.StrictMode>` in your gallery to match how most apps render. In development builds StrictMode intentionally double-invokes render functions and effects. This matters for stories that record events with counters set in effects — recording via state updates from event handlers (like the `CountsClicks` example story) is unaffected. If a story misbehaves under StrictMode, that is usually a real finding about the component; drop the wrapper only if the app itself does not use StrictMode.
+
+## Global providers
+
+If components require context (theme, store, i18n, router), create one shared decorator and use it in stories, so each story states its scenario and nothing more:
+
+```tsx
+// src/stories/decorators.tsx
+import { ThemeProvider } from '../theme';
+import { MemoryRouter } from 'react-router-dom';
+
+export function AppScaffold({ children, route = '/' }: { children: React.ReactNode, route?: string }) {
+ return (
+ <ThemeProvider theme="light">
+ <MemoryRouter initialEntries={[route]}>{children}</MemoryRouter>
+ </ThemeProvider>
+ );
+}
+```
+
+```tsx
+// src/components/ProfilePage.story.tsx
+export const LoggedIn = () => (
+ <AppScaffold route="/profile/42">
+ <ProfilePage user={{ id: 42, name: 'Test User' }} />
+ </AppScaffold>
+);
+```
+
+Do not build the decorator into the gallery — keeping it in story files makes the wrapping visible and lets stories opt out.
+
+## CSS
+
+- Global stylesheets: import them in your gallery entry (`playwright/gallery/main.tsx`, e.g. `import '../../src/index.css'`), mirroring the app's own entry point.
+- Tailwind: if content scanning is path-based, make sure `*.story.tsx` files are covered.
+
+## Data fetching
+
+For libraries with client objects (React Query, Apollo), create the client inside the story or decorator so each navigation starts fresh.
diff --git a/packages/skills/component-testing/references/vue.md b/packages/skills/component-testing/references/vue.md
new file mode 100644
index 0000000000..5243ac85da
--- /dev/null
+++ b/packages/skills/component-testing/references/vue.md
@@ -0,0 +1,52 @@
+# Vue setup
+
+Follow the setup workflow in `SKILL.md`. Implement the gallery per `references/gallery-spec.md`, exposing `window.mount`/`window.unmount` — in Vue, mount with `app = createApp(h(story, props)); app.mount('#root')` and unmount with `app.unmount()`; this page covers Vue-specific details.
+
+## Files
+
+- `playwright/gallery/` — the gallery you implement to `references/gallery-spec.md` (an `index.html` + a `main.ts` module). Requires Vue 3.
+- Stories: `src/**/*.story.{ts,js,vue}`; example in `templates/vue/Button.story.ts`.
+
+## Two ways to write stories
+
+**Render-function stories** (`Button.story.ts`) — several scenarios per file, one named export each; see `templates/vue/Button.story.ts`. Uses `defineComponent` + `h()`, no SFC compilation involved.
+
+**Single-file-component stories** (`Button.primary.story.vue`) — one story per file, full template syntax:
+
+```vue
+<script setup lang="ts">
+import { ref } from 'vue';
+import Button from './Button.vue';
+const clicks = ref(0);
+</script>
+
+<template>
+ <Button title="Submit" @click="clicks++" />
+ <output data-testid="click-count">{{ clicks }}</output>
+</template>
+```
+
+An SFC story is addressed by its path without the extension: `mount('components/Button.primary')`. Prefer SFC stories when the scenario needs slots or non-trivial templates.
+
+## Global plugins
+
+Apps that rely on plugins (Pinia, vue-router, i18n) should wrap components with a decorator story helper that creates a fresh instance per story:
+
+```ts
+// src/stories/decorators.ts
+import { defineComponent, h, type Component } from 'vue';
+import { createPinia } from 'pinia';
+
+export function withStore(story: Component) {
+ return defineComponent(() => {
+ const pinia = createPinia();
+ return () => h(story, { pinia });
+ });
+}
+```
+
+For plugins that must be installed on the app instance (`app.use(...)`), add them in your gallery right after `createApp(...)` — that is the equivalent of the app's own bootstrap.
+
+## CSS
+
+Import global stylesheets in your gallery entry (`playwright/gallery/main.ts`, e.g. `import '../../src/assets/main.css'`), mirroring the app's entry point.
diff --git a/packages/skills/component-testing/templates/react/Button.story.tsx b/packages/skills/component-testing/templates/react/Button.story.tsx
new file mode 100644
index 0000000000..0df097ef8b
--- /dev/null
+++ b/packages/skills/component-testing/templates/react/Button.story.tsx
@@ -0,0 +1,19 @@
+// Example story file. Stories live next to the component they exercise:
+// this file is src/components/Button.story.tsx for src/components/Button.tsx.
+// Each named export is one story: a scenario-specific wrapper around the
+// component. Wire providers, mock data and event recording here, not in tests.
+import { useState } from 'react';
+import { Button } from './Button';
+
+export const Primary = () => <Button title="Submit" />;
+
+export const Disabled = () => <Button title="Submit" disabled />;
+
+// Callbacks are asserted through the DOM: record events into visible output.
+export const CountsClicks = () => {
+ const [clicks, setClicks] = useState(0);
+ return <>
+ <Button title="Submit" onClick={() => setClicks(count => count + 1)} />
+ <output data-testid="click-count">{clicks}</output>
+ </>;
+};
diff --git a/packages/skills/component-testing/templates/react/button.spec.ts b/packages/skills/component-testing/templates/react/button.spec.ts
new file mode 100644
index 0000000000..bcefdd2594
--- /dev/null
+++ b/packages/skills/component-testing/templates/react/button.spec.ts
@@ -0,0 +1,18 @@
+// Example component test. `mount` is a built-in fixture of @playwright/test.
+import { test, expect } from '@playwright/test';
+
+test('renders primary button', async ({ mount }) => {
+ const component = await mount('components/Button/Primary');
+ await expect(component).toHaveText('Submit');
+});
+
+test('disabled button is disabled', async ({ mount }) => {
+ const component = await mount('components/Button/Disabled');
+ await expect(component).toBeDisabled();
+});
+
+test('button click fires callback', async ({ mount, page }) => {
+ const component = await mount('components/Button/CountsClicks');
+ await component.getByRole('button').click();
+ await expect(page.getByTestId('click-count')).toHaveText('1');
+});
diff --git a/packages/skills/component-testing/templates/vue/Button.story.ts b/packages/skills/component-testing/templates/vue/Button.story.ts
new file mode 100644
index 0000000000..e8f1e32f71
--- /dev/null
+++ b/packages/skills/component-testing/templates/vue/Button.story.ts
@@ -0,0 +1,21 @@
+// Example story file. Stories live next to the component they exercise:
+// this file is src/components/Button.story.ts for src/components/Button.vue.
+// Each named export is one story: a scenario-specific wrapper around the
+// component. Wire providers, mock data and event recording here, not in tests.
+// Alternatively, write a story as a Button.<scenario>.story.vue single-file
+// component — its default export is the story.
+import { defineComponent, h, ref } from 'vue';
+import Button from './Button.vue';
+
+export const Primary = defineComponent(() => () => h(Button, { title: 'Submit' }));
+
+export const Disabled = defineComponent(() => () => h(Button, { title: 'Submit', disabled: true }));
+
+// Callbacks are asserted through the DOM: record events into visible output.
+export const CountsClicks = defineComponent(() => {
+ const clicks = ref(0);
+ return () => h('div', [
+ h(Button, { title: 'Submit', onClick: () => clicks.value++ }),
+ h('output', { 'data-testid': 'click-count' }, String(clicks.value)),
+ ]);
+});
diff --git a/packages/skills/component-testing/templates/vue/button.spec.ts b/packages/skills/component-testing/templates/vue/button.spec.ts
new file mode 100644
index 0000000000..bcefdd2594
--- /dev/null
+++ b/packages/skills/component-testing/templates/vue/button.spec.ts
@@ -0,0 +1,18 @@
+// Example component test. `mount` is a built-in fixture of @playwright/test.
+import { test, expect } from '@playwright/test';
+
+test('renders primary button', async ({ mount }) => {
+ const component = await mount('components/Button/Primary');
+ await expect(component).toHaveText('Submit');
+});
+
+test('disabled button is disabled', async ({ mount }) => {
+ const component = await mount('components/Button/Disabled');
+ await expect(component).toBeDisabled();
+});
+
+test('button click fires callback', async ({ mount, page }) => {
+ const component = await mount('components/Button/CountsClicks');
+ await component.getByRole('button').click();
+ await expect(page.getByTestId('click-count')).toHaveText('1');
+});
diff --git a/tsconfig.json b/tsconfig.json
index c26c7fc9c6..e8bc4e9f9d 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -43,5 +43,6 @@
"exclude": [
"packages/*/lib",
"packages/extension",
+ "packages/skills",
]
}
diff --git a/utils/build/build.js b/utils/build/build.js
index cb233c7a30..38825020fb 100644
--- a/utils/build/build.js
+++ b/utils/build/build.js
@@ -1055,6 +1055,12 @@ copyFiles.push({
to: 'packages/playwright/lib',
});
+copyFiles.push({
+ files: 'packages/skills/**/*',
+ from: 'packages/skills',
+ to: 'packages/playwright/lib/skills',
+});
+
copyFiles.push({
files: 'packages/playwright-core/src/tools/cli-client/skill/**/*.md',
from: 'packages/playwright-core/src',
diff --git a/utils/generate_types/index.js b/utils/generate_types/index.js
index a2b61decfc..f20b51e3b3 100644
--- a/utils/generate_types/index.js
+++ b/utils/generate_types/index.js
@@ -579,8 +579,10 @@ class TypesGenerator {
'Config',
'ExpectMatcherUtils',
'Matchers',
+ 'PlaywrightTestArgs.mount',
'PlaywrightWorkerArgs.playwright',
'PlaywrightWorkerOptions.defaultBrowserType',
+ 'PlaywrightWorkerOptions.reuseContext',
'Project',
]),
doNotExportClassNames: assertionClasses,
diff --git a/utils/generate_types/overrides-test.d.ts b/utils/generate_types/overrides-test.d.ts
index 9adad0984d..66f6dc3605 100644
--- a/utils/generate_types/overrides-test.d.ts
+++ b/utils/generate_types/overrides-test.d.ts
@@ -309,6 +309,9 @@ export interface PlaywrightTestArgs {
context: BrowserContext;
page: Page;
request: APIRequestContext;
+ // Experimental, undocumented: mount a story from the component gallery and return a locator
+ // for the mounted component, augmented with update()/unmount(). See the playwright-component-testing skill.
+ mount: (storyId: string, props?: Record<string, any>) => Promise<Locator & { update(props?: Record<string, any>): Promise<void>, unmount(): Promise<void> }>;
}
type ExcludeProps<A, B> = {