}) => {
const Story = await resolve(story);
if (!Story) throw new Error(`Unknown story: ${story}`);
root ??= createRoot(rootEl, { onUncaughtError: error => { renderError = error; } });
renderError = undefined;
flushSync(() => root!.render());
if (renderError) {
const error = renderError;
root.unmount();
root = undefined;
throw error;
}
};
(window as any).unmount = async () => {
root?.unmount();
root = undefined;
};
```
このmain.tsxは、同梱スキルのgallery仕様にある作例をもとに、StrictModeで包み、エラー処理を補ったものです。要点は次の4つです。
- `import.meta.glob` でstoryファイルを列挙し、`src/` からの相対パスと export名を組み合わせてstory idにします。この処理はViteの静的解析に依存するため、共通パッケージには切り出せません。
- 2回目以降の `mount` でも `createRoot` を作り直さずに再利用します。作り直すと、後述の `update()` でコンポーネントの状態が消えます。
- 描画中の例外をテスト側の失敗として返します。React 19では描画中のエラーが再スローされないため、`flushSync` だけでは `mount` が成功扱いになりました（同梱スキルの作例のままでは、5件目のテストは失敗します）。そこで `createRoot` の `onUncaughtError` でエラーを受け取り、`window.mount` から投げ直しています。
- 短縮idが複数のstoryファイルに一致した場合は、先頭のファイルを選ばずに `Ambiguous story` として失敗させます。完全一致があればそちらを優先します。
アプリ全体で使うCSSやテーマの初期化も、このmain.tsxに書きます。旧方式の `beforeMount`／`afterMount` フックに当たる処理の置き場所も、この `window.mount` の中です。
### playwright.config.tsのcomponentsプロジェクト
```
import { defineConfig, devices } from '@playwright/test';
export default defineConfig({
projects: [
{
name: 'components',
testDir: './tests/components',
use: {
...devices['Desktop Chrome'],
baseURL: 'http://localhost:5173/playwright/gallery/index.html',
serviceWorkers: 'block',
reuseContext: true,
},
},
],
webServer: {
command: 'npx vite',
url: 'http://localhost:5173/playwright/gallery/index.html',
reuseExistingServer: !process.env.CI,
},
});
```
```
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({ plugins: [react()], server: { port: 5173, strictPort: true } });
```
`mount` は `baseURL` へ遷移するので、`baseURL` はgalleryのURLにします。`serviceWorkers: 'block'` は、アプリのService Workerがキャッシュを返して `page.route()` のモックを素通りさせるのを防ぐ設定です。`reuseContext: true` は、同じワーカー内のテスト間でブラウザコンテキストを使い回します。旧パッケージが暗黙に行っていた高速化を、明示的に指定する形になりました。なお、package.jsonに `"type": "module"` がないと、Vite 8.3.0はvite.config.tsの読み込み時に警告を出します。
## storyとテストコードの書き方
### storyの命名とstory id
テスト対象のCounterと、そのstoryを次のように用意しました。storyファイルはコンポーネントと同じディレクトリに置き、名前付きexportを1つのシナリオとして扱います。
```
import { useState } from 'react';
type Props = { step?: number; onChange?: (value: number) => void };
export function Counter({ step = 1, onChange }: Props) {
const [count, setCount] = useState(0);
return (
);
}
```
```
import { useState } from 'react';
import { Counter } from './Counter';
export const Default = ({ step = 1 }: { step?: number }) => ;
export const RecordsChange = () => {
const [last, setLast] = useState(null);
return <>
;
};
export const Broken = () => { throw new Error('render failed'); };
```
story idは「`src/` 配下のパスから `.story.*` を除いたもの＋export名」です。この例では `components/Counter/Default` になり、一意に決まる末尾部分だけの `Counter/Default` でも解決できます。この例のように文字列でidを書く場合、storyの名前変更や移動は実行時まで検出されません。1.63では、Vite用の小さなプラグインで `stories.d.ts` を生成し、`@playwright/test` の `Stories` インターフェースに登録すると、id自体も型検査と補完の対象にできます。
### propsの受け渡しとupdate()
```
import { test, expect } from '@playwright/test';
import type { Default } from '../../src/components/Counter.story';
test('step の値ずつ増える', async ({ mount }) => {
const component = await mount('components/Counter/Default', { step: 5 });
await component.getByRole('button', { name: '+5' }).click();
await expect(component.getByLabel('count')).toHaveText('5');
});
test('update() は状態を保ったまま props だけ差し替える', async ({ mount }) => {
const component = await mount('Counter/Default', { step: 1 });
await component.getByRole('button').click();
await component.update({ step: 10 });
await component.getByRole('button', { name: '+10' }).click();
await expect(component.getByLabel('count')).toHaveText('11');
});
test('onChange の結果は story 側の隠しフォームで検証する', async ({ mount }) => {
const component = await mount('Counter/RecordsChange');
await component.getByRole('button').click();
await expect(component.getByTestId('last')).toHaveValue('2');
});
test('存在しない story は mount が例外になる', async ({ mount }) => {
await expect(mount('Counter/Missing')).rejects.toThrow('Unknown story');
});
test('描画中の例外も mount の失敗として受け取れる', async ({ mount }) => {
await expect(mount('Counter/Broken')).rejects.toThrow('render failed');
});
```
```
npx playwright test --project=components --reporter=list
```
```
Running 5 tests using 1 worker
✓ 1 [components] › tests/components/counter.spec.ts:4:1 › step の値ずつ増える (627ms)
✓ 2 [components] › tests/components/counter.spec.ts:10:1 › update() は状態を保ったまま props だけ差し替える (898ms)
✓ 3 [components] › tests/components/counter.spec.ts:18:1 › onChange の結果は story 側の隠しフォームで検証する (589ms)
✓ 4 [components] › tests/components/counter.spec.ts:24:1 › 存在しない story は mount が例外になる (348ms)
✓ 5 [components] › tests/components/counter.spec.ts:28:1 › 描画中の例外も mount の失敗として受け取れる (362ms)
5 passed (6.5s)
```
2件目のテストは、1回クリックして値を1にしたあと、`update({ step: 10 })` でpropsだけを差し替えています。続けて+10を押した結果が11になることから、再マウントされずに状態が引き継がれたことがわかります。`mount` のように型引数でstoryの型を渡すと、propsが型検査されます。`step` に文字列を渡すコードは、tsc 7.0.2でTS2322のエラーになりました。
propsで渡すのは、シリアライズできる素のデータだけにします。同梱スキルも公式ドキュメントも、コールバックはstoryの中に置くよう定めています。
### コールバックは隠しフォームで検証
3件目のテストが、新方式の中心となる書き方です。旧方式のように、テスト側で関数を渡して呼び出し回数を数えることはしません。story側で `useState` を持ってコールバックに接続し、その値を `hidden` 属性付きのフォームに書き出します。テストは `toHaveValue()` で値を確認します。`toHaveValue()` は値が反映されるまで自動で再試行するので、待機処理を書く必要がありません。検証したい値が複数ある場合は、値ごとに `data-testid` 付きのinputを分けます。オブジェクトは `JSON.stringify` で文字列にして書き出します。
手動で確認したいときは、galleryのURLをブラウザで開き、DevToolsのコンソールで `await window.mount({ story: 'components/Counter/RecordsChange' })` を実行します。これは `mount` fixtureが内部で行っている処理と同じです。開発中はstoryの `hidden` を外しておくと、クリックに応じて記録値が変わる様子を画面で確認できます。
### ネットワークのモックとスクリーンショット比較
```
test('APIが500を返したらエラー表示になる', async ({ page, mount }) => {
await page.route('**/api/items', route => route.fulfill({ status: 500 }));
const component = await mount('components/ItemList/Default');
await expect(component.getByRole('alert')).toContainText('Something went wrong');
});
test('ボタンの見た目を状態ごとに比較する', async ({ mount }) => {
await expect(await mount('Button/Primary')).toHaveScreenshot('primary.png');
await expect(await mount('Button/Disabled')).toHaveScreenshot('disabled.png');
});
```
上の2つは、公式ドキュメントの例をもとにテスト名を変えたものです（ItemListとButtonのstoryは別途必要です）。`mount` はページ遷移を伴うので、`page.route()` は必ず `mount` より前に登録します。スクリーンショットはページ全体ではなく、`mount` が返すルートのLocatorを撮ると、galleryに置いた余分な要素が比較に混ざりません。1.62からは、スナップショット名を `.webp` にするとWebP形式で保存できます。アクセシビリティツリーをスナップショットで比べたい場合は、[Playwright の Aria Snapshots が提供するアクセシビリティ検証機能とは](/tech/details/6230/)で紹介している `toMatchAriaSnapshot()` も、同じLocatorに対して使えます。
## Vue・Svelteなど他フレームワークでの扱い
新方式で必要なフレームワーク固有のコードはgalleryだけなので、公式ドキュメントは「React、Vue、Svelte、Solidなど、開発サーバーが描画できるものなら何でもテストできる」としています。ただし、同梱スキルに作例があるのはReactとVueだけです。
Vueでは `createApp(...).mount()` を呼ぶたびに新しいインスタンスができるため、gallery仕様は、小さなホストを1度だけマウントし、storyとpropsを `shallowRef` で差し替える実装を示しています。
```
const story = shallowRef(null);
const props = shallowRef>({});
const host = { render: () => (story.value ? h(story.value, props.value) : null) };
let app: App | undefined;
(window as any).mount = async ({ story: id, props: next }) => {
const resolved = await resolve(id);
if (!resolved)
throw new Error(`Unknown story: ${id}`);
story.value = resolved;
props.value = next ?? {};
if (!app) {
app = createApp(host);
app.mount('#root');
}
};
```
スロットを多用するシナリオは、`.story.vue` の単一ファイルコンポーネントを1つのstoryとして扱えます（idはパスのみで、default exportを使います）。Svelteは専用パッケージが1.59.0で削除されたため、現行のPlaywright Component Testingで扱うには、新方式の自前galleryを書くことになります。その場合も、story idを解決して `#root` に描画し、`update()` のためにルートを使い回すという契約を満たせば、`mount` fixture側の変更は不要です。
## 旧experimental-ct-reactからの移行手順
[公式の移行ガイド](https://playwright.dev/docs/test-components#migration-from-the-experimental-packages)にある対応表のうち、影響の大きい項目を抜き出しました。
| 旧パッケージ | story方式 |
| --------------------------------- | --------------------------------- |
| mount(JSX) | storyのexport＋mount(‘id’) |
| テストからのデータprops | mount(id, props) |
| JSXのchildren・スロット | 組み合わせごとにstoryを1つ |
| component.update(JSX) | component.update(props) |
| beforeMount・afterMount | galleryのwindow.mount・storyのデコレーター |
| hooksConfig | storyが解釈するprops |
| routerフィクスチャ | page.route() またはstory内のMSW |
| playwright/index.html | galleryのindex.htmlとエントリーモジュール |
| ctViteConfig・ctPort・ctTemplateDir | 廃止（webServerとbaseURLで指定） |
クリック回数を数える典型的なテストは、次のように書き換えます。
移行前（button.spec.tsx）：
```
import { test, expect } from '@playwright/experimental-ct-react';
import { Button } from '../src/components/Button';
test('counts clicks', async ({ mount }) => {
let clicks = 0;
const component = await mount(