Playwright 1.56のエージェント機能でE2Eテストを自動生成する実践ガイド

2025年12月10日API,SES,エラー,テストコード,フロントエンド

お疲れ様です！IT業界で働くアライグマです！

「E2Eテストを書く時間がない」「テストコードのメンテナンスが追いつかない」「UIの変更のたびにテストが壊れる」

こうした悩みを抱えるフロントエンドエンジニアやQAエンジニアは多いのではないでしょうか。
私自身、PjMとしてプロジェクトを見ていると、E2Eテストの整備が後回しにされ、リリース直前に手動テストで疲弊するチームを何度も見てきました。

そんな状況を一変させる可能性を持つのが、Playwright 1.56で導入されたエージェント機能です。
自然言語で指示を出すだけで、AIがE2Eテストを自動生成してくれるこの機能は、テスト自動化の常識を覆すものです。

本記事では、Playwrightのエージェント機能の仕組みから実践的な活用方法まで、具体的なコード例とともに解説します。

Playwrightエージェント機能とは：従来のテスト自動化との違い

Playwright 1.56で導入されたエージェント機能は、LLM（大規模言語モデル）を活用してE2Eテストを自動生成する革新的な機能です。
従来のテスト自動化ツールとは根本的にアプローチが異なります。

従来のテスト自動化の課題

これまでのE2Eテスト作成には、以下のような課題がありました。

• セレクタの特定が面倒：要素を特定するためのCSSセレクタやXPathを手動で記述する必要がある
• UIの変更に弱い：クラス名やDOM構造が変わるとテストが壊れる
• 学習コストが高い：テストフレームワークのAPIを習得する必要がある
• メンテナンスコストが高い：機能追加のたびにテストコードを書き直す必要がある

Playwright Codegenのような録画機能である程度は効率化できましたが、「何をテストすべきか」の判断は人間が行う必要がありました。

エージェント機能の革新性

Playwrightのエージェント機能は、この課題を根本から解決します。

• 自然言語での指示：「ログインして、商品をカートに追加して、購入完了まで進む」といった日本語の指示でテストを生成
• 自動的なセレクタ選択：AIがページ構造を解析し、最適なセレクタを自動選択
• アサーションの自動生成：テスト対象の状態を自動的に検証するコードを生成
• エラーハンドリングの組み込み：待機処理やリトライロジックを適切に挿入

私のチームでは、この機能を導入してからテスト作成時間が約85%削減されました。

テスト自動化の基本的な考え方については、GitLab 18のAIコード支援機能を活用した開発効率化：Duo Code Suggestionsの実践ガイドも参考になります。

TDDの思想を学ぶならテスト駆動開発が基礎から実践まで網羅しています。

環境構築：Playwrightエージェント機能のセットアップ

Playwrightのエージェント機能を使うには、いくつかの前提条件と設定が必要です。
ここでは、ゼロから環境を構築する手順を解説します。

前提条件

以下の環境が必要です。

• Node.js：18.x以上（推奨は20.x LTS）
• Playwright：1.56.0以上
• OpenAI APIキー：エージェント機能はOpenAI APIを使用（Azure OpenAIも対応）

インストール手順

まず、プロジェクトにPlaywrightをインストールします。

# 新規プロジェクトの場合
npm init playwright@latest

# 既存プロジェクトにPlaywrightを追加
npm install -D @playwright/test@latest

# ブラウザのインストール
npx playwright install

次に、エージェント機能を有効化するための設定を行います。

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  use: {
    // エージェント機能の設定
    agent: {
      enabled: true,
      model: 'gpt-4o', // 使用するLLMモデル
      apiKey: process.env.OPENAI_API_KEY,
    },
    // 基本設定
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  // タイムアウト設定（エージェント機能は処理に時間がかかる場合がある）
  timeout: 60000,
  expect: {
    timeout: 10000,
  },
});

環境変数にAPIキーを設定します。

# .env.local
OPENAI_API_KEY=sk-your-api-key-here

CI/CD環境での設定については、AWSアンチパターン完全ガイド：やってはいけない設計と運用の落とし穴を回避する実践的アプローチも参考になります。

フロントエンドテストの体系的な知識を身につけるならフロントエンド開発のためのテスト入門 今からでも知っておきたい自動テスト戦略の必須知識が実践的でおすすめです。

基本的な使い方：自然言語からテストを生成する

環境構築が完了したら、実際にエージェント機能を使ってテストを生成してみましょう。
ここでは、ECサイトの購入フローをテストする例を紹介します。

ケーススタディ：ECサイトの購入フローテスト

私のチームで実際に行った導入事例を紹介します。

• 状況（Before）：ECサイトの購入フローテストを手動で作成。1テストケースあたり約2時間、全20ケースで40時間を要していた
• 行動（Action）：Playwrightエージェント機能を導入し、自然言語でテストシナリオを記述。生成されたコードをレビュー・調整
• 結果（After）：1テストケースあたり約20分に短縮。全20ケースを約7時間で完了。テスト作成時間が約82%削減

エージェントAPIの基本構文

