ラクスパートナーズ Advent Calendar 2025

@H-Iidain

株式会社ラクス

Playwright Test Agentsを使ってみたら感動した話

Last updated at 2025-12-19Posted at 2025-12-19

この記事は、ラクスパートナーズ AdventCalendar 2025の22日目の記事です。
（個人で25日連続投稿にチャレンジ中のカレンダーになります）

以前、以下の記事でPlaywrightの基本的な使い方をまとめました。

今回は話題のPlaywright Test Agentsについてまとめたいと思います。

Playwright Test Agentsとは

Test Agentsは、Playwrightのバージョン1.56でリリースされた機能です。
公式ドキュメントには、Playwright Agentsについて以下のように説明されています。

Playwright comes with three Playwright Test Agents out of the box: 🎭 planner, 🎭 generator and 🎭 healer.

These agents can be used independently, sequentially, or as the chained calls in the agentic loop. Using them sequentially will produce test coverage for your product.

🎭 planner explores the app and produces a Markdown test plan
🎭 generator transforms the Markdown plan into the Playwright Test files
🎭 healer executes the test suite and automatically repairs failing tests

引用元：https://playwright.dev/docs/test-agents#introduction

要約すると、Playwright Test AgentsはAIを使ってテストを自動的に実装してくれる機能です。

具体的には、以下3つのエージェントで構成されています。

planner：アプリを調査し、Markdown形式でテストの計画書を作成する
generator：計画書を元にしたテストコードを実装する
healer：作成したテストを実行し、失敗したテストを自動で修正する

これらを全てAIが自動でやってくれるのはすごいですね！

使い方

1. Playwright Test Agentの定義をプロジェクトに追加

まずは、以下のコマンドを実行することで、Playwright Test Agentの定義をプロジェクトに追加します。
（使用しているエディタ、コード支援ツールによってオプションが変わります）

VS Code
npx playwright init-agents --loop=vscode

Claude Code
npx playwright init-agents --loop=claude

Open Code
npx playwright init-agents --loop=opencode

完了すると、planner、generator、healerに命令を出せるようになります。
（ここからはVS Code前提で説明します）

2. plannerに計画書を作るよう指示

VS Codeの場合は、Copilotのチャットを開いて、「playwright-test-planner」を選択すればplannerに指示を出せるようでした。

あとは以下のように指示を出すと…

specs/test-plan.md という150行程度のテストの計画書を作成してくれました。
（Canvas APIを使って簡単な画像合成機能を入れたプロジェクトで試しています）

specs/test-plan.mdの内容

specs/test-plan.md

# 総合テスト計画書

## Application Overview

このViteアプリケーションの総合テスト計画書。目的は主要ユーザーフローの検証、UIコンポーネント（CanvasChild、HelloWorldなど）の機能確認、アクセシビリティ・エッジケース・エラーハンドリングを包括的にカバーすることです。各シナリオは独立して実行可能とし、前提は「新規ブラウザセッション（クリーン状態）」とします。

## Test Scenarios

### 1. Smoke Suite

**Seed:** `tests/seed.spec.ts`

#### 1.1. アプリ起動（ベーシック表示）

**File:** `tests/smoke.spec.ts`

**Steps:**
  1. ブラウザを起動しルートURL（`/`）にアクセスする
  2. ページが読み込まれるまで待機する
  3. ページタイトルまたは主要ヘッダー要素を確認する
  4. 主要コンポーネント（HelloWorld または CanvasChild）が存在するか確認する

**Expected Results:**
  - ページがHTTP 200でロードされること（ネットワークリクエストで確認）
  - 主要ヘッダー/タイトルが画面上に表示されること — 期待テキストが存在する
  - 主要コンポーネントのDOM要素がマウントされていること（見つからない場合は失敗）
  - 成功基準: ページが安定して表示されること。失敗条件: 404/5xx、主要要素が存在しない、読み込み中で止まる。

### 2. UI / コンポーネント検証

**Seed:** `tests/seed.spec.ts`

#### 2.1. HelloWorld コンポーネント表示とテキスト確認

**File:** `tests/ui.helloworld.spec.ts`

