Playwright Agents でサクッとE2Eテストを作ろう!
2025-10-17
azblob://2025/10/17/eyecatch/2025-10-10-how-to-playwright-agent-000.png

要約

Playwright MCP + Chrome DevTools MCP + Playwright Agents を使用すると、テストがめっちゃ簡単に書けます!

はじめに

お疲れ様です。

Playwright の最新バージョン 1.56 で、

ついに「Playwright Agents」という強力な新機能がリリースされました!

Release notes | Playwright

Playwright Agents

Playwright テストを構築するコア プロセスを通じて LLM をガイドするように設計された 3 つのカスタム エージェントを提供します。

  • 🎭 Plannerはアプリを探索し、Markdown テスト計画を作成
  • 🎭 Generator は、Markdown プランを Playwright Test ファイルに変換
  • 🎭 Healerはテストスイートを実行し、失敗したテストを自動的に修復

え・・・つまり?

AIが実装を調査してテスト計画書を作ってくれる!?

計画書をもとにテストを作ってくれる!?!?

失敗したテストは自動で修復してくれる!?!?!?

・・・そんな夢みたいな話あるわけないでしょ?

でも、もし本当に動くなら・・・革命的です。

ということで、今回はこの「Playwright Agents」を実際に触ってみて、本当に使えるのか検証してみました。

エージェント一覧

Playwright Agents は、次の3種類のエージェントを提供しています。

プランナー

Planner はアプリの構造を解析し、ユーザーフローに基づいたテスト計画書を Markdown 形式で自動生成してくれます。

使用に必要なのは以下の2点です。

  • 初期化用テストコード:seed.spec.ts
  • エージェントへの要求(例:「タスクを作成するシナリオのテストを作成してください。」)

さらに、要件定義書などのドキュメントを併用すると精度が上がるようです。

実行すると、Markdown 形式のテスト計画書が出力されます(後述)。

ジェネレーター

Generator は、テスト計画書をもとに実際のテストコードを生成します。

このとき使用する計画書は、Planner が作成したものでも、ユーザーが独自に用意したものでも構いません。

必要なのは以下の2点。

  • テスト計画書
  • エージェントへの要求(例:「シナリオテスト1を作成してください。」)

生成後、tests 配下に Playwright テストコードが出力されます。

ヒーラー

Healer は壊れたテストを修復するエージェントです。

内部では次のような流れで動作します。

  1. 失敗したステップを再実行
  2. UIを調査し、失敗箇所を特定
  3. 修正を提案
  4. テストが成功するまで再試行(またはループ停止まで)

修正不可能な場合(=テスト対象の機能自体が壊れていると判断した場合)は、自動でスキップしてくれるとのこと。

実際に使ってみる

ということで、実際にこの 3 種類のエージェントを試してみます。

テスト対象は Next.js で作った簡単な TODO アプリです。

このアプリには以下の機能があります。

  • タスクの追加
  • タスクの編集
  • タスクの削除
TODOアプリTODOアプリ:タスクの追加

インストール

今回はClaude Code に導入してみます。

ターミナルで以下のコマンドを実行します。

npx playwright init-agents --loop=claude

出力結果は以下の通りです。

$ npx playwright init-agents --loop=claude
Writing file: .claude/agents/playwright-test-generator.md
Writing file: .claude/agents/playwright-test-healer.md
Writing file: .claude/agents/playwright-test-planner.md
Writing file: tests/seed.spec.ts
Writing file: .mcp.json

なるほど、これでエージェントがコマンドとして使用可能になりました。

生成されたファイルは以下の通りです。

  • プランナー・ジェネレーター・ヒーラー各エージェントの Markdown ファイル
  • シードテストファイル
  • MCP Server の設定ファイル

.claude/agents/ 配下に格納されるため、アプリに合わせてカスタマイズも可能です。

エージェントファイル

 

プランナーを使ってみる

まずはプランナーから試してみます。

公式リファレンスによると、「アプリを解析してテスト計画を自動生成する」とのこと。