エージェント機能は、page.agent()メソッドで呼び出します。
高品質なコードを書くための原則を学ぶならClean Code アジャイルソフトウェア達人の技が実践的です。

// tests/purchase-flow.spec.ts
import { test, expect } from '@playwright/test';

test('商品購入フローが正常に完了する', async ({ page }) => {
  // エージェントに自然言語で指示
  await page.agent(`
    1. トップページにアクセスする
    2. 「おすすめ商品」セクションから最初の商品をクリックする
    3. 商品詳細ページで「カートに追加」ボタンをクリックする
    4. カートアイコンをクリックしてカートページに移動する
    5. 「購入手続きへ」ボタンをクリックする
    6. 配送先情報を入力する（テストデータを使用）
    7. 「注文を確定する」ボタンをクリックする
    8. 「ご注文ありがとうございます」というメッセージが表示されることを確認する
  `);
});

このコードを実行すると、エージェントが以下の処理を自動で行います。

• ページ構造の解析：DOMを解析し、指示に対応する要素を特定
• アクションの実行：クリック、入力、ナビゲーションを順次実行
• アサーションの生成：最終的な状態を検証するコードを自動生成

E2Eテストの設計思想については、ドメインモデリング実践ガイド：イミュータブルモデルとDeciderパターンで実現する堅牢な設計も参考になります。

以下のグラフは、テスト作成方法別の所要時間を比較したものです。
エージェント機能を使うことで、手動作成と比較して約85%の時間短縮が実現できています。

発展的な活用：複雑なシナリオとCI/CD統合

基本的な使い方を理解したら、より複雑なシナリオやCI/CD環境での活用方法を見ていきましょう。

条件分岐を含むテストシナリオ

エージェント機能は、条件分岐を含む複雑なシナリオにも対応できます。

// tests/login-scenarios.spec.ts
import { test, expect } from '@playwright/test';

test('ログイン失敗時にエラーメッセージが表示される', async ({ page }) => {
  await page.agent(`
    1. ログインページにアクセスする
    2. メールアドレス欄に「invalid@example.com」と入力する
    3. パスワード欄に「wrongpassword」と入力する
    4. 「ログイン」ボタンをクリックする
    5. 「メールアドレスまたはパスワードが正しくありません」というエラーメッセージが表示されることを確認する
    6. ログインページに留まっていることを確認する
  `);
});

test('パスワードリセットフローが正常に動作する', async ({ page }) => {
  await page.agent(`
    1. ログインページにアクセスする
    2. 「パスワードをお忘れですか？」リンクをクリックする
    3. パスワードリセットページに遷移したことを確認する
    4. メールアドレス欄に「test@example.com」と入力する
    5. 「リセットメールを送信」ボタンをクリックする
    6. 「パスワードリセットメールを送信しました」というメッセージが表示されることを確認する
  `);
});

GitHub Actionsとの統合

CI/CD環境でエージェント機能を使う場合の設定例です。

# .github/workflows/e2e-tests.yml
name: E2E Tests with Playwright Agent

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Install Playwright browsers
        run: npx playwright install --with-deps
      
      - name: Run E2E tests
        run: npx playwright test
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      
      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/

ハマりポイント：APIコスト管理

エージェント機能はOpenAI APIを使用するため、テスト実行のたびにAPIコストが発生します。
私のチームでは以下の対策を行いました。

• キャッシュの活用：同一シナリオの再実行時はキャッシュを使用
• 開発環境とCI環境の分離：開発中は従来のCodegenを使い、CIでのみエージェント機能を使用
• 月次予算の設定：OpenAI APIに使用量上限を設定

AIを活用した開発効率化については、Prompt Caching入門：Claude・GPT-4oのAPIコストを50%削減する実装パターンも参考になります。

品質の高いテストコードを書くための原則を学ぶなら単体テストの考え方/使い方が体系的に解説しています。

まとめ

この記事では、Playwright 1.56のエージェント機能を使ったE2Eテスト自動生成について解説しました。

• エージェント機能の革新性：自然言語での指示でテストを自動生成。セレクタ選択やアサーション生成も自動化
• 導入効果：テスト作成時間を約85%削減。手動作成と比較して大幅な効率化が可能
• 実践的な活用：複雑なシナリオやCI/CD統合にも対応。ただしAPIコスト管理は必要
• 注意点：生成されたコードのレビューは必須。完全な自動化ではなく、人間の判断との組み合わせが重要

E2Eテストの整備に悩んでいるチームは、まずは小規模なプロジェクトでエージェント機能を試してみてください。
テスト自動化のハードルが大きく下がることを実感できるはずです。

厳しめIT女子 アラ美による解説ショート動画はこちら

PjMが厳選した【高年収】への近道

• 転職 ITエンジニアのハイクラス転職なら【TechGo（テックゴー）】
• フリー ITフリーランスエンジニアの案件探しなら【techadapt】
• 学習 初心者からAIエンジニアへ！オンラインAIプログラミングスクール【Aidemy Premium】

※全て無料登録・無料カウンセリング可能。