(ジェネレーターエージェントについても書きました。そちらもおねがいします)
はじめに
Playwright 1.56で導入された新機能「Test Agents」が気になっていたので、実際に使ってみました。この記事では、プランナーエージェント（🎭 Planner） を使ってPlaywright公式サイトのテストプランを自動生成する過程を、1から順を追って解説します。
Test Agentsとは？
Playwright Test Agentsは、AI駆動でテストの作成とメンテナンスを支援する3つのエージェントです：
- 🎭 Planner（プランナー）: アプリを探索してMarkdown形式のテストプランを生成
- 🎭 Generator（ジェネレーター）: Markdownプランを実行可能なPlaywrightテストに変換
- 🎭 Healer（ヒーラー）: テストを実行して失敗したテストを自動修復
今回は、プランナーエージェントにフォーカスして検証します。
環境構築
ステップ1: プロジェクトの初期化
まず、新しいディレクトリを作成してプロジェクトを初期化します。
mkdir try-playwright-agent
cd try-playwright-agent
npm init -y
実行結果:
{
"name": "try-playwright-agent",
"version": "1.0.0",
"description": "",
"main": "index.js",
"scripts": {
"test": "echo \"Error: no test specified\" && exit 1"
},
"keywords": [],
"author": "",
"license": "ISC"
}
ステップ2: Playwrightのインストール
Playwright Test Agentsを使用するには、Playwright 1.56以上が必要です。
npm install -D @playwright/test
実行後のpackage.json:
ステップ3: Playwright設定ファイルの作成
playwright.config.jsを作成します。今回はJavaScriptファイルで統一します。
npx playwright install chromium
playwright.config.jsの内容:
ステップ4: ディレクトリ構造の準備
プランナーエージェントが使用するディレクトリを作成します。
mkdir tests specs
ディレクトリ構造:
try-playwright-agent/
├── package.json
├── package-lock.json
├── playwright.config.js
├── tests/ # シードテストを配置
└── specs/ # 生成されたテストプランが保存される
シードテストの作成
プランナーエージェントは、シードテストを起点にしてページを探索します。シードテストとは、テスト対象のページを開くだけのシンプルなテストファイルです。
tests/seed.spec.jsを作成
このファイルの役割:
- プランナーエージェントの探索開始点を定義
- ページの初期状態（Playwright公式サイトのトップページ）を設定
- グローバルセットアップやフィクスチャがあれば、それらも実行される
プランナーエージェントの実行
ここからが本題です。プランナーエージェントを起動してテストプランを自動生成します。
Claude Code（またはAIツール）で実行
プランナーエージェントは、Claude CodeやVS Code Insiders（v1.105以上）などのAIツールと連携して動作します。今回はClaude Codeを使用しました。
実行したプロンプト（英語版）:
Explore the Playwright official website (https://playwright.dev/) and create a comprehensive test plan for the main navigation features and documentation access.
Use the seed file: tests/seed.spec.js
Please create a test plan that covers:
1. Navigation from homepage to documentation
2. Accessing the Test Agents documentation page
3. Verifying key navigation elements
Save the test plan as a Markdown file in the specs/ directory.
プランナーエージェントの動作
プランナーエージェントは以下の処理を自動で行います：
-
シードテストの実行 -
tests/seed.spec.jsを実行してブラウザを起動 - ページの探索 - Playwright公式サイトを自動で巡回
- 要素の識別 - ナビゲーション、リンク、ボタンなどを認識
- テストシナリオの生成 - 人間が読めるMarkdown形式で詳細なテストプランを作成
-
ファイルの保存 -
specs/ディレクトリに自動保存
生成されたテストプラン（英語版）
プランナーエージェントが生成したファイル：
生成されたテストシナリオの例
プランナーエージェントは15カテゴリ、45+個のテストシナリオを自動生成しました。
例: Test Agentsドキュメントへのアクセス
### 4. Accessing Test Agents Documentation
**Seed:** `tests/seed.spec.js`
#### 4.1 Navigate to Test Agents via Sidebar from Docs Home
**Steps:**
1. Navigate to https://playwright.dev/docs/intro
2. Locate the "Playwright Test" section in the sidebar
3. Verify the section is expanded
4. Click on "Agents" link (first item under Playwright Test)
**Expected Results:**
- Page navigates to https://playwright.dev/docs/test-agents
- Page title changes to "Agents | Playwright"
- Breadcrumb displays: Home > Playwright Test > Agents
- "Agents" link is highlighted in the sidebar
- Main heading displays "Playwright Agents"
注目ポイント:
- 具体的な手順が番号付きで記載
- 期待される結果が箇条書きで明確に記述
- URLやページタイトルなど、検証可能な具体的な値が含まれている
カバレッジ範囲
生成されたテストプランには以下のような幅広いシナリオが含まれています：
- Homepage Navigation Elements (3シナリオ) - トップページのUI確認
- Navigation from Homepage to Documentation (3シナリオ) - ドキュメントへの遷移
- Documentation Sidebar Navigation (3シナリオ) - サイドバーの操作
- Accessing Test Agents Documentation (4シナリオ) - Test Agentsページへのアクセス
- API Documentation Navigation (3シナリオ) - API参照の確認
- Search Functionality (3シナリオ) - 検索機能
- External Links and Social Media (3シナリオ) - 外部リンク
- Theme Toggle Functionality (2シナリオ) - テーマ切り替え
- Breadcrumb Navigation (2シナリオ) - パンくずリスト
- Language/Version Selector (3シナリオ) - 言語切り替え
- Table of Contents (3シナリオ) - 目次ナビゲーション
- Direct URL Access and Deep Linking (3シナリオ) - 直接URL指定
- Responsive Navigation (2シナリオ) - レスポンシブ対応
- Cross-Navigation Between Sections (3シナリオ) - セクション間遷移
- Edge Cases and Error Handling (3シナリオ) - エッジケースとエラー処理
日本語でも試してみた
プランナーエージェントが日本語にも対応しているか検証してみました。
実行したプロンプト（日本語版）
Playwrightの公式サイト（https://playwright.dev/）を探索して、検索機能に関する詳細なテストプランを日本語で作成してください。
使用するシードファイル: tests/seed.spec.js
以下の項目をカバーしてください：
1. 検索ボタンの表示確認
2. 検索モーダルの開閉
3. キーボードショートカット（Command+K）の動作
4. 実際に検索を実行して結果を確認
テストプランは日本語のMarkdownファイルとして、specs/ディレクトリに保存してください。ファイル名も日本語にしてください。
生成されたテストプラン（日本語版）
ファイル名：specs/検索機能テストプラン.md (556行)
ファイル名も日本語で生成されました！
ファイルの内容（抜粋）
# Playwright公式サイト - 検索機能 総合テストプラン
## アプリケーション概要
Playwright公式サイト（https://playwright.dev/）は、モダンなWebアプリケーション向けのE2Eテストフレームワークに関する包括的なドキュメントサイトです。本テストプランでは、サイトの主要機能の一つである検索機能に焦点を当てています。
### 検索機能の特徴
- **検索プロバイダー**: Algolia DocSearchを使用
- **アクセス方法**:
- ヘッダーの検索ボタン（「Search (Command+K)」）をクリック
- キーボードショートカット（Command+K / Ctrl+K）
...
よかったところ:
- 完全に日本語で記述
- 専門用語も適切に日本語化（「検索モーダル」「キーボードショートカット」など）
- 日本語固有のテストケースも含む（IME入力、マルチバイト文字など）
日本語版のカバレッジ
生成されたテストプランには10カテゴリ、35シナリオが含まれています：
- 検索ボタンの表示と基本UI確認 (2シナリオ)
- 検索モーダルの開閉 (3シナリオ)
- キーボードショートカット（Command+K）の動作 (3シナリオ)
- 検索実行と結果表示 (6シナリオ)
- キーボードナビゲーション (5シナリオ)
- マウスインタラクション (3シナリオ)
- 検索履歴とパーシステンス (2シナリオ)
- レスポンシブデザインとアクセシビリティ (3シナリオ)
- パフォーマンスとエラーハンドリング (3シナリオ)
- エッジケースと境界値テスト (5シナリオ)
日本語版の特徴的なテストケース
#### 10.2 日本語・マルチバイト文字での検索
**手順:**
1. Playwright公式サイトにアクセス
2. 検索モーダルを開く
3. 検索フィールドに日本語（例：「テスト」「ブラウザ」）を入力
**期待される結果:**
- 日本語入力が正常に処理される
- 該当する検索結果が表示される（存在する場合）
- 文字化けが発生しない
- IME入力が正常に動作する
セキュリティテストも含まれています:
#### 10.4 SQLインジェクション試行
**手順:**
1. Playwright公式サイトにアクセス
2. 検索モーダルを開く
3. 検索フィールドにSQLインジェクションパターン（例：「' OR '1'='1」）を入力
**期待される結果:**
- SQLインジェクションが防止される
- 検索結果が安全に処理される
- エラーメッセージに機密情報が含まれない
- アプリケーションが正常に動作し続ける
最終的なプロジェクト構造
try-playwright-agent/
├── package.json
├── package-lock.json
├── playwright.config.js
├── node_modules/
├── tests/
│ └── seed.spec.js # シードテスト
└── specs/
├── playwright-website-navigation.md # 英語版テストプラン（613行）
└── 検索機能テストプラン.md # 日本語版テストプラン（556行）
ファイルサイズの比較
$ ls -lh specs/
-rw-r--r-- 1 user staff 20K playwright-website-navigation.md
-rw-r--r-- 1 user staff 21K 検索機能テストプラン.md
プランナーエージェントの仕組み
内部で何が起きているのか
プランナーエージェントは、以下のような処理を行っています：
-
ページスナップショットの取得
- アクセシビリティツリーをYAML形式で取得
- 各要素のrole、accessible name、参照IDを含む
-
要素の探索
- クリック可能な要素を識別
- リンクの遷移先URLを取得
- フォーム要素や入力フィールドを認識
-
ページ遷移の追跡
- リンクをクリックして実際にページ遷移
- 遷移後のページ構造も解析
-
テストシナリオの生成
- 探索した情報を元に、人間が読めるテストプランを作成
- 手順と期待結果を明確に記述
従来の手作業との比較
| 項目 | 従来の手作業 | プランナーエージェント |
|---|---|---|
| 所要時間 | 数日〜1週間 | 数分 |
| 作業内容 | QAエンジニアが手動で仕様書作成 | AIが自動でページを探索して生成 |
| カバレッジ | 担当者の経験に依存 | 包括的（エッジケースも含む） |
| 言語対応 | 手動で翻訳が必要 | 多言語対応（英語・日本語など） |
| メンテナンス | 手動で更新 | 再実行で最新状態に更新可能 |
やってみてわかったこと
✅ 良かった点
-
圧倒的な効率化
- 数分で600行以上のテストプランが自動生成される
- 手作業なら数日かかる作業が瞬時に完了
-
包括的なカバレッジ
- 基本機能だけでなく、エッジケースやエラーハンドリングも含む
- アクセシビリティ、パフォーマンス、セキュリティのテストケースも生成
-
多言語対応
- 日本語でのプロンプトに完璧に対応
- ファイル名も日本語で生成可能
-
実用的な内容
- 具体的なURL、ページタイトル、要素名が含まれる
- そのままQAチームに渡せる品質
-
メンテナンスの容易さ
- サイトが更新されたら、再実行するだけで最新のテストプランが生成される
⚠️ 注意点
-
ボット検出サイトは注意
- Google.comなど、ボット検出が厳しいサイトでは使用が困難(現に、最初はこの検証をGoogle検索サイトでやってたんですが reCAPTCHAが表示されて探索が中断されてました)
-
AIツールとの連携が必要
- Claude CodeやVS Code Insiders（v1.105以上）が必要
- スタンドアロンでは動作しない
- まあでも、これはやるだけだしそこまでデメリットでもないかも
-
生成されるのはテストプラン
- 実際のテストコードは別途、ジェネレーターエージェントで生成する必要がある
- 後述するジェネレータエージェントが活躍してくるのかな
次のステップ：ジェネレーターエージェント
今回生成したMarkdownテストプランは、ジェネレーターエージェント（🎭 Generator） に渡すことで、実行可能なPlaywrightテストコードに変換できます。(これは次回にやってみるつもり)
まとめ
Playwright Test Agentsのプランナーエージェントを実際に使ってみて、以下のことがわかりました：
🎯 できること
- ✅ Webサイトを自動探索してテストプランを生成
- ✅ 英語・日本語の両方に対応
- ✅ 包括的なテストシナリオ（基本機能からエッジケースまで）
- ✅ 人間が読みやすいMarkdown形式で出力
- ✅ そのままQAチームに渡せる品質
💡 使いどころ
- 新しいWebアプリケーションのテスト計画作成
- 既存サイトのリグレッションテスト仕様書作成
- QA担当者の作業効率化
- テストカバレッジの洗い出し
🚀 今後の展望
今回はプランナーエージェントのみを試しましたが、Playwright Test Agentsの真価は3つのエージェントを連携させたときに発揮されます：
- Planner → テストプランを作成（今回実施）
- Generator → 実行可能なテストコードを生成（次回予定）
- Healer → 失敗したテストを自動修復（次回予定）
この3つを組み合わせることで、「テスト設計 → コード生成 → メンテナンス」までを自動化できます。
参考リンク
検証日: 2025-10-09
Playwrightバージョン: 1.56.0
使用ツール: Claude Code + Playwright MCP Server
今回の検証に使ったコードをgithubに上げてあります。よかったら手元で試してみてください(といっても生成された結果のファイル群なので試すもなにもないのだけど)
あと2つのエージェントについてもトライ中なので、近日中に記事書こうと思います。
株式会社SKIYAKIのテックブログです。ファンクラブプラットフォームBitfanの開発・運用にまつわる知見や調べたことなどを発信します。主な技術スタックは Ruby on Rails / React / AWS / Swift / Kotlin などです。 recruit.skiyaki.com/
Discussion