本当にそんなことができるのか…?

試しに次のように入力してみました。

@agent-playwright-test-planner
現状のアプリの実装を調査してテスト計画書を作成してください

しばらく待つと・・・生成完了!

計画書完成!

内容を確認してみましょう。

生成されたテスト計画書

おお、なんかよさそうだぞ・・・?

詳しく見ていきます。

まず、機能の洗い出しをしてくれているようです。

### 1.2 主要機能
本アプリケーションは、カンバン方式のタスク管理システムで、以下の機能を提供します:

1. **タスク管理**
   - タスクの作成・編集・削除
   - タイトル(最大100文字)
   - 詳細説明(最大500文字)
   - 締切日
   - タグ(複数選択可能)

2. **ステータス管理**
・・・

アプリの主要機能を抽出してくれています。

つぎはUI要素を確認してくれています。

### 1.3 主要UI要素

#### ヘッダー
- タイトル: "TODOリスト"
- ボタン: "やることをかく"(PlusIcon付き)

#### タスクボード
- 3つのカラム構成
- 各カラムにステータスドット(色分け)とカウンター表示

#### タスクカード
- サイズ: 320px × 200px
- ドラッグハンドル(グリップアイコン)
- 詳細メニュー(3点リーダー)
- タイトル(2行まで表示)
- 説明(3行まで表示)
- タグバッジ(色付き)
- 締切日(カレンダーアイコン付き)

#### タスクフォーム(モーダル)
- サイズ: 520px幅
- フィールド:
  - やること(必須、100文字以内)
  - いつまで(必須、日付選択 + 期間ショートカット)
  - くわしく(任意、500文字以内、複数行)
  - タグ(任意、複数選択ドロップダウン)
- ボタン:
  - 送信: "ついかする" / "なおす"
  - キャンセル: "やっぱりやめる"

こちらもちゃんと見れていそうです。

UI の構成要素も詳細に把握しており、フォームやモーダルのバリデーション条件まで含まれていました。
「Headless UI の Listbox」など、実装レベルの特定もできており、かなり賢い印象です。

つぎは肝心のテストシナリオですが・・・

#### シナリオ 3.1.1: タスクの新規作成(正常系)

**目的**: タスクを正常に作成できることを確認する

**前提条件**:
- アプリケーションが http://localhost:3000 で起動している
- ブラウザのLocalStorageがクリアされている(初期状態)

**テスト手順**:
1. ヘッダーの「やることをかく」ボタンをクリック
2. タスクフォームが表示されることを確認
3. 「やること」フィールドに「買い物に行く」と入力
4. 「いつまで」フィールドで明日の日付を選択
5. 「くわしく」フィールドに「牛乳とパンを買う」と入力
6. 「タグ」ドロップダウンから任意のタグを選択
7. 「ついかする」ボタンをクリック

**期待結果**:
- モーダルが閉じる
- 「やること」カラムにタスクカードが追加される
- タスクカードに入力した情報が正しく表示される
- 「タスクを追加しました」という成功アラートが右下に表示される
- アラートが3秒後に自動的に消える
- カラムのカウンターが「(1)」と表示される

**DOM要素**:
- ボタン: `button` に "やることをかく" テキスト
- フォーム: `role="dialog"` の要素
- 入力欄: タスク名入力は最初の `input` 要素
- 日付選択: `input[type="date"]`
- タグドロップダウン: Headless UI の `Listbox` コンポーネント
- カラム: `section` 要素に `aria-labelledby="column-title-todo"` 属性

**優先度**: High

かなり細かく書いてありますね!

実際のユーザー操作から期待値、優先度まで網羅的に書いてあります。

これがあれば確かになんなく実装できそうです。

確認したところ、全部で47件のテストが実装されていました!!

すごい!っと思う反面、内容が正常系はもちろん、

アクセシビリティ・メモリ・パフォーマンステストなどかなり多岐にわたり書いてくれているので

もしかしたら一つ一つのテストの精度は落ちてしまっているかもしれないです。

