Playwright 1.62 のコンポーネントレベル VRT を実際に構築してみた

Playwright 1.62.0 で、これまで実験的な機能だったコンポーネントレベルの VRT（Visual Regression Testing）が正式にパッケージへ含まれるようになりました。実際に自分のプロジェクトへ導入してみたので、構成の全体像とハマったポイントをまとめておきます。

まず驚いたこと：手順書の一行目が「エージェントに任せろ」だった
Playwright のコンポーネント VRT はどういう構成になっているか
1. 全体像
2. 用意するもの
既存の E2E テストとの共存
ハマりポイント：workers はプロジェクト単位で効かない
まとめ

まず驚いたこと：手順書の一行目が「エージェントに任せろ」だった

公式の環境構築手順を開いて最初に目に入ったのが、

エージェントにこのスキルを渡して環境構築するのが早いです

という一文でした。手順書の一番最初にこれが書かれている。世の中はもうエージェントありきでドキュメントが作られているんだな、というのが正直な第一印象です。

Playwright のコンポーネント VRT はどういう構成になっているか

全体像

Playwright のコンポーネントレベル VRT は、ざっくり言うと次の 2 つに分かれます。

VRT 対象のコンポーネントを描画するアプリケーション（アプリケーションサーバーとして立ち上がる）
そのブラウザにアクセスして、1 つずつ見た目をチェックしていくテスト側

[ *.story.tsx ]
      │  main.tsx が探し出して描画
      ▼
[ index.html + main.tsx ]  ──►  VRT 用アプリサーバー
                                      ▲
                                      │ アクセスしてスクリーンショット比較
                                [ *.spec.ts ]

用意するもの

そのため、VRT を行うにあたって事前に準備が必要なのは以下です。

ファイル	役割
`index.html`	本番アプリとは別の VRT 用エントリポイント。テストのアクセス先になる
`main.tsx`	`index.html` 内でどのコンポーネントをどう描画するかを定義する
`*.story.tsx`	VRT 対象のコンポーネントを定義するファイル（この拡張子が推奨）
`*.spec.ts`	テスト側。描画されたブラウザに対して検証を行う

main.tsx がやることはシンプルで、.story ファイルを探し出して、あとはループで 1 つずつ描画していくだけです。実際、行数としては 100 行にも満たないくらいのものでした。

ただし、「どのファイルを、どういう形で描画するか」はプロジェクトに合わせて自分で決めなければいけないのがポイントです。ここがかなりプロジェクト固有の判断になるため、公式が「エージェントを使ったほうが早い」と書いている理由もなんとなく理解できました。

既存の E2E テストとの共存

もともと Playwright で E2E テストも回していたので、E2E と VRT の両方を動かせる設定にする必要がありました。ここが地味に手間のかかるところです。

playwright.config.ts は projects を複数定義できるので、E2E 用と VRT 用でプロジェクトを分けました。

// playwright.config.ts のイメージ
export default defineConfig({
  projects: [
    {
      name: 'e2e',
      testMatch: /.*\.e2e\.spec\.ts/,
      use: { baseURL: 'http://localhost:3000' }, // 本番相当のアプリ
    },
    {
      name: 'vrt',
      testMatch: /.*\.vrt\.spec\.ts/,
      use: { baseURL: 'http://localhost:3100' }, // VRT 用アプリ
    },
  ],
});

ポイントは 2 つです。

baseURL をプロジェクトごとに設定する → E2E はこっちの URL、VRT はこっちの URL、とアクセス先を分けられる
どのファイルをテスト対象にするかを制御する → VRT のスペックファイルが E2E 側で拾われてしまわないよう、testMatch / testDir などで明示的に切り分ける