PlaywrightでE2Eテストを書こうとすると、最初に困るのが「どの操作をテストにするか」です。画面を見ながら手でテストケースを考え、セレクターを書き、失敗したら直す。この繰り返しは、思ったより時間がかかります。
Playwrightには、この流れを分担するPlanner・Generator・Healerという3つのTest Agentがあります。全部を一度に任せる魔法ではありませんが、計画、コード化、修正を分ける考え方はかなり実用的です。
3つのエージェントは何をするのか
公式ドキュメントでは、Plannerはアプリを操作してMarkdownのテスト計画を作り、Generatorはその計画からPlaywright Testを書き、Healerは失敗したテストを実行して修正を試みる役割です。
- Planner：画面を探索して、シナリオと期待結果を`specs/`に書く
- Generator：Markdownの計画を、実行できるテストファイルに変換する
- Healer：失敗したテストを再実行し、セレクターや待ち方の修正を提案する
つまり、いきなりコードを書かせるのではなく、いったん人間が読める計画を間に置きます。ここが大事です。テストの意図と、生成されたコードを別々に確認できるからです。
まずエージェント定義を生成する
既存のPlaywrightプロジェクトのルートで、次のコマンドを実行します。
npx playwright init-agents --loop=claudeVS Code向けなら`–loop=vscode`、OpenCode向けなら`–loop=opencode`を指定します。Playwrightのバージョンを更新したときは、エージェント定義も再生成してください。古い指示やツールのまま使い続けると、最新機能とのずれが出ちゃいます。
このコマンドで、プロジェクト内にエージェント定義と、計画・テストを置くための構成が用意されます。定義ファイルは普通のテストコードではなく、AIがPlaywrightを操作するための指示とツールの組み合わせです。
Plannerに画面を調べてもらう
Plannerには、テストしたいシナリオを具体的に伝えます。例えばTodoアプリなら、次のような依頼です。
ゲストとしてTodoを1件追加し、一覧に表示されることを確認するテスト計画を作ってください。ログインや初期データの投入が必要なら、seed testを用意します。
import { test } from './fixtures';
test('seed', async ({ page }) => {
// テスト環境を初期化する処理
});Plannerはseed testを実行して、必要なfixtureや初期化処理を使える状態にしてから画面を確認します。出力されるMarkdownには、アプリの概要、操作手順、各手順の期待結果が書かれます。
ここで一度、人間が計画を読みます。機能として存在しない期待結果が混ざっていないか、テストにしたい操作が抜けていないかを確認してください。コードになる前なら直すのが簡単ですね。
Generatorにコードを書かせる
Plannerの出力を確認したら、GeneratorにそのMarkdownを渡します。Generatorは計画を1手順ずつ実行し、実際の画面を見ながらロケーターとアサーションを決めます。
specs/basic-operations.mdの計画からPlaywright Testを生成してください。
seedはtests/seed.spec.tsを使ってください。生成されるコードは、例えば次のような形になります。
import { test, expect } from '../fixtures';
test('Todoを追加できる', async ({ page }) => {
const input = page.getByRole('textbox', {
name: 'What needs to be done?'
});
await input.fill('買い物');
await input.press('Enter');
await expect(page.getByText('買い物')).toBeVisible();
});ポイントは、Generatorが計画を読むだけでなく、セレクターを画面上で確認しながら書くことです。`getByRole`や`getByText`のような、意味のあるロケーターが選ばれます。ただし、生成コードを無条件に信じてはいけません。期待結果が弱い、テストデータが固定されすぎている、といった問題は普通に残ります。
失敗したらHealerに渡す
テストを実行して失敗したら、エラーだけを見てすぐにtimeoutを伸ばすのはおすすめしません。まず、どのステップで失敗したのかを確認します。
npx playwright test tests/todo/add-todo.spec.tsそのうえでHealerに失敗したテスト名を渡します。
tests/todo/add-todo.spec.tsの失敗を調べ、必要なら修正して再実行してください。Healerは失敗手順を再生し、画面上の近い要素や流れを調べ、ロケーターの変更や待ち方の調整を試します。修正後にもう一度テストを実行します。
ここで注意してください。Healerがテストを通したからといって、アプリの機能が正しいとは限りません。期待結果を弱くしたり、テストをスキップしたりして通す可能性もあります。スキップされた場合は、機能が壊れているのか、テストの前提が間違っているのかを人間が判断する必要があります。
3体を順番に使うと何が変わるのか
この3体は単独でも使えますが、順番に使うと役割がはっきりします。
- Plannerで、何を確認するかをMarkdownにする
- 人間が計画を確認し、不要なシナリオを削る
- Generatorで、画面に合わせたテストコードを作る
- テストを実行し、失敗したものだけHealerに渡す
- 修正されたコードと期待結果を人間がレビューする
この分担なら、AIに「全部テストして」と丸投げするより、どこで判断が入ったのかを追いやすくなります。特にMarkdownの計画が残るので、テストの目的がコードの細部に埋もれません。
最初は小さなシナリオで試しましょう
いきなり会員登録から決済までの長いフローを渡すのはおすすめしません。最初は「Todoを1件追加する」「検索語を入力して結果が表示される」のように、1つの目的に絞ってください。
長いフローは、どこで壊れたのかがわかりにくくなります。seed testで初期状態を作り、Plannerの計画を小さく分けるだけで、GeneratorとHealerの判断も安定します。
Playwright Test Agentsは、テストを書く作業を完全に自動化するものではありません。計画を作る人、コードを確認する人、壊れた機能を判断する人は必要です。
それでも、画面を調べて計画にし、コードに変換し、失敗箇所を直すという流れを3つに分けられるのは便利です。まずは小さな1シナリオで試してみてください。これ、意外と使えます。
詳しい仕様はPlaywright Test Agents公式ドキュメントと公式リリースノートを確認してください。エージェント定義はPlaywrightの更新で変わるため、記事のコマンドも執筆時点のものとして見てください。
コメント