Playwright Agents を使ってみた。

Posted at 2025-11-04

実際に使ってみての感想は note に書いてます。
https://note.com/snjssk/n/n9b412df72307

Qiita では Playwright Test Agents のこと、セットアップ手順を書いておきます。

Playwright Test Agents とは

Playwright Test Agents は、Playwright v1.56 導入された。
この記事を書いている10月11日時点でGitHubに「released this 5 days ago」とあり、つい最近リリースされたばかりの新しい機能。Playwright Test Agents には3つのエージェントがある。

Getting Started

公式では
npx playwright init-agents --loop=claude
これ一発で完結しているが、既に playwright を導入していた場合の手順などを書いておく。

構成

既存のPlaywright: v1.55.0がインストール済み
既存のE2E構成: e2e/tests/ ディレクトリあり

  frontend/
  ├── e2e/
  │   ├── fixtures/
  │   ├── tests/
  │   └── utils/
  └── playwright.config.ts

セットアップ

v1.55.0 のままで以下のコマンドを叩くとエラーが出る。
これは init-agents がなく、init-agents はv1.56.0 から利用できるため。

npx playwright init-agents --loop=claude
# error: unknown command 'init-agents'

Playwrightのアップグレードするだけ
（@latest にしてますがバージョン指定するかは好みで）

pnpm add -D @playwright/test@latest playwright@latest

どんなファイルが作られるのか

それぞれエージェントの定義が3つ、MCP設定、Seedテンプレート、の5つ。
構成としては以下のようになる。

  frontend/
  ├── .claude/
  │   └── agents/
  │       ├── playwright-test-planner.md      # Plannerエージェント定義
  │       ├── playwright-test-generator.md    # Generatorエージェント定義
  │       └── playwright-test-healer.md       # Healerエージェント定義
  ├── .mcp.json                                # MCP設定
  ├── e2e/
  │   └── tests/
  │       └── seed.spec.ts                     # Seedテンプレート
  └── playwright.config.ts

3つのエージェント

（AIに日本語でまとめてもらいました）

1. Planner（playwright-test-planner）

役割

Webアプリを探索してMarkdown形式のテスト計画を作成する

利用可能なツール

ファイル操作: Glob, Grep, Read, Write
ブラウザ操作:
- browser_navigate - ページ遷移
- browser_click - クリック
- browser_type - テキスト入力
- browser_snapshot - スナップショット取得
- browser_console_messages - コンソールログ確認
- browser_network_requests - ネットワークリクエスト確認
- その他多数のブラウザ操作
専用: planner_setup_page - ページセットアップ（最初に1回実行）

ワークフロー

Navigate and Explore

planner_setup_pageを最初に1回実行
ブラウザスナップショットを探索
スクリーンショットは必要な時のみ
インタラクティブ要素、フォーム、ナビゲーションを特定

Analyze User Flows

ユーザージャーニーをマッピング
異なるユーザータイプと行動を考慮

Design Comprehensive Scenarios

Happy path（正常系）
エッジケース・境界条件
エラーハンドリング・バリデーション

Structure Test Plans

明確なタイトル
ステップバイステップの手順
期待される結果
開始状態の前提（常にクリーンな状態を仮定）

Create Documentation

アプリの概要
各シナリオをセクション分け
ステップを番号付き
Markdownファイルで保存

出力例

# TodoMVC Application - Comprehensive Test Plan

## Application Overview
アプリの機能説明...

## Test Scenarios

### 1. Adding New Todos
**Seed:** `tests/seed.spec.ts`

#### 1.1 Add Valid Todo
**Steps:**
1. Click in the "What needs to be done?" input field
2. Type "Buy groceries"
3. Press Enter key

**Expected Results:**
- Todo appears in the list with unchecked checkbox
- Counter shows "1 item left"

使用例

新機能のテストシナリオが必要な時
ECサイトのチェックアウトフローをテストしたい
ダッシュボードの包括的なテストカバレッジが欲しい

