Playwright Agents（公式名はPlaywright Test Agents）は、テスト計画を作るplanner、計画からテストを書くgenerator、落ちたテストを直すhealerの3つのエージェント定義です。npx playwright init-agents を1回実行すると、Claude CodeやVS Code、Codex、OpenCodeが読める形でプロジェクトに書き出されます。この記事では、1.65.1（2026年11月時点の最新）のソースと公式ドキュメントを読み、生成されるファイル、seedテストの書き方、3エージェントの回し方、生成テストをレビューで止める基準までを作業順にまとめました。
まとめ：Playwright Agentsを導入する前に決めておく4項目
- どのAIツールで回すか：
--loopは claude・codex・copilot・opencode・vscode・vscode-legacy の6値。値ごとに定義ファイルの置き場所が変わる。 - 既存の .mcp.json を守るか：claude を選ぶとリポジトリ直下の .mcp.json は playwright-test だけの内容で上書きされる。先に退避しておく。
- seedテストに何を書くか：plannerとgeneratorはseedを起点に画面を開く。ログインやテストデータの投入はここに寄せる。
- healerの修復をどこで止めるか：直せないと判断したテストは
test.fixme()で飛ばす規則になっている。PRの差分でfixmeと期待値の書き換えを必ず人が見る。
テストが1本も無い既存Webアプリで、計画と初版を短期間で揃えたい案件には向きます。検証環境が毎回変わる案件や決済画面では、生成より手書きのほうが総工数は小さく収まります。
Playwright Agentsの3役が受け取る入力と書き出す成果物
3つのエージェントは、それぞれ独立して呼んでも、順につないでも使えます。中身はLLMに渡す指示文と、Playwrightが用意したMCPツールの組み合わせです。モデルを動かすのは利用者側のAIツールで、Playwright自体が推論を行うわけではありません。
planner・generator・healerの役割分担と受け渡しファイル
公式のTest Agentsドキュメントでは、3役の入出力が次のように定義されています。受け渡しはすべてリポジトリ内のファイルなので、途中の成果物をGitで差分管理できる点がこの仕組みの肝です。
| エージェント | 入力 | 出力 |
|---|---|---|
| planner | 依頼文・seedテスト・任意のPRD | specs配下のMarkdown計画 |
| generator | specs配下の計画 | tests配下のテストファイル |
| healer | 失敗しているテスト名 | 修復済みかfixme付きのテスト |
plannerの出力は人が読める手順書で、generatorはそれを1シナリオ1ファイルのテストへ変換します。healerは生成直後に残りがちな初期エラーの掃除役という位置づけです。
1.56で追加されたTest Agentsと1.65.1時点の対応状況
Test Agentsは公式リリースノートの1.56の節で発表され、npmへの1.56.0の公開は2025年10月6日でした。2026年11月14日時点のnpmの最新は1.65.1です。1.56時点の案内に載っていた --loop は vscode・claude・opencode の3つでしたが、1.65.1のCLI定義では codex・copilot・vscode-legacy を加えた6つに増えています。VS Codeで使う場合、公式ドキュメントはVS Code v1.105以上を前提にしており、VS Code 1.105のリリースノートで手元の版と照らし合わせられます。公式は「Playwrightを更新したら定義を作り直す」運用を求めているため、版を上げるたびに init-agents を流し直す前提で考えてください。
Playwright MCPとTest Agents用MCPサーバーの使い分け
名前が似ていますが、Test Agentsが使うMCPサーバーは汎用の @playwright/mcp ではありません。init-agentsが登録するのは playwright-test という名前のサーバーで、起動コマンドは npx playwright run-test-mcp-server です。こちらはテストランナーと直結しており、test_run・test_debug・test_list といったテスト実行用のツールを持ちます。ブラウザを会話から操作して調べ物やフォーム入力をさせたいなら汎用のPlaywright MCP、テストを作って直したいならTest Agentsと分けて考えるのが実務的です。汎用版の設定はPlaywright MCPとは？使い方・料金・Dify連携の設定手順で扱っています。
init-agentsでエージェント定義を生成する導入手順とloop別の差
前提はPlaywright Testの導入済みプロジェクトです。playwright.config.ts が無い状態から始める場合は、Playwrightの使い方入門：E2Eテストを初期化から実行・CIまで書く手順の初期化を先に済ませてください。
npm導入からinit-agents –loop=claudeまでのコマンド
Claude Codeで回す場合の最小手順です。Test Agentsは1.56以上が必要なので、まず最新版へ上げてからブラウザを入れ、最後にエージェント定義を生成します。
# Playwright Testを最新版へ（1.56以上が必須）
npm install -D @playwright/test@latest
npx playwright install chromium
# Claude Code向けのエージェント定義を生成
npx playwright init-agents --loop=claude
# playwright.config.tsが複数プロジェクトを持つ場合はseed用を指定
npx playwright init-agents --loop=claude --project=chromium
# 計画・生成・修復のプロンプトも一緒に置く
npx playwright init-agents --loop=claude --prompts--project と -c はseedテストを探すプロジェクトと設定ファイルの指定です。--prompts を付けると、計画・生成・修復・カバレッジ用のプロンプトファイルが追加で置かれます。
–loopの6つの値と書き出されるエージェント定義の置き場所
1.65.1のgenerateAgents.tsを読むと、値ごとの出力先は次のとおりです。vscode を指定した場合もcopilotと同じ処理に入る点は、ドキュメントからは読み取りにくい挙動です。
| –loopの値 | エージェント定義 | MCP設定 |
|---|---|---|
| claude | .claude/agents（md） | .mcp.json（上書き） |
| codex | .codex/agents（toml） | tomlの中に記述 |
| opencode | .opencode/prompts | opencode.json |
| copilot・vscode | .github/agents | .vscode/mcp.json（追記） |
| vscode-legacy | .github/chatmodes | .vscode/mcp.json（追記） |
codexのファイル名はハイフンをアンダースコアに置き換えた playwright_test_planner の形になります。ソースのコメントによると、Codexのサブエージェント登録がハイフン入りの識別子を受け付けないためです。Claude Code側でのサブエージェントの読み込み規則はClaude Codeのsubagentsドキュメントに沿っており、3つの定義はいずれもフロントマターで model に sonnet を指定しています。
.mcp.jsonの上書きとWindowsでcmd経由になるMCP設定
claudeを選んだときの注意点は1つです。.vscode/mcp.json は既存の内容へ追記されるのに対し、リポジトリ直下の .mcp.json は playwright-test だけを登録した内容で丸ごと書き換えられます。ほかのMCPサーバーを登録済みなら、生成前に退避し、あとで項目を戻してください。macOSとLinuxで書き出される内容は次の形です。
{
"mcpServers": {
"playwright-test": {
"command": "npx",
"args": ["playwright", "run-test-mcp-server"]
}
}
}Windowsでは command が cmd、args の先頭が /c になり、cmd経由でnpxを呼ぶ形に変わります。チームでOSが混在するとコミットのたびに差分が出るため、どちらの形をリポジトリに置くか先に決めておきましょう。プロジェクト直下の .mcp.json は、Claude Codeを起動し直したときに利用の承認を求められます（Claude CodeのMCPドキュメントのproject scopeの節）。スコープの使い分けはClaude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例、ブラウザを動かすMCPを社内で許可する際の論点はPlaywright MCPのセキュリティ｜危険性とCVE-2025-9611対策にまとめています。テスト生成ではなく、Claude Codeに実装後の画面をPlaywright MCPで確かめさせる使い方はPlaywright MCPをClaude Codeで使う設定：登録・権限ルール・画面確認の手順で扱っています。
seedテストで認証と初期画面を用意してplannerに計画を書かせる
plannerとgeneratorは、どちらも最初にseedテストを実行してからブラウザを触ります。seedは「どの画面から、どの状態で探索を始めるか」を決める起点で、生成されるテストの手本にもなります。
seed.spec.tsの探索規則と既定で作られる空テストの中身
seed.tsのソースでは、対象プロジェクトのテストファイルのうち、ファイル名に seed を含む最初の1本をseedとして扱います。見つからなければ testDir 直下に seed.spec.ts を作り、中身は describe の中に空の seed テストを置いただけのものです。既存のテストに seed という語を含むファイル名があると、それが拾われる点は覚えておいてください。
import { test, expect } from '@playwright/test';
test.describe('Test group', () => {
test('seed', async ({ page }) => {
// generate code here.
});
});ログイン済みの状態から画面を探索させるseedテストの記述例と注意
空のseedのままだと、plannerはトップページから手探りで始めます。管理画面のように認証が要るアプリでは、ログインと初期画面への遷移をseedに書いておくと、計画が認証後の機能に集中します。次は環境変数から資格情報を読む例です。
import { test, expect } from '@playwright/test';
test.describe('Test group', () => {
test('seed', async ({ page }) => {
await page.goto('/login');
await page.getByLabel('メールアドレス').fill(process.env.E2E_USER ?? '');
await page.getByLabel('パスワード').fill(process.env.E2E_PASSWORD ?? '');
await page.getByRole('button', { name: 'ログイン' }).click();
await expect(page.getByRole('heading', { name: 'ダッシュボード' })).toBeVisible();
});
});相対パスの /login は、playwright.config.ts の baseURL を検証環境に向けていることが前提です。本番のURLや本番アカウントをseedに書かないでください。plannerはそこから画面を自由に操作するため、登録や削除のボタンも押し得ます。
plannerが保存するspecs配下のMarkdown計画の構成
plannerの定義ファイルは、最初に planner_setup_page を1回だけ呼び、画面のスナップショットを取りながら操作要素と遷移を洗い出し、planner_save_plan で保存する流れです。各シナリオには手順・期待結果・成功と失敗の条件を書き、開始状態は常にまっさらと仮定し、どの順で流しても成り立つ独立したシナリオにするよう指示されています。Claude Codeからは、サブエージェント名を示して依頼します。
playwright-test-planner エージェントで、商品検索からカート投入までの
テスト計画を作って specs/cart.md に保存して。
正常系に加えて、在庫0の商品と数量の上限超えも入れること。依頼文に境界条件を書かないと、計画は正常系に寄ります。業務上の制約（数量上限、締め時刻、権限ごとの表示差）は人が知っている情報なので、依頼文かPRDとして渡すほうが計画の網羅が上がります。
generatorでテストを書き出しhealerで失敗を修復する実行手順
計画のMarkdownをレビューで直したら、generatorに渡します。計画の段階で誤りを潰しておくと、後段で直す量が減ります。
generatorが1シナリオ1ファイルで書き出すテストの命名規則
generatorの定義ファイルには、1ファイルに1テスト、ファイル名はシナリオ名をファイルシステムで扱える形にしたもの、describe は計画の最上位項目、テスト名はシナリオ名と一致させる、という規則があります。各ステップの前に入るのは、計画の手順文を記したコメントです。generatorは generator_setup_page でページを開き、手順を実際にブラウザで実行してから generator_read_log でログを読み、generator_write_test で書き出します。ロケーターとアサーションは画面に当てて確かめた上で書かれるため、codegenで記録しただけのコードよりも初回から通りやすい作りです。
playwright-test-generator エージェントで specs/cart.md の
「1. カートへの追加」にあるシナリオをすべてテストにして。
# 書き出されたテストを流して状態を確かめる
npx playwright test tests/cart --reporter=listhealerがtest_runとtest_debugで失敗を追い込む修復の流れ
healerは test_run で全体を流して失敗を特定し、1件ずつ test_debug で再実行して、スナップショットからロケーター・待機・期待値のどれが原因かを調べます。修正のたびに再実行し、通るまで繰り返す指示です。healerの定義ファイルには、networkidle の待機や非推奨APIを使わない、動的なデータには正規表現のロケーターを使う、利用者に質問せず通すための最も妥当な手を打つ、という規則が並びます。テストランナー側のMCPサーバーは既定でブラウザを表示して動き、--headless を付けると非表示になります。
playwright-test-healer エージェントで tests/cart 配下の失敗を直して。
アプリ側の不具合と判断したものは直さず、理由を一覧で報告すること。依頼文の後半は、次の章で扱う「失敗を伏せる」挙動への歯止めです。定義ファイルの規則より依頼文が優先される保証は無いため、最終的な確認はPRの差分で行います。
AIが生成したテストの品質をレビューで担保する確認項目と止め方
生成テストの品質で崩れやすいのは、通すための変更が仕様の変更と区別されずに入る点です。レビューで見る場所を絞っておけば、差分の量が多くても見落としを減らせます。
healerのtest.fixmeが本物の不具合を隠す失敗パターン
healerの定義には「エラーが解消せず、テストが正しいと高い確信がある場合は test.fixme() を付ける」とあり、失敗する手順の前に理由のコメントを残す規則です。これは、アプリ側の不具合をテストが検出した状態でも、healerはテストを飛ばして緑にできることを意味します。リリース直前のブランチでhealerを回し、fixmeが増えたままマージされると、不具合を見つけたテストほど黙る結果になります。fixmeの追加はテストの修正ではなく不具合の報告として扱い、起票とセットでしか通さない運用にしてください。テスト設計の原則はE2Eテストのベストプラクティスで整理しています。
正規表現ロケーターと期待値の書き換えをPRの差分で見張るCI設定
もう1つの崩れ方は、期待値のゆるみです。表示文言が変わって落ちたテストを、healerが正規表現で幅を持たせて通すと、本来は検出すべき文言の誤りまで受け入れるロケーターになります。PRでテスト配下に fixme や正規表現の期待値が追加されたときだけCIを落とし、人のレビューを必須にする仕組みが手軽です。
# mainとの差分で、テストにfixmeが足されていたら失敗させる
git fetch origin main
if git diff origin/main...HEAD -- tests/ | grep -E '^\+.*test\.fixme'; then
echo "test.fixme が追加されています。不具合の起票と合わせてレビューしてください"
exit 1
fi
# 期待値やロケーターに正規表現が足された行を一覧で出す
git diff origin/main...HEAD -- tests/ | grep -E '^\+.*(toHaveText|getByText|name:)\(?.*/.+/' || true1本目は機械で止め、2本目は件数をPRコメントに出してレビュー者に見せる使い方を想定しています。正規表現がすべて悪いわけではなく、日付や件数のような動的な値には妥当です。固定の文言に正規表現が入った箇所だけを差し戻してください。
受託開発でPlaywright Agentsを採用する条件と見送る場面
Test Agentsは、テストを書く時間を減らす道具であって、何を検証すべきかを決める道具ではありません。採否は「計画をレビューできる人がいるか」と「検証環境が安定しているか」の2点で決まります。
テストが未整備の既存Webアプリで計画と初版の生成まで任せる条件
採用してよいのは、E2Eテストが無いか数本しかない既存のWebアプリで、検証環境とテスト用アカウントが用意でき、画面の仕様を知る人が計画のMarkdownをレビューできる場合です。この条件なら、plannerが書いた計画を仕様書の代わりに読み合わせ、generatorで初版を作り、以後は手で保守する流れで初期構築の工数を圧縮できます。逆に、生成したテストをhealer任せで保守し続ける運用は勧めません。修復のたびに期待値が少しずつゆるみ、半年後には何を守っているテストか誰も説明できなくなります。テストの生成からCIでの実行・レポート統合までを一続きで整えたい場合は、DevOps・CI/CD導入支援として、seedと検証環境の設計、PRでのfixme検知まで含めてご相談いただけます。
検証環境が不安定な案件や決済画面でAgentsを見送る判断基準
見送るのは次の場面です。第一に、検証環境のデータが日々入れ替わり、seedで同じ開始状態を作れない案件。plannerの「常にまっさらな状態」の仮定が崩れ、計画と実画面が食い違います。第二に、決済・送金・外部への通知を伴う画面。plannerは探索中にボタンを押すため、サンドボックスが無い環境では実害が出ます。第三に、テスト対象が数画面でシナリオが10本に満たない規模。init-agentsとレビューの手間のほうが、手書きの工数を上回ります。コーディングエージェント全般の向き不向きはCoding Agent（コーディングエージェント）とは：仕組み・3つの型と主要ツールの選び方で比較しています。
よくある質問
Playwright Agentsの導入前によく確認される点を、1.65.1時点のソースと公式ドキュメントに沿って回答します。
Playwright Agentsはどのバージョンから使えますか？
1.56で追加された機能で、npmへの1.56.0の公開は2025年10月6日です。2026年11月14日時点の最新は1.65.1で、--loop の選択肢は6つに増えています。古い版で作った定義は新しいMCPツールに追従しないため、Playwrightを上げたら npx playwright init-agents を同じ --loop で実行し直してください。
Claude Code以外のAIツールでも動かせますか？
Codex・OpenCode・GitHub Copilot・VS Codeでも動かせます。--loop に codex を渡すと .codex 配下にtoml形式の定義、opencode なら opencode.json とプロンプト、copilot と vscode なら .github/agents 配下の定義と .vscode/mcp.json が作られる仕組みです。VS Codeで使う場合、公式ドキュメントはv1.105以上を前提としています。
Playwright Agentsの利用に料金はかかりますか？
Playwright自体はオープンソースで、init-agentsにも追加料金はありません。費用が出るのは推論を担うAIツール側で、Claude CodeやCopilot、Codexの契約やAPIの従量課金に従います。3つの定義はフロントマターで sonnet を指定しているため、Claude Codeでは指定を変えない限りそのモデルで動きます。
Playwright MCPとPlaywright Agentsは何が違いますか？
汎用のPlaywright MCPは、会話の中でブラウザを操作させるためのサーバーです。Test Agentsはテストランナー直結の playwright-test サーバーを使い、テストの一覧・実行・デバッグのツールを持ちます。調査や操作の代行には前者、テストの作成と修復には後者が向きます。
healerが直したテストはそのままマージしてよいですか？
差分を人が見てからにしてください。healerは直せないと判断したテストに test.fixme() を付けて飛ばすため、アプリの不具合を検出したテストが黙ることがあります。fixmeの追加と、固定文言への正規表現の追加はCIで検知し、不具合の起票と合わせてレビューする運用が安全です。
関連記事
- Playwright（プレイライト）とは？仕組み・できること・Seleniumとの違いを解説：Test Agentsが動かしているPlaywright本体の仕組み
- Playwrightの使い方入門：E2Eテストを初期化から実行・CIまで書く手順【1.65対応】：init-agentsの前に済ませる初期化とCIへの組み込み
- Playwright CLIコマンド一覧｜test・codegen・installと1.63の新オプション：生成したテストを絞り込んで流すためのオプション
- Playwright MCPとは？使い方・料金・Dify連携の設定手順【Playwright 1.64対応】：テスト用ではない汎用のブラウザ操作MCP
- Claude CodeのMCP設定｜claude mcp addの書き方とスコープ・.mcp.json例【2026年11月】：init-agentsが上書きする .mcp.json の扱い方