これについては正常・異常・境界値・アクセシビリティ・パフォーマンスなど、

テスト対象に応じてエージェントファイルを作成・実行するのが良いかと思われます。

つぎはテストデータが記載してあります。

### 4.1 タスクデータサンプル

```typescript
// 基本的なタスク
{
  id: "task-1",
  title: "買い物に行く",
  description: "牛乳とパンを買う",
  dueDate: "2025-01-15",
  tagIds: ["tag-1"],
  status: "todo",
  createdAt: "2025-01-10T10:00:00.000Z",
  updatedAt: "2025-01-10T10:00:00.000Z"
}

// 説明なしのタスク
{
  id: "task-2",
  title: "会議の準備",
  description: "",
  dueDate: "2025-01-12",
  tagIds: [],
  status: "doing",
  createdAt: "2025-01-09T14:30:00.000Z",
  updatedAt: "2025-01-09T14:30:00.000Z"
}

つぎはテスト環境です。

## 5. テスト環境

### 5.1 動作環境

- **ブラウザ**:
  - Chrome 最新版(推奨)
  - Firefox 最新版
  - Safari 最新版
  - Edge 最新版

- **OS**:
  - Windows 10/11
  - macOS
  - Linux

- **画面解像度**:
  - デスクトップ: 1920x1080 以上推奨
  - タブレット: 768px 以上
  - モバイル: 375px 以上

### 5.2 テストツール

- **E2Eテスト**: Playwright
- **ブラウザ開発者ツール**: Chrome DevTools
- **アクセシビリティ**: axe DevTools(Chrome拡張機能)
- **パフォーマンス**: Lighthouse

画面の解像度やツールまで書いてくれています!

特にツールではChrome DevToolsの記載があるので、

先日発表されたChrome DevTools MCP を併用してみるとより効率よくテストが実装できそうです。

AI エージェント用の Chrome DevTools(MCP)  |  Blog  |  Chrome for Developers

Chrome DevTools MCPで実現した次世代Web開発体験 | cloud.config Tech Blog

つぎは推奨事項(コーディング規約・実装パターン)が記載されています。

## 6. テスト実装時の推奨事項

### 6.1 Playwright テストのベストプラクティス

#### 6.1.1 Page Object Pattern の使用

#### 6.1.2 セレクタの優先順位

#### 6.1.3 待機処理

・・・

こちらもありがたいですね。

アプリ全体でテストの品質を担保できるよう実装サンプルも記載されているのは嬉しい点です。

以上が計画書の内容になります。

生成物としては驚くほど完成度が高く驚きました。

ジェネレーターを使ってみる

ということで、計画書ができたので実際にテストを書いてみます。

入力するのはこれだけ↓

@agent-playwright-test-generator
@tests\test-plan.md
このテスト計画書を参照し、シナリオ 3.1.1: タスクの新規作成(正常系)を実装してください。

数分待つと・・・生成完了!

テスト生成完了!テスト生成完了!1

ちゃんとテスト計画書のシナリオ通りにテストが作成されていそうです!

ヒーラーを使ってみる

では、作成されたテストを実行してみると・・・失敗しました。

テスト失敗!

しかし、ご安心ください。

ここで登場するのが最後のエージェントのHealerです。

入力するのはこちら↓

@agent-playwright-test-healer
@tests\task-creation.spec.ts
このテストが壊れているので直してください。
ChromeDevToolsMCPも併用してください。

今回は余計な実装・検証ループを防ぐため、Chrome DevTools MCP も併用します。

しかし、こんな曖昧な指示だけで本当に治るのでしょうか・・・?

数分後、以下の出力が。

修正完了!!

まさかの成功。テストが通りました。
恐るべし、Playwright Agents。

おわりに

今回試した Playwright Agents、正直想像以上の完成度でした。

テストケースの洗い出しから計画、実装、修正まで、すべて自動で完結。
AIによるテスト自動化の時代が、いよいよ現実味を帯びてきましたね。

それでは。