2. Generator（playwright-test-generator）

役割

Markdownのテスト計画を実際のPlaywrightテストコードに変換する

利用可能なツール

ファイル操作: Glob, Grep, Read
ブラウザ操作: click, type, navigate, wait_for など
検証ツール:
- browser_verify_element_visible - 要素の可視性確認
- browser_verify_text_visible - テキストの可視性確認
- browser_verify_value - 値の確認
- browser_verify_list_visible - リストの可視性確認
専用ツール:
- generator_setup_page - テストシナリオ用のページセットアップ
- generator_read_log - 生成ログの取得
- generator_write_test - テストファイルの書き込み

ワークフロー

テスト計画（全ステップ・検証仕様）を取得
generator_setup_pageでシナリオ用ページをセットアップ
各ステップと検証について:

Playwrightツールでリアルタイムに手動実行
ステップ説明をPlaywrightツールコールのintentとして使用

generator_read_logで生成ログを取得
generator_write_testで生成されたソースコードを書き込み

生成されるテストの特徴

単一テストを含むファイル
ファイル名はシナリオ名（ファイルシステムフレンドリー）
トップレベルのテスト計画項目に対応するdescribeブロック
テスト名はシナリオ名と一致
各ステップ実行前にステップテキストのコメント
ログからのベストプラクティスを常に使用

生成例

// spec: specs/plan.md
// seed: tests/seed.spec.ts

test.describe('Adding New Todos', () => {
  test('Add Valid Todo', async ({ page }) => {
    // 1. Click in the "What needs to be done?" input field
    await page.click(...);

    // 2. Type "Buy groceries"
    await page.type(...);

    // 3. Press Enter key
    await page.press(...);
  });
});

使用例

Plannerが作成したMarkdownテスト計画がある
ログインフローのテストが必要
複雑なチェックアウトフローを自動化したい

3. Healer（playwright-test-healer）

役割

失敗したPlaywrightテストをデバッグ・修復する

利用可能なツール

ファイル操作: Glob, Grep, Read, Write, Edit, MultiEdit
ブラウザ分析:
- browser_console_messages - コンソールメッセージ確認
- browser_network_requests - ネットワークリクエスト確認
- browser_snapshot - スナップショット取得
- browser_evaluate - JavaScript実行
- browser_generate_locator - ロケータ生成
テスト実行:
- test_list - テスト一覧取得
- test_run - テスト実行
- test_debug - テストデバッグ

ワークフロー

Initial Execution: 全テストを実行して失敗テストを特定
Debug failed tests: 各失敗テストでtest_debugを実行
Error Investigation: エラーで停止した際に:

エラー詳細を調査
ページスナップショットで状況把握
セレクタ、タイミング、アサーション失敗を分析

Root Cause Analysis: 根本原因を特定:

変更された要素セレクタ
タイミング・同期の問題
データ依存関係やテスト環境の問題
テストの前提を壊すアプリ変更

Code Remediation: テストコードを編集:

現在のアプリ状態に合わせてセレクタ更新
アサーションと期待値を修正
テストの信頼性と保守性を改善
動的データには正規表現を使用

Verification: 修正後にテストを再実行して検証
Iteration: テストが成功するまで繰り返す

重要な原則

体系的で徹底的なデバッグアプローチ
各修正の理由を文書化
クイックハックより堅牢で保守可能な解決策
Playwrightのベストプラクティスを使用
複数エラーは1つずつ修正して再テスト
何が壊れていて、どう修正したかを明確に説明
エラーが続き、テストが正しいと確信できる場合はtest.fixme()でスキップ
非インタラクティブ - ユーザーに質問せず、最も妥当な方法でテストを通す
非推奨APIは使わない - networkidle待機など

使用例

ログインテストが失敗している
最近の変更でテストが壊れた
user-registration.spec.tsが動かない

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up