**Steps:**
  1. ルートにアクセスする
  2. `HelloWorld` コンポーネント（または表示される識別子）を探す
  3. コンポーネント内の主要テキスト・ボタン・リンクを確認する
  4. クリック可能要素があればクリックして反応を確認する

**Expected Results:**
  - 期待テキストが一致すること（例: 'Hello' 等）
  - クリックで期待されるUI変化やイベントが発生すること
  - 成功基準: 表示及び基本インタラクションが動作すること。失敗条件: テキスト不一致、クリック無反応、例外をコンソールで確認。

#### 2.2. CanvasChild 描画インタラクション

**File:** `tests/ui.canvas.spec.ts`

**Steps:**
  1. ルートにアクセスする
  2. `CanvasChild` が存在することを確認する
  3. Canvas上でマウスダウン→ムーブ→マウスアップのシミュレーションを行う
  4. 描画結果のDOM/CANVAS状態またはピクセル変化を検証する

**Expected Results:**
  - Canvas要素が見つかること
  - 描画操作をシミュレート後、Canvasに変化があること（描画された痕跡を確認）
  - 成功基準: ユーザーの描画操作に反応すること。失敗条件: 描画反応がない、例外が発生する。

### 3. エラーハンドリングとネットワーク

**Seed:** `tests/seed.spec.ts`

#### 3.1. オフライン/ネットワーク障害時の表示

**File:** `tests/network.offline.spec.ts`

**Steps:**
  1. ルートにアクセスする
  2. ネットワークを遮断（またはネットワークリクエストに故意のエラーを注入）
  3. エラーメッセージ/フォールバックUIが表示されるか確認する
  4. アプリが回復可能か（ネットワーク復旧で通常表示に戻るか）確認する

**Expected Results:**
  - ネットワーク障害時にユーザーへ分かる適切なエラー表示が出ること
  - 復旧後にアプリが再試行して正常表示に戻ること
  - 成功基準: 明示的なエラー表示と復旧動作。失敗条件: 画面が無反応のまま、例外でクラッシュする。

#### 3.2. APIエラー応答の表示検証

**File:** `tests/network.api-error.spec.ts`

**Steps:**
  1. ページをロードし、API呼び出しがトリガーされる操作を実施する（もしUIでトリガーがあれば）
  2. APIが400/500を返す状況をシミュレーションする
  3. UIがエラーメッセージを表示するか、該当UIがフェールセーフであるか確認する

**Expected Results:**
  - エラー状態に対してユーザー向けの説明的メッセージが出ること
  - 致命的でない限りアプリが継続して機能すること
  - 成功基準: 明示的なエラーハンドリング。失敗条件: 未処理例外やクラッシュ。

### 4. アクセシビリティ & レスポンシブ

**Seed:** `tests/seed.spec.ts`

#### 4.1. キーボード操作とフォーカス順

**File:** `tests/accessibility.keyboard.spec.ts`

**Steps:**
  1. ルートにアクセスする
  2. Tabキーでフォーカスを移動し、フォーカス順が論理的であることを確認する
  3. 主要ボタンでEnter/Spaceによりアクション可能か確認する

**Expected Results:**
  - キーボードのみで主要機能にアクセスできること
  - フォーカスが視覚的に確認でき、順序が自然であること
  - 成功基準: キーボード操作で致命的な機能欠落がないこと。失敗条件: キー操作で機能に到達できない、フォーカスが飛ぶ。

#### 4.2. レスポンシブ表示（モバイル／タブレット／デスクトップ）

**File:** `tests/responsive.spec.ts`

**Steps:**
  1. ルートにアクセスする
  2. ビューポートを複数サイズ（320x568, 768x1024, 1366x768）に切り替え表示を確認する
  3. レイアウト崩れ・重要な要素の重なり・タップ領域の極端な縮小がないか確認する

**Expected Results:**
  - 各ビューポートで主要UIが視認可能かつ操作可能であること
  - 成功基準: レイアウト崩れがないこと。失敗条件: 重要要素が見切れる、操作不可。

### 5. ネガティブ/境界値テスト

**Seed:** `tests/seed.spec.ts`

#### 5.1. フォーム入力のバリデーション（存在する場合）

