Playwright Agentを使ってみた

/ システム開発, テクノロジー / By

先日、Playwright Agentが公開されたことがにわかに話題でした。4月ごろにはPlaywright MCPでClaude CodeやChatGPTからブラウザ操作ができるようになっていましたが、Playwright Agentを使えばよりエージェントとして自律的にブラウザ操作をしてもらえるようです。公式ドキュメントの手順をなぞるだけですが、試しに使ってみました。

https://playwright.dev/docs/test-agents

環境

  • Windows 11
  • VSCode Insiders 1.106.0 (現在は安定版でOK)
  • VSCode 1.105.1
  • Node.js v22
  • playwright@1.56.1
  • GitHub Copilotが使えるアカウント

準備

VSCodeの準備

VSCodeであらかじめGitHubにログインし、GitHub Copilotを使えるようにしておきます。以前はVSCode Insiders（ベータ版）でないとエージェントに対応していませんでしたが、2025年10月31日時点では安定版のVSCode 1.105ではPlaywright Agentを使えるようです。

Playwrightのプロジェクト作成

続いて、適当なフォルダーをVSCodeで開き、Playwrightのプロジェクトを作ります。npx playwright installも事前に実行しておくとあとがスムーズです。

code .

npm init playwright@latest
npx playwright install

Playwright Agentを導入

公式ドキュメントの手順に沿ってPlaywright Agentをプロジェクトに導入します。

npx playwright init-agents --loop=vscode

こうすると .github/chatmodes にGitHub Copilot向けの Agent の設定ファイルが、.vscode/mcp.json に Playwright MCP の設定ファイルが作成されました。また「ここに実装してください」というコメントのあるテストコード tests\seed.spec.ts も合わせて作成されました。

実際に使ってみる

実際に使ってみます。ちょうどローカルで動いているEC-CUBEの環境が手元にあったので、今回はこのEC-CUBEのサイトを例にします。

Planner

まず使うのは Planner エージェントです。Planner はプロンプトに応じたテスト計画を立案して、Markdown形式で出力してくれます。

GitHub CopilotのチャットUIを開き、”Agent” や “Ask” などが選択できるドロップダウンに追加されている “Planner” を選択（画像参照）します。今回は「http://localhost:8080/ のECサイトについて、ログインして適当な商品を購入するフローをテストする。アカウントは ID: test@localhost / pw: password を使ってください」とだけ伝えました。ファイルに出力してくれないときもあるので、そのときはファイルの作成・書き込み権限があることを確認してから「保存して」みたいなプロンプトを渡します。

以降のステップではこのテスト計画が元となるので、意図通りのテスト内容になっているか、テスト方針に問題がないかなどを確認して修正します。
今回はとりあえず試すのが目的ですし、だいたい良さそうだったのでそのまま使います。

Generator

次にテスト計画に基づいてテストコードを生成してくれる Generator エージェントを使います。Generator エージェントは、Plannerが作ったMarkdownを読むだけではなく、Playwright MCPを使ってブラウザでサイトを操作しながらコーディングしてくれます。今回は「テスト計画に沿ってテストを実装してください」みたいなプロンプトにしました。

Playwrightのいろんな操作が度々発生するので、その都度、人間が許可する必要があります。何度も「許可」ボタンを押すのも面倒なので「このワークスペースで許可する」を選んでおくと便利です。また途中で止まることもあるので、そのときは「続行」とチャットを送信すると再開してくれます。

⚠️注意

接続先が本番環境など注意が必要な場合や意図しない操作を防ぎたい場合、「常に許可」は選ばず、面倒ですが毎回許可するようにしましょう。特に、Playwright MCPではなくシェル操作について「常に許可する」を選んでしまうと、想定外のコマンドを実行されてしまう危険性があります。意図しないファイル削除 (例: rm -rf /) などの危険もあるので、その都度内容を確認して許可するようにしてください。

Healer

最後にHealerエージェントを使います。Healerはテストの修正を自動で行ってくれるエージェントです。テストが失敗したときに「デバッグして修正して」とプロンプトを渡すと、エージェントが自力で修正案を考えてくれます。

テストの実行も自分でやってくれるので、失敗するテストを成功するように修正してほしいときは「デバッグして」だけの指示でも動作します。

もちろん修正内容を具体的に指示してもOKです。

最終的にできあがったコードはこのようになりました。実際にテストが動作します。

// spec: tests/ec_purchase_flow_test_plan.md

import { test, expect } from '@playwright/test';

