「E2Eテストを書くのが面倒で後回しにしてしまう」
開発者なら誰でも経験がある話だ。Playwrightのテストコードを書くには、セレクタの調査、ロケーター設計、アサーション記述と手間がかかる。特にUIが頻繁に変わるプロダクトでは、テストコードのメンテナンスが追いつかなくなる。
Claude Codeは、Playwright MCPを通じてブラウザを直接操作しながら、E2Eテストを自動生成できる。ページを実際に動かしながらテスト対象を理解するため、セレクタの精度が高く、生成したコードが即動くケースが多い。
この記事では、4エージェントパイプラインを使ったPlaywright E2Eテスト自動生成ワークフローを、実際のコードと設定つきで解説する。
Claude Code × Playwrightの全体像
Claude CodeとPlaywrightの組み合わせには、大きく2つのアプローチがある。
| アプローチ | 使い方 | トークンコスト | 適した場面 |
|---|---|---|---|
| Playwright MCP | Claude Codeが直接ブラウザ操作 | 高（1セッション50k+） | 探索的デバッグ、スポットQA |
| Playwright CLI | コマンド経由でコード生成 | 低（MCPの約1/4） | 大規模プロジェクト、CI連携 |
| 4エージェントパイプライン | 役割分担した段階的生成 | 中（各エージェント限定実行） | チーム開発、本格的QA自動化 |
AIエージェントのテスト戦略全般については、AIエージェントのテスト戦略（ユニット・統合・E2E）も参照してほしい。
5分で動かすセットアップ
まずPlaywright MCPをClaude Codeに接続する。Node.js 18 LTS以上が必要だ。
# Playwright MCPをClaude Codeに追加
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
# Claude Codeを起動してからMCP追加
claude mcp add playwright npx @playwright/mcp@latest
# 接続確認
/mcp
# ヘッドレスモード（CI環境向け）
claude mcp add playwright npx @playwright/mcp@latest --headless
注意: @playwright/mcp を使うこと（@modelcontextprotocol/server-playwright は非推奨）。
接続後、Claude Codeに「このページのログインフローをテストするPlaywrightコードを書いて」と指示するだけで、実際にブラウザを動かしながらテストコードを生成してくれる。
4エージェントパイプライン：本格的なE2Eテスト自動化
スポットQAを超えて、チーム開発に使える品質のテストを量産するには、4つのエージェントを役割分担させるアーキテクチャが有効だ。
各エージェント間の引き渡しはすべてファイル経由で行う。オーケストレーターを設けず、シンプルな構造にするのがポイントだ（”Every handoff is a file on disk. No orchestrator.”）。
エージェント1: Exploration Agent（アプリの文脈把握）
アプリ全体を探索して app.context.md を生成する。セレクタよりも先に「このアプリが何をするのか」を理解させることで、後続エージェントの精度が上がる。
# app.context.md の例
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
## What this app does
- Core workflows: upload runs, view failures, triage flaky tests
- User roles: Owner, Admin, Member, Viewer
- Auth: email/password at /auth/login
- NOT in scope: billing, OAuth
## Critical business rules
- Admin can create/rotate/delete API keys; Member cannot
- Token visible in response dialog on create only (NOT stored in UI)
- Test uploads are immutable after 5 minutes
エージェント2: Test Case Generation Agent（テスト仕様の策定）
context.mdをもとに、テストケースをMarkdown形式で作成する。この段階ではコードを書かず、「何をテストするか」だけを定義する。
エージェント3: Automation Agent（コード生成）
テスト仕様を実際のPlaywrightコードに変換する。CLIモードで実行することでトークンコストを抑制できる。
// tests/auth/global-setup.ts — マルチロール認証の設定例
// 動作環境: Node.js 18+, @playwright/test>=1.40.0
// 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
import { chromium, FullConfig } from '@playwright/test';
const roles = [
{ name: 'owner', email: process.env.OWNER_EMAIL! },
{ name: 'admin', email: process.env.ADMIN_EMAIL! },
{ name: 'member', email: process.env.MEMBER_EMAIL! },
];
async function globalSetup(config: FullConfig) {
const browser = await chromium.launch();
for (const role of roles) {
const context = await browser.newContext();
const page = await context.newPage();
await page.goto('/auth/login');
await page.getByLabel('Email').fill(role.email);
await page.getByLabel('Password').fill(process.env[`${role.name.toUpperCase()}_PASSWORD`]!);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('/dashboard');
// ログイン状態をファイルに保存
await context.storageState({ path: `tests/auth/${role.name}.json` });
await context.close();
}
await browser.close();
}
export default globalSetup;
// APIキー権限テストの例
// 動作環境: Node.js 18+, @playwright/test>=1.40.0
// 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
import { test, expect } from '@playwright/test';
// メンバーはAPIキーを作成できないことを確認
test.describe('API Key Permissions', () => {
test.use({ storageState: 'tests/auth/member.json' });
test('member cannot see Generate button', async ({ page }) => {
await page.goto('/settings?tab=api');
await expect(page.getByRole('button', { name: 'Generate' })).not.toBeVisible();
});
});
test.describe('API Key Rotation', () => {
test.use({ storageState: 'tests/auth/owner.json' });
test('rotate key captures token from response', async ({ page }) => {
await page.goto('/settings?tab=api');
const row = page.getByRole('row', { name: 'Production Key' });
// クリック前にレスポンスリスナーを登録（レースコンディション防止）
const responsePromise = page.waitForResponse(
(resp) => resp.url().includes('/api-key') && resp.request().method() === 'PUT'
);
await row.getByRole('button', { name: 'Rotate' }).click();
const response = await responsePromise;
const body = await response.json();
// トークンはUIに表示されないのでAPIレスポンスから取得
expect(body.data.token).toMatch(/^trx_/);
});
});
エージェント4: Maintenance Agent（テスト修復）
CIでテストが落ちたとき、失敗ログを分析してロケーターの修正案を提案する。自動適用は行わず、差分レビュー後に人間が承認する設計だ。
CI連携：GitHub Actionsとの統合
PRラベルトリガーでClaude Code QAエージェントを自動起動する設定例を示す。
# .github/workflows/ai-e2e.yml
# 動作環境: GitHub Actions, Node.js 18+
# 注意: 本番環境で使用する前に、必ずテスト環境で動作確認してください。
name: AI-Powered E2E Tests
on:
pull_request:
types: [labeled]
jobs:
e2e-test:
if: contains(github.event.label.name, 'run-e2e')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '18'
- name: Install dependencies
run: npm ci
- name: Start dev server
run: npm run dev &
env:
NODE_ENV: test
- name: Run AI QA with Claude Code + Playwright MCP
run: |
claude --print \
--mcp-config '{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--headless"]
}
}
}' \
"PR #${{ github.event.pull_request.number }} の変更内容を確認し、
主要なユーザーフローをPlaywrightでテストしてください。
変更点: ${{ github.event.pull_request.title }}"
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
【要注意】よくある失敗パターンと回避策
失敗1: app.context.mdを省略する
❌ いきなりテストコード生成を指示する
⭕ まずアプリの文脈ファイルを作らせてから生成を指示する
なぜ重要か: context.mdなしではエージェントがDOMを総探索し、汎用的なスクリプトしか生成されない。ビジネスルールを理解した精度の高いテストが書けない。
失敗2: 自動化エージェントにMCPを使う
❌ 全フェーズでMCPを使用
⭕ 探索フェーズはMCP、生成フェーズはCLI
なぜ重要か: MCPはDOMスナップショット取得で1セッション50,000トークン以上消費する。Automation AgentはCLIで実行するとトークンコストが約1/4に下がる。
失敗3: 並列実行でデータ依存テストが壊れる
❌ すべてのテストをデフォルトで並列実行
⭕ データ依存テストに test.describe.serial() を使う
なぜ重要か: 「作成→取得→削除」のように順序依存するテストを並列実行すると、前のテストの状態を拾えずに失敗する。
失敗4: Maintenance Agentの修正を自動適用する
❌ テスト失敗 → エージェントが自動で修正してコミット
⭕ エージェントが差分提案 → 人間がレビューして承認
なぜ重要か: 自動適用はパーミッションに関わる修正を無音でカバレッジから除外するリスクがある。修正の承認は必ず人間が行うこと。
参考・出典
- Create Playwright tests with Claude Code: 4 Agents Pipeline — TestDino（参照日: 2026-04-11）
- Building an AI QA Engineer with Claude Code and Playwright MCP — alexop.dev（参照日: 2026-04-11）
- Playwright MCP & Claude Code: AI-Powered Test Automation Guide — Testomat（参照日: 2026-04-11）
- Write automated tests with Claude Code using Playwright Agents — Shipyard（参照日: 2026-04-11）
- claude-code-test-runner: An automated E2E natural language test runner — GitHub / firstloophq（参照日: 2026-04-11）
まとめ：今日から始める3つのアクション
- 今日やること：
claude mcp add playwright npx @playwright/mcp@latestを実行して接続を確認。既存の1ページでテスト生成を試してみる。 - 今週中：
app.context.mdを作成して、主要ユーザーフロー5〜10件のテストケースを生成する。4エージェントパイプラインの探索フェーズから始めると効率が良い。 - 今月中：GitHub ActionsにCI連携を実装し、PR時の自動E2Eテストをチームのワークフローに組み込む。
あわせて読みたい:
- AIエージェントのテスト戦略（ユニット・統合・E2E） — テスト設計の全体像
- AIエージェント構築完全ガイド — エージェント設計の基礎から応用まで
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。早稲田大学法学部在学中に生成AIの可能性に魅了され、X（旧Twitter）で活用法を発信（@SuguruKun_ai、フォロワー10万人超）。100社以上の企業向けAI研修・導入支援を展開。著書累計3万部突破。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
