Playwright Test Agents を Claude Codeで試してみた

はじめに

2025年10月、Playwright 1.56 のリリースとともに登場した Playwright Test Agents は、テスト計画の策定、テストケースの実装、そして継続的なメンテナンス。これら作業をAIに任せられるツールとして期待されます。今回は、実際のクイズアプリケーションを対象に Playwright Agents を使ったテスト自動化を試してみましたので、その体験をレポートします。

Playwright Test Agents とは

Playwright Test Agents は、Playwright 1.56 で導入されたAI駆動のテスト自動化ツールです。従来のテスト自動化では、開発者が手動でテストケースを設計し、コードを記述し、失敗したテストをデバッグする必要がありました。Playwright Agents は、これらのプロセスをAIエージェントが自律的に実行することで、テスト自動化の生産性を大幅に向上させます。

Playwright Test Agents は Model Context Protocol (MCP) を活用しており、VS Code Copilot、Claude Code、OpenAI GPT-4 などの様々なAIプラットフォームと連携できます。これにより、開発者は自然言語でテストの要件を伝えるだけで、AIエージェントが包括的なテストスイートを構築してくれます。

Playwright Test Agents の3つのエージェント

Playwright Test Agents には、それぞれ異なる役割を持つ3つのエージェントが用意されています。

🎭 Planner (プランナー)

役割: アプリケーションを調査し、テスト計画書を作成します。

Planner エージェントは、アプリケーションの構造を分析し、テストすべきシナリオやユーザーフローを特定します。正常系、異常系、エッジケース、セキュリティテストなど、様々な観点から網羅的なテスト計画を立案してくれます。

🎭 Generator (ジェネレーター)

役割: テスト計画書を基に、実行可能な Playwright テストコードを生成します。
Generator エージェントは、Planner が作成したテスト計画をもとに、実際に動作するテストコードを自動生成します。セレクタの検証やアサーションの確認を行いながら、テストを実装してくれます。

🎭 Healer (ヒーラー)

役割: テストを実行し、失敗したテストケースを自動的に修正します。
Healer エージェントは、テストの実行結果を分析し、失敗の原因を特定して自動的に修正を行います。デバッグ時間の削減に貢献します。

セットアップ方法

Playwright Test Agents のセットアップは下記のコマンド一つで、プロジェクトに必要なエージェント定義ファイルが自動生成されます。

npx playwright init-agents --loop=claude

--loop オプションには、使用するAIプラットフォームを指定します。

--loop=vscode: VS Code Copilot と連携
--loop=claude: Claude Code と連携
--loop=opencode: OpenAI GPT-4 と連携

このコマンドを実行すると、以下のファイルが生成されます。

.claude/agents/playwright-test-planner.md
.claude/agents/playwright-test-generator.md
.claude/agents/playwright-test-healer.md
.mcp.json
seed.spec.ts

実際に試してみた

今回は、Reactの社内研修で作った。以下の4画面を持つクイズアプリケーションを対象に、Playwright Test Agents を使ったテスト自動化を実践しました。

クイズ一覧画面
クイズ作成画面
クイズ挑戦画面
クイズ挑戦結果画面

・クイズ一覧画面

・クイズ作成画面

・クイズ挑戦画面

・クイズ挑戦結果画面

ステップ1: テスト計画書の自動作成

まず、Planner エージェントにテスト計画書の作成を依頼しました。

@agent-playwright-test-planner
クイズアプリについて、現状の実装を調査してテスト計画書を作成してください。
クイズアプリは下記画面があります。
・クイズ作成
・クイズ一覧
・クイズ挑戦
・クイズ挑戦結果

実行結果

Planner エージェントは以下の作業を自律的に実行しました。

package.json を読み込んでプロジェクト構成を確認
src/app/**/page.tsx パターンで画面ファイルを検索
各画面のソースコードを詳細に分析
包括的なテスト計画書 test-plan.md を作成

生成されたテスト計画書の内容

合計195以上のテストシナリオを含む詳細なテスト計画書が作成されました。
テスト計画書の内容はMarkdownで1700行ほどに及びました。生成AIに内容をまとめて貰った記載が下記です。