**File:** `tests/validation.spec.ts`

**Steps:**
  1. 該当フォームがある前提でページをロードする
  2. 必須フィールドを空で送信する/異常値（長い文字列、特殊文字）を入力して送信する
  3. エラーメッセージが表示されるか確認する

**Expected Results:**
  - 適切なバリデーションメッセージが表示されること
  - 不正入力がサーバーへ送られないこと（フロント側で検出）
  - 成功基準: バリデーションが機能すること。失敗条件: 無効データが通る、UIが崩れる。

#### 5.2. 大量データ・パフォーマンス境界

**File:** `tests/performance.load.spec.ts`

**Steps:**
  1. もしリスト表示や大量項目ロードがある場合、意図的に大量データをレンダリングする
  2. レンダリング時間とUIフリーズの有無を観察する

**Expected Results:**
  - 大データロード時に致命的なクラッシュや長時間のフリーズがないこと
  - 成功基準: 許容範囲内の応答性（例: 初回レンダリング < 3s）。失敗条件: UIが操作不能、メモリ例外。

3. 計画書を元にテストコードを生成するようgeneratorに指示

今度はエージェントを「playwright-test-generator」にして、以下のように指示してみます。

すると、specs/test-plan.mdを参照したtests/smoke.spec.tsが生成されます。

tests/smoke.spec.ts

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

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

test.describe('Smoke Suite', () => {
  test('1.1. アプリ起動（ベーシック表示）', async ({ page }) => {
    // 1. ブラウザを起動しルートURL（/）にアクセスする
    const response = await page.goto('http://localhost:5173/');
    expect(response && response.status()).toBe(200);

    // 2. ページが読み込まれるまで待機する
    await expect(page).toHaveURL(/http:\/\/localhost:5173\//);

    // 3. ページタイトルまたは主要ヘッダー要素を確認する
    await expect(page).toHaveTitle('vite-project');

    // 4. 主要コンポーネント（HelloWorld または CanvasChild）が存在するか確認する
    const canvas = page.locator('#canvasId');
    await expect(canvas).toBeVisible();

    const saveButton = page.getByRole('button', { name: '保存する' });
    await expect(saveButton).toBeVisible();
  });
});

ただ、generatorはテストの実行までは行いません。そのため、ユーザーの手で
npx playwright test
を実行すると、テストが失敗する可能性もあります（上記のテストコードは問題なく成功しました）。

そこで、次はhealerの出番です。

healerでテストを修正する

healerに失敗したテストを修正してもらうよう指示します

※ Claude Codeを使っている方の記事では「テストが失敗するとその時点でhealerが自動で修正してくれる」そうなのですが、VS Codeでnpm playwright testを実行した時は何も起こりませんでした。そのため、今回は手動でhealerに指示を出しました。
（VS Codeでも自動修正する方法をご存知でしたらコメントいただけると嬉しいです）

まず、テストを失敗させるために、前項のサンプルのテストコードを以下のように書き換えます

// id名ではなくclass名で取得するよう変更
const canvas = page.locator('.canvasId');

npm playwright testを実行すると、無事(？)テストが失敗しました。

ここで、「playwright-test-healer」に、テストを修正するよう指示をします。

すると、

該当のテストコードを修正
再度実行し、tests/smoke.spec.tsのテストが全ブラウザで成功したことを確認

というフローを以下の画像のように自動でやってくれました。

いかがでしょうか？
以上が、Playwright Test Agentsの基本的な使い方となります。

私はnpx playwright codegenだけでも
「ブラウザの操作通りにテストコード実装してくれるなんて楽〜！」
と感動していた人間なので、自動でテストを実装してくれるPlaywright Test Agentsにはそれ以上に感動しました。
軽く使ってみた印象では、テストコードの精度もかなり高そうです。

E2Eテストは管理の大変さがネックだったりしますが、Playwright Test Agentsを使えば修正作業も非常に楽になりそうだと感じました。業務でも布教して、積極的に使用を検討していきたいと思います。

ここまで読んでくださり、ありがとうございました。

参考

以下参考にさせていただいた記事です。
ありがとうございました！

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