test.describe('ECサイト購入フロー', () => {
  test('ログインして商品を購入する（ハッピーパス）', async ({ page }) => {
    // 1. サイトトップ（http://localhost:8080/）にアクセス
    await page.goto('http://localhost:8080/');

    // 2. 「ログイン」ボタンをクリック（環境依存文字を使わず部分一致で取得）
    await page.getByRole('link', { name: /ログイン/ }).click();

    // 3. メールアドレス欄に test@localhost を入力
    await page.getByRole('textbox', { name: 'メールアドレス' }).fill('test@localhost');

    // 4. パスワード欄に password を入力
    await page.getByRole('textbox', { name: 'パスワード' }).fill('password');

    // 5. 「ログイン」ボタンをクリック
    await page.getByRole('button', { name: 'ログイン' }).click();

    // 商品一覧ページへ遷移（部分一致で取得）
    await page.getByRole('link', { name: /more/ }).click();

    // 7. 商品名「キリマンジャロ」のみでフィルタし、「カートに追加」ボタンをクリック（価格変動に依存しない）
    await page.getByRole('listitem').filter({ hasText: 'キリマンジャロ' }).getByRole('button').click();

    // 8. 商品追加後は自動でカートページに遷移するため、URLで遷移を検証
    await expect(page).toHaveURL(/\/cart/);

    // 9. カート内に選択した商品（キリマンジャロ）が表示されていることを確認（aタグのみ検証）
    await expect(page.locator('a', { hasText: 'キリマンジャロ' })).toBeVisible();

    // 10. 「購入する」または「注文確定」ボタンをクリック
    await page.getByRole('link', { name: 'レジに進む' }).click();

    // 注文内容確認画面へ進む
    await page.getByRole('button', { name: '確認する' }).click();

    // 11. 購入完了画面（注文完了メッセージ）が表示されることを確認
    await page.getByRole('button', { name: '注文する' }).click();
    await expect(page.getByText('ご注文ありがとうございました')).toBeVisible();
  });
});

Tips / コツ

まだ試しに使ってみただけではあるのですが、上手く使うためにはいろいろな試行錯誤や工夫が必要そうかなと思います。ブログ記事という性質上省略してしまったのですが、実際には何度かやり直したりレビューしたりしたので、手間や知識が不要で全てやってくれるという訳ではありませんでした。

とは言え、AIエージェントがブラウザを使いながらコードを書く一連の動きを自律的に行ってくれるのは非常に便利です。自動テストには使い方次第でていろいろ活用、応用できそうです。まだ浅くしか使っていませんが、現段階で思ったコツを紹介します。

1つのテストを短く、シンプルに設計する

Playwright Healerエージェントに「デバッグして修正して」とプロンプトを渡すと、テストの実行＆修正を自力でループしてくれます。そのとき、実行時間が長いと、AIエージェントの作業時間がその分延びることになり不便です。特にPlaywrightのタイムアウトはデフォルトだと30秒ですが、テストが失敗したとき30秒待つことになってしまいます。5秒や10秒程度に短いタイムアウトに設定して、テストをすぐに成功 or 失敗を判定できるようにするのがおすすめです。

また長く複雑なテストケースは、AIにとっても人間にとっても修正が難しくなってしまいます。CI/CD環境で実行するときの費用にも直結するので、AIを使わない場合であってもテストケースは注意するべきです。

Agentの指示ファイルをカスタムしていく

npx playwright init-agents --loop=vscode で Playwright Agent を導入すると、.github/chatmodes にPlanner, Generator, Healerの3つエージェントの指示ファイルが作成されます。デフォルトのままでも概ね問題ありませんが、プロジェクトによって適宜調整していくのが良さそうかなと思います。

各エージェントモードで設定ボタンからMCPを有効/無効に設定すると、それに対応するMarkdownの指示ファイルの該当箇所が編集されます。そのため適宜 .github/chatmodes のMarkdownを保存し、Gitで管理してチーム内で共有するのがおすすめです

設計方針やプロジェクトのルールをドキュメント化する

ローカルではない検証環境にはBasic認証が設定されていたり、実際のプロジェクトにはいろいろな制約やテストする上でのベストプラクティスがあると思います。AIエージェントがそういった情報を知ることができないと、期待したようなテストの計画やコードを作ってくれません。

今回は、最初のプロンプトで「URLは http://localhost:8080 で、テスト用のログインアカウントは ID: test@localhost / pw: password です」としか伝えていませんでしたが、他に注意事項やルールなどをまとめた AGENT.md のようなドキュメントを作成し、最初のプロンプトで参照するようにすると良さそうです。

Gitを使う

AIエージェントには、自律的にテストコードやMarkdownを編集してもらいたいです。VSCodeではAIエージェントによる変更を承認するか却下するかを選べますが、実際には「編集してもらったやっぱり戻したい」という場合も多いです。Ctrl+Zでは限界があるので、Gitを使って作業ブランチにこまめにコミットしておくのが一番良さそうです。

コードフォーマッタを使う

AIエージェントが0から生成したコードはだいたい整っているのですが、既存コードを編集してもらうとインデントなどのスタイルがどんどん崩れていきます。AIの書いたコードを手作業で整形するのはあまりに虚無なので、コードフォーマッタを使うようにしたいです。

VSCodeなら Ctrl+Shift+P で開いたコマンドパレットに "format" と入力して、「ドキュメントのフォーマット」を選ぶと、設定されているコードフォーマッタでコードを整形してくれます。設定から “Formmat on Save” を有効にしていて、ファイル保存時に自動整形するようにしておくと便利です。また、実際のプロジェクトでは biome を導入して自動フォーマットを設定しておくのもおすすめです。

最後に

こういったAI系のツールについてはまだまだ発展中で、今後もどんどん進化したり別のものが出たりするはずです。正直なところ、現在の使い方が来年でも通用するかは疑わしいのですが、ツールを使う上での基礎知識は今のところは変わらなさそうかなと思います。最後のTipsに記載したように、テストケースの保守性を意識して設計するとか、AIエージェントが参照できるドキュメントを用意するとかのプラクティスは今後も大きく変わらないはずです。

「何ができるか分かるまでは様子見しよう」や「最適な手法が確立されてから検討しよう」といった姿勢だと何も出来ずに時が過ぎてしまうので、まずは試してみるトライアンドエラーの精神が大事なのかなと、自戒を込めて思いました。

こちらの記事もどうぞ