# クイズアプリケーション - テスト計画書サマリー
## 📋 概要
**アプリケーション**: クイズアプリケーション
**技術スタック**: Next.js 15.3.1, React 19.1.0, Redux Toolkit, TypeScript
**開発サーバー**: http://localhost:3000
**総テストシナリオ数**: 195+
---
## 🎯 主要機能
1. **クイズ一覧表示** - 作成されたクイズの一覧を表示
2. **クイズ作成** - 複数の問題と選択肢を持つクイズを作成
3. **クイズ挑戦** - クイズに回答し、結果を確認
4. **結果表示** - スコアとフィードバックメッセージの表示
5. **ダークモード対応** - テーマ切り替え機能
---
## 📊 画面別テストシナリオ数
| 画面 | テストシナリオ数 | 優先度 |
|------|-----------------|--------|
| クイズ一覧画面 (`/`) | 31 | 高 |
| クイズ作成画面 (`/quiz/create`) | 47 | 高 |
| クイズ挑戦画面 (`/quiz/[id]`) | 34 | 高 |
| クイズ結果画面 (`/quiz/[id]/result`) | 36 | 高 |
| 共通機能 | 24 | 中 |
| APIテスト | 13 | 高 |
| データ整合性テスト | 4 | 中 |
| ブラウザ互換性テスト | 6 | 低 |
---
## 🔍 主要テストカテゴリ
### 1. クイズ一覧画面（31シナリオ）
**機能テスト**:
- 初期表示の確認
- クイズカードの情報表示（タイトル、作成日、問題数）
- 空データ時の表示
**UIテスト**:
- レスポンシブデザイン（モバイル/PC）
- ホバー効果
- ダークモード表示
**画面遷移**:
- クイズ挑戦画面への遷移
- クイズ作成画面への遷移
### 2. クイズ作成画面（47シナリオ）
**機能テスト**:
- フォーム入力（タイトル、問題文、選択肢）
- 問題・選択肢の動的追加
- クイズ作成と保存
**バリデーションテスト（7種類）**:
- タイトル未入力
- 問題文未入力
- 選択肢不足（2つ未満）
- 正解未選択
- 空白のみ入力
- 複数問題でのエラー
**エッジケース**:
- 超長文入力（タイトル1000文字、問題文2000文字）
- 大量追加（選択肢20個、問題50個）
- APIエラー処理
- XSS対策
### 3. クイズ挑戦画面（34シナリオ）
**機能テスト**:
- 初期表示（問題文、選択肢、問題番号）
- 選択肢の選択・変更
- 問題間の遷移（次へボタン）
- 回答送信
**状態管理テスト**:
- Redux状態の初期化
- 回答の記録と保持
- 問題遷移時の状態更新
**エッジケース**:
- 存在しないクイズID（404エラー）
- 大量選択肢（10個以上）
- ブラウザリロード時の動作
### 4. クイズ結果画面（36シナリオ）
**機能テスト**:
- スコア表示（全問正解/一部正解/全問不正解）
- フィードバックメッセージの判定
- 100%: 「満点です！素晴らしい！」
- 70%以上: 「よくできました！」
- 50%以上: 「合格です！」
- 50%未満: 「もう一度チャレンジしてみましょう！」
**セキュリティテスト**:
- 回答データなしでの直接アクセス → ホームにリダイレクト
- 異なるクイズIDでのアクセス → ホームにリダイレクト
- データ整合性チェック
**スコア計算テスト（6パターン）**:
- 2問中0/1/2問正解
- 3問中0/1/2/3問正解
### 5. 共通機能（24シナリオ）
**ナビゲーション**:
- ヘッダー表示とリンク動作
- アクティブリンクの強調表示
**フッター**: コピーライト表示
**ダークモード**:
- 切り替え機能
- 設定の永続化
- 全ページでの適用
**レスポンシブデザイン**:
- モバイル（320px）
- タブレット（768px）
- デスクトップ（1920px）
**アクセシビリティ**:
- キーボードナビゲーション
- フォーカスインジケーター
- セマンティックHTML
**パフォーマンス**:
- 初期表示速度（2秒以内）
- 画面遷移速度
### 6. APIテスト（13シナリオ）
**GET /api/quizzes**:
- 正常取得（200）
- 空データ取得
- エラー処理（500）
**POST /api/quizzes**:
- 正常作成（201）
- バリデーションエラー（400）
- タイトル空
- 問題空
- 選択肢不足
- 正解インデックス未定義
- ID自動採番
- 作成日時自動設定
---
## ✅ テスト実行優先順位
### 優先度: 高（リリース前必須）
- クイズ一覧画面 - 機能テスト
- クイズ作成画面 - 機能テスト＋バリデーション
- クイズ挑戦画面 - 機能テスト
- クイズ結果画面 - 機能テスト＋セキュリティ
- APIテスト
### 優先度: 中（重要だが補助的）
- 全画面のUIテスト
- 画面遷移テスト
- 共通機能（ナビゲーション、ダークモード）
- データ整合性テスト
### 優先度: 低（時間があれば実施）
- エッジケース・異常系
- パフォーマンステスト
- ブラウザ互換性テスト
---
## 🚀 テスト実行方法
### 環境セットアップ
```bash
cd C:\develop\quiz-app
npm install
npm run dev # 開発サーバー起動
```
### 自動テスト（Jest）
```bash
npm test # 全テスト実行
npm run test:watch # ウォッチモード
npm run test:api # APIテストのみ
```
### E2Eテスト（Playwright）
```bash
npm run test:e2e # 全E2Eテスト実行
npm run test:e2e:ui # UIモード（推奨）
npm run test:e2e:debug # デバッグモード
npm run test:e2e:headed # ブラウザ表示モード
```
---
## 📁 データ構造
```typescript
Quiz {
id: number;
title: string;
createdAt: string;
questions: Question[];
}

Question {
questionText: string;
options: string[];
correctIndex: number;
}
```
**データファイル**: `data/quizzes.json`
---
## 🎨 テストカバレッジ
- **正常系**: すべての主要機能
- **異常系**: バリデーション、エラー処理
- **セキュリティ**: 不正アクセス防止、XSS対策
- **UI/UX**: レスポンシブ、ダークモード、ホバー効果
- **パフォーマンス**: 表示速度、遷移速度
- **アクセシビリティ**: キーボード操作、セマンティックHTML
---
## 📝 テスト記録項目
- テスト日時
- テスト実施者
- テスト環境（OS、ブラウザ、バージョン）
- テスト結果（合格/不合格）
- 不具合内容（不合格の場合）
- スクリーンショット
---
## 🔄 自動テストとの連携
### 既存の自動テスト
- `src/app/api/quizzes/__tests__/route.test.ts` - APIルート
- `src/lib/features/quiz/__tests__/quizSlice.test.ts` - Redux slice
- `src/utils/__tests__/quiz.test.ts` - ユーティリティ関数
- `src/components/__tests__/ThemeToggle.test.tsx` - コンポーネント
### 使い分け
- **自動テスト（Jest）**: ロジック、API、状態管理
- **手動テスト**: UI/UX、ビジュアル確認
- **E2Eテスト（Playwright）**: エンドツーエンドのユーザーフロー
---
## 📌 注意事項
1. テスト前に `data/quizzes.json` をバックアップ
2. テスト後に元のデータに戻す
3. テスト計画書は生きたドキュメント - 随時更新
4. 新機能追加時は該当セクションを参照し回帰テスト実施
5. リリース前は優先度「高」のテストをすべて実施
---
**文書バージョン**: 1.0（サマリー版）
**最終更新日**: 2025-11-23
**元ドキュメント**: `test-plan.md`

