Playwright Agentsでのテスト自動化：最初の一歩

Last updated at 2025-12-18Posted at 2025-12-18

はじめに

この記事は、ヤプリ&フラー合同アドベントカレンダー Advent Calendar 2025 の18日目の記事です

自身が経験してきた課題

QAエンジニアとしてサービス品質に向き合ってきましたが、「効率的なテスト実施」 は、いつになっても最大の課題です。

特にWebサービスのE2E（End-to-End）テストの自動化は、その代表例です。

これまで、様々なアプローチを試してきました。

Seleniumでは、詳細なコードを書くことで高い柔軟性を得られましたが、テストケースが増えるたびに初期実装とメンテナンスのコストが増大し、かなり大きな負担となっていました。
ノーコード・ローコードツールの導入は、実装のハードルを下げましたが、複雑な操作への対応や、独自の業務ロジックへの柔軟な対応が課題として残ることもありました。
結果的に、自動化だけではカバーできず、リリース前はマニュアルテストに頼らざるを得ない状況に陥りがちです。

Playwright Agentsとの出会い

そんな中、私はPlaywright Agentsという、非常に興味深い機能に出会いました。これはAIを活用し、E2Eテストにおける最大のボトルネック、すなわち 「テストコードを書く手間」 と 「UI変更時のテストを直す手間」 を根本的に解決する可能性を秘めていると感じています。

本当にこのAgentsが、悩みを解消してくれるのでしょうか？
試していこうと思います！

Playwright Agents とは

Playwright Agentsは、一言で言うと 「AIがテストに関する面倒な作業を代わりにやってくれるPlaywrightの機能拡張」 です。

これは、従来のE2Eテスト自動化の課題である 「テストコードを書く手間」 と 「テストが壊れて直す手間」 を解決するために開発されました。

Playwright Agentsは何をしてくれるの？（3つの主要な役割）

Agentは、主に以下の3つの機能を利用できます

機能名	役割
Planner (プランナー)	テスト計画と実行
Generator (ジェネレーター)	テストコードを自動で生成
Healer (ヒーラー)	テストコード自己修復

Playwright Test Agentsの環境構築

Playwright Agentsを動かすには、通常の環境に加え、Python環境とVS Code拡張機能のセットアップが最もスムーズです。

前提とする環境

Node.js
Playwright
Python (3.9以上)
VS Code
claude code

Agentsのインストールとセットアップ

E2Eテストを書くプロジェクトルートにcdで移動してから下記コマンドを実行する

$ npx playwright init-agents --loop=claude

このコマンドを実行すると、必要なPythonライブラリのインストールと、VS CodeでAgent機能を利用するための初期設定が一括で完了します。

以下ファイルが生成される。

 🎭 Using project "" as a primary project
 🤖 .claude/agents/playwright-test-generator.md - agent definition
 🤖 .claude/agents/playwright-test-healer.md - agent definition
 🤖 .claude/agents/playwright-test-planner.md - agent definition
 🔧 .mcp.json - mcp configuration

Planner

対象のコードを探索してMarkdown形式のテスト計画を作成する

# 対象のURLを指定して、テスト計画を依頼
> @agent-playwright-test-planner [対象のURL]のテスト計画を作成してください。

⏺ サイトの包括的なテスト計画を日本語で作成いたしました。

  作成されたテスト計画の概要：

  9つの主要テストスイート:
  1. アプリケーション概要 - ツールの機能説明
  2. 機能テストスイート - 因子入力、水準入力、テストケース生成、結果表示
  3. UI/UXテストスイート - レスポンシブデザイン、アクセシビリティ、ダークモード
  4. 入力値検証テストスイート - 境界値テスト、無効入力テスト
  5. エッジケースとエラーシナリオテスト - 特殊ケース、パフォーマンス、エラーハンドリング
  6. クロスブラウザ互換性テスト - Chrome、Safari、Firefox、Edge対応
  7. モバイル対応テスト - iOS、Android対応
  8. セキュリティテスト - XSS対策、HTMLインジェクション対策

  テスト実行優先順位:
  1. 機能テスト（優先度：高）
  2. 入力値検証テスト（優先度：高）
  3. UI/UXテスト（優先度：中）
  4. クロスブラウザテスト（優先度：中）
  5. セキュリティテスト（優先度：中）
  6. パフォーマンステスト（優先度：低）

  このテスト計画に基づいて、実際のPlaywrightテストファイルを生成することも可能です。特定のテストケースについて詳細な実装を希望される場合は、お
  知らせください。

> テストプランは日本語のMarkdownファイルとして、specs/ディレクトリに保存してください。ファイル名も日本語にしてください。

生成結果例

## プロジェクト概要
ペアワイズテストツールは、以下の機能を提供するウェブアプリケーションです：
- テストファクタ（因子）とその水準の定義
- ペアワイズテスト手法を使用した最適なテストケース組み合わせの生成
- CSVファイルとしての結果エクスポート
- スタンドアロンHTMLとモダンなNext.js Reactベースの実装の両方を提供