ステップ2: テストコードの自動生成

次に、Generator エージェントに、作成されたテスト計画書に基づいてテストコードを生成するよう依頼しました。

@agent-playwright-test-generator
テスト計画書「test-plan.md」に沿ったテストコードを作成してください。

実行結果

Generator エージェントは、テスト計画書を読み込み、59のテストケースを含む6つのテストファイルを自動生成しました。

作成されたファイル:

playwright.config.ts – Playwright設定ファイル
tests/quiz-list.spec.ts – クイズ一覧画面 (8テストケース)
tests/quiz-create.spec.ts – クイズ作成画面 (13テストケース)
tests/quiz-challenge.spec.ts – クイズ挑戦画面 (11テストケース)
tests/quiz-result.spec.ts – クイズ結果画面 (16テストケース)
tests/common.spec.ts – 共通機能 (11テストケース)

さらに、package.json にテスト実行用のコマンドも自動追加されました。

"test:e2e": "playwright test",
"test:e2e:ui": "playwright test --ui",
"test:e2e:debug": "playwright test --debug",
"test:e2e:headed": "playwright test --headed"

作成されたテストコードの実行

UIモードでのテスト実行が推奨されていたため、下記コマンドで実行しました。
npm run test:e2e:ui
テスト成功は27/55でした。テストの順番を無視して並行実行してしまったため、他のテストが他のテストに影響して失敗ケースが多い様に見えました。

ステップ3: テストの自動修復

テスト失敗したテストコードを全部修正するのは時間がかかりそうだったので、一旦クイズ一覧画面に関するテストについて、Healer エージェントに修正を依頼しました。

@agent-playwright-test-healer
クイズ一覧画面の失敗したテストについて、テストコードを修正してください。

実行結果

修正後のテスト実施と結果

npx playwright test tests/quiz-list.spec.ts

まとめ

Playwright Test Agents を実際に使用した際の作業時間は以下の通りです。

・plannerによるテスト計画書の作成に10分
・generatorによるテストコード作成に15分
・healerによるクイズ一覧のテストコード修正に5分

でこれだけのOutputが出せるのは生成AIならではだと思います。
Outputを仕上げるのには結構時間がかかりそうですが、たたき台作りには十分な作業効率アップが見込めそうです。
また、Planner、Generator、Healer という3つのエージェントを使い分けて指示を出していく進め方も興味深い体験でした。

Playwright Test Agents を Claude Codeで試してみた

はじめに

目次

Playwright Test Agents とは

Playwright Test Agents の3つのエージェント

🎭 Planner (プランナー)

🎭 Generator (ジェネレーター)

🎭 Healer (ヒーラー)

セットアップ方法

実際に試してみた

ステップ1: テスト計画書の自動作成

実行結果

生成されたテスト計画書の内容

ステップ2: テストコードの自動生成

実行結果

作成されたテストコードの実行

ステップ3: テストの自動修復

実行結果

修正後のテスト実施と結果

まとめ

参考リンク

生成 AI でスライド作成！Gemini 3 と NotebookLM のスライド生成を実際に試してみた

【AWS re:Invent 2025】Expoで面白い展示をたくさん見てきた

Figma AI ほぼ全機能使ってみた

生成AIをフル活用できるモノレポ構成について

Obsidianにターミナルを統合してGemini CLIを組み込む

Playwright Test Agents を Claude Codeで試してみた

はじめに

目次

Playwright Test Agents とは

Playwright Test Agents の3つのエージェント

🎭 Planner (プランナー)

🎭 Generator (ジェネレーター)

🎭 Healer (ヒーラー)

セットアップ方法

実際に試してみた

ステップ1: テスト計画書の自動作成

実行結果

生成されたテスト計画書の内容

ステップ2: テストコードの自動生成

実行結果

作成されたテストコードの実行

ステップ3: テストの自動修復

実行結果

修正後のテスト実施と結果

まとめ

参考リンク

関連記事Related Articles

Cursor ＋ Playwright MCPで開発中のWebアプリケーションの画面テストを自動化する

Generative AI Summit Osaka 実用的な生成AI

嘘をつかない！？ハルシネーションを抑制した生成 AI

“AI部下”と共に諦めるを諦めない世界戦

Claude for DesktopにMCPサーバーを追加する(Windows)