## テスト環境設定
- **ベースURL**: https://s-iwahana.github.io/pairwise-testing/
- **ブラウザ**: Chrome、Firefox、Safari、Edge
- **デバイス**: デスクトップ、タブレット（iPad Pro）、モバイル（iPhone 12、Pixel 5）
- **言語**: 日本語（メイン）、英語フォールバック
- **テストデータ**: 様々なファクタ/水準の組み合わせ

---

## 1. コア機能のテストシナリオ

### 1.1 アプリケーションの初期化
**テストシナリオ**: アプリケーションが正しく読み込まれ、初期化されることを確認
- **前提条件**: クリーンなブラウザ状態
- **手順**:
  1. アプリケーションURLに移動
  2. ページが完全に読み込まれるまで待機
  3. ページタイトルに「ペアワイズ」または「Pairwise」が含まれていることを確認
  4. メインインターフェースが表示されていることを確認
  5. 少なくとも1つのデフォルトファクタが存在することを確認
  6. デフォルトファクタにサンプルデータ（ブラウザ、OSファクタ）があることを確認
- **期待される結果**: 
  - ページが3秒以内に読み込まれる
  - デフォルトファクタ「ブラウザ」と「OS」が事前に設定されている
  - すべてのUI要素が表示され、レスポンシブである

Generator

Plannerが作成したMarkdown計画を基に、実行可能なPlaywrightテストコードを生成する

# 生成されたMarkdownファイル名を指定して、テストコードの生成を依頼
> @agent-playwright-test-generator テスト計画書「テスト計画.md」に沿ったテストコードを作成してください [ファイル名].md

生成結果例

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

/**
 * 基本機能テストスイート
 * ペアワイズテストツールの主要機能をテスト
 */
test.describe('ペアワイズテストツール - 基本機能', () => {
  
  test.beforeEach(async ({ page }) => {
    // 各テストの前にページを読み込み
    await page.goto('/');
    // ページが完全に読み込まれるまで待機
    await page.waitForLoadState('networkidle');
  });

  test.describe('初期ページ読み込みテスト', () => {
    test('ページが正常に読み込まれる', async ({ page }) => {
      // ページタイトルを確認
      await expect(page).toHaveTitle(/ペアワイズ|Pairwise|All Pairs/i);
      
      // メインコンテンツが表示されることを確認
      const mainContent = page.locator('main');
      await expect(mainContent).toBeVisible();
      
      // 因子追加ボタンが表示されることを確認
      const addFactorButton = page.locator('button', { hasText: /因子|追加|Factor|Add/i });
      await expect(addFactorButton.first()).toBeVisible();
    });

    test('初期状態で少なくとも1つの因子が存在する', async ({ page }) => {
      // 因子カードが少なくとも1つ存在することを確認
      const factorCards = page.locator('[data-testid="factor-card"], .factor-card, [class*="factor"]');
      await expect(factorCards.first()).toBeVisible();
      
      // 因子名入力フィールドが存在することを確認
      const factorNameInput = page.locator('input[placeholder*="因子"], input[placeholder*="Factor"], input[type="text"]').first();
      await expect(factorNameInput).toBeVisible();
    });
  });

Healer

生成されたテストを実行します。もしUIに変更があった場合、自動でテストを修復する

# NG箇所の修正例
 > @agent-playwright-test-healer 
  XXXXX　を確認するテストケースがNGのようです　
  NG理由の報告と修正をお願いします

生成結果例

⏺ I'll use the playwright-test-healer agent to debug and fix the failing focus test case and provide a report
  on the NG reasons.

主要なNG理由

  1. フォーカステスト特有の問題:
    - 要素セレクタが実際のHTML構造と一致していない
    - input[placeholder*="因子"] や input[placeholder*="Factor"] 要素が存在しない

⏺ ボタンセレクタを更新します：

注意点

プロンプトの精度: 複雑なサービスほど、指示の具体性が求められる

人間による最終レビュー: AIの生成物を過信せず、QAの目での検収が必須

コストと非決定性: APIコスト管理と、実行のたびに結果が変わる可能性を考慮する

まとめ

今回の検証を通じて、Playwright Agentsの導入ハードルはそれほど高くなく、すぐに実戦投入のイメージが持てました。冒頭に挙げた課題に対しては、現時点で以下のような感触を得ています。

「テストコードを書く手間」の解消」：PlannerとGeneratorの連携により、ゼロからコードを書く時間は確実に削減されます。叩き台としての使い方でも十分な成果物となる。

「UI変更時のテストを直す手間」：Healerによる自動修復は、運用の安定性を見ていく必要はありますが、少なくとも「壊れた原因の特定」と「修正案の提示」までのステップは劇的に短縮されるはず。

「過去自動化の二の舞」にしないため過去の経験から、最初から欲張るとメンテナンスコストで自滅してしまうので、まずはPlannerで生成されたケースの中から、重要度の高いケースに絞ったミニマムな運用から開始してみようと考えています。

本記事では「触ってみた」体験に焦点を当てましたが、導入/運用編は改めて別記事でシェアしたいと思います！

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