Playwright Test Agents × Claude Code Skillsで実現するプロダクション品質のE2Eテストコード自動生成

published

published

author

authorDisplayName

Yuichiro Suzuki

category

QA

frontend

mainImage

publishedAt

Dec 23, 2025

slug

Advent-Calendar-20251223

tags

advent calendar

QA

DevOps

1. はじめに

TL;DR

対象読者

• E2Eテストのメンテナンスコストに課題を感じているQA/テストエンジニア

• AIを活用したテスト自動化に興味がある開発者

• チームでE2Eテストの品質を標準化したいリーダー

2. 課題：なぜE2Eテストは維持できないのか

E2Eテストが維持困難になるよくある要因

既存アプローチとその特徴

• コード生成支援ツールとして優秀な能力を持つ。

• copilot-instructions.md 等を活用することで、プロジェクト固有のルールを適用させることが可能。

• ブラウザを直接操作できないため、実際の画面を見ながらのテスト生成ができない。

• 生成されたコードが実際に動くかどうかは、実行してみるまで分からない（ハルシネーションのリスク）。

• 2025年10月（v1.56）より公式導入された機能。

• MCPを通じてAIがブラウザを直接操作可能。

• 「画面を見て、操作して、テストコードを生成する」という理想的なワークフローを実現。

• 汎用性が高い反面、プロジェクト固有のルール（コーディング規約や独自ライブラリの使用など）が適用されにくい。

• 生成されたコードが、既存のコードベースと一貫しない（バラつきが出る）問題がある。

• 自己修復（Self-Healing）機能が強力。

• テストの生成から実行、失敗時の自動修復まで一貫してAIが担当。

• ベンダーロックインのリスクがあり、カスタマイズの自由度が制限される。

レベル別比較表

3. 解決策の全体像：Playwright Test Agents × Claude Code Skills

なぜClaude Codeなのか

なぜSkillsなのか

.claude/
└── agents/
    └── playwright-test-generator.md  # サブエージェント版

1. 呼び出しが煩雑
• Task toolで明示的に呼び出す必要がある
• 新規メンバーは「このエージェントを使う」という知識が必要

2. コンテキストの引き継ぎが限定的
• サブエージェントは独立したコンテキストで動作
• メインの会話コンテキストとの連携が弱い

3. 機能の存在に気づきにくい（Discoverabilityが低い）
• 「E2Eテストを書きたい」と言っても自動で使われない
• 明示的な指示が必要

Skillsの優位性

.claude/
└── skills/
    └── e2e-implement-skill/
        └── SKILL.md  # Skills版

---
name: e2e-implement-skill
description: NEWTプロジェクトのE2Eテストを実装するためのスキル。
  Playwrightを使用したPage Object Modelパターンに基づくテスト実装をサポートします。
---

移行のポイント

SKILL.mdの構成例

---
name: e2e-implement-skill
description: NEWTプロジェクトのE2Eテストを実装するためのスキル。
  Playwrightを使用したPage Object Modelパターンに基づくテスト実装をサポートします。
---

# E2E Test Generator for NEWT

## 使用条件
- E2Eテストの新規作成が必要な場合(詳細割愛)

## コーディング標準
[docs/e2e.md と同等の内容]
- Locator優先順位
- 待機処理ルール
- Page Object Model強制
- 認証パターン
- PC/SP分離ルール

## テスト生成フロー
1. 既存Page Objectを検索（packages/e2e/pages/）
2. MCPツールでブラウザ操作を実行
3. コード生成
4. 型チェック（pnpm -F @newt/e2e check-types）

## 実装例
[具体的なコード例]

4. 仕組みの中核：Generator AgentをSkillで制御する

Playwrightが提供する3つのAgent

npx playwright init-agents --loop=claude

公式Agentをそのまま使った場合の課題

1. プロジェクト固有のコーディング標準が適用されない
• 生成されたコードが既存のコードベースと一貫しない
• セレクターの選び方がプロジェクトの方針と異なる

2. Page Object Modelが強制されない
• 直接セレクターを使ったコードが生成される
• 既存のPage Objectを活用しない

3. 環境固有の対応が考慮されない
• reCAPTCHA、3DS認証等の特殊なフローに対応できない
• 認証状態の前提条件が不明確

4. PC/SPの分離が自動化されない
• レスポンシブ対応のテストが考慮されない
• ビューポート設定が手動で必要

NEWTでの解決アプローチ

Generator Skillのプロンプト構造

---
name: playwright-test-generator
description: NEWT旅行予約プラットフォーム向けのPlaywrightテスト生成エージェント
tools: [MCPツール一覧]
model: sonnet
---

# 役割定義
You are a Playwright Test Generator specialized for NEWT travel booking platform...

# コーディング標準（NEWT固有）
## Directory Structure
## Priority for Element Selection
## Waiting and Synchronization Rules
## Page Object Model Requirements
## Test Structure Requirements

# 認証システム
## Default Authentication Setup
## Test Fixtures

# コード生成優先ルール
## Priority 1: Element Selectors & Robustness
## Priority 2: Flow & Navigation from MCP Behavior
## Priority 3: Values & Test Data

# テスト生成ステップ
1. 既存Page Objectの検索（必須）
2. ブラウザ自動化の実行
3. テスト生成
4. 型チェック検証

# 実装例
[具体的なコード例]

5. NEWTのE2Eルールセット設計（AIに注入する規約）

5.1 要素選択（Locator）の優先順位

// 優先度1: セマンティック（最優先）
page.getByRole('button', { name: '検索する' })
page.getByLabel('出発地')
page.getByPlaceholder('都市や空港名')

// 優先度2: テキストベース
page.getByText('東京発')

// 優先度3: data-testid（最後の手段）
page.getByTestId('search-button')

// 避けるべき例
// page.locator("div[class^='Header_title']")
// → クラス名はビルド時に変更される可能性があり、テストが不安定になる

{コンポーネント名}-{variant1}-{variant2}

5.2 待機処理のルール

## Waiting and Synchronization Rules:
- **NEVER use arbitrary waits (sleep, wait)**
- Use URL or title assertions for navigation verification
- Use explicit conditional waits only when necessary

// 良い例: 明示的な条件待機
await expect(page).toHaveURL(/\\/tour\\/detail\\//)
await expect(page.getByRole('heading', { name: 'ツアー詳細' })).toBeVisible()

// 必要な場合の条件付き待機
await page.waitForURL(/\\/tour\\/detail\\//)
await page.waitForSelector('[data-testid="tourDetail-xxx"]')

public async waitForLoadingToComplete(): Promise<void> {
  const loadingText = this.page.getByText("読みこみ中です…");
  const isLoadingVisible = await loadingText.isVisible().catch(() => false);
  if (isLoadingVisible) {
    await loadingText.waitFor({ state: "hidden", timeout: 30000 });
  }
}

5.3 Page Object Model（POM）

## Page Object Model Requirements:
- All page classes must extend `BasePage`
- All component classes must extend `BaseComponent`
- Static elements as direct properties
- Dynamic elements as functions
- Page navigation methods must return new page objects

public searchButton = this.section.getByTestId("searchBox-submit");
public pageTitle = this.page.getByRole("heading", { name: "ページタイトル" });

public destinationButton = (label: string) =>
  this.section.getByRole("button", { name: label });

public tourItem = (title: string) =>
  this.page.getByRole("link", { name: title });

public async goToSearchPage() {
  await this.searchBox.searchButton.click();
  return new SearchPage(this.page);
}

NEWTでの実装例：旅行予約フローへの適用

TOP → 検索 → 一覧 → 詳細 → 予約入力 → 確認 → 決済 → 完了

// NEWTでの実装例
const tourTopPage = await new TourTopPage(page).open();
const searchPage = await tourTopPage.goToSearchPage();
const detailPage = await searchPage.selectTour("ハワイ5日間");

5.4 認証パターン

// 1. 未ログイン状態（サインインテスト用）
import { testNoAuth as test } from '@common/authUsingStorageState';

// 2. ログイン済み状態（通常テスト）- デフォルト
import { test } from '@playwright/test';

// 3. GMO決済認証（決済フロー）
import { testNeedGMOAuth } from '@common/authUsingStorageState';

// 4. Firebase認証（独立ユーザー）
import { test } from '@fixtures/firebaseAuth';

テストの目的は？
├─ サインイン/サインアウトのテスト → testNoAuth
├─ GMO決済が含まれる → testNeedGMOAuth
├─ 一般的なログイン済み機能 → デフォルト（storageState）
└─ 完全に独立した新規ユーザーが必要 → firebaseAuthPage

// CRITICAL: Set firebase_testing cookie BEFORE navigation
await page.context().addCookies([{
  name: 'firebase_xxx_testing',
  value: 'xxx',
  domain: 'hoge',
  path: '/'
}]);
// Only AFTER setting cookie, navigate to the page
await page.goto('<http://localhost:3000>');

5.5 PC/SP分離テスト

## Test Structure Requirements:
- **ALWAYS create separate tests for PC and SP (mobile)**
  - Use `test.describe('PC', () => { ... })` for desktop tests
  - Use `test.describe('SP', () => {
      test.use({ viewport: { width: 375, height: 667 } });
      ...
    })` for mobile
  - Pass `isMobile` parameter to Page Objects

test.describe('TC-1: サインイン', () => {
  // PC版テスト
  test.describe('PC', () => {
    test('未ログイン状態から電話番号でログイン', async ({ page }) => {
      const isMobile = false;
      const tourTopPage = new TourTopPage(page, isMobile);
      await tourTopPage.open();

      // PC用のセレクター（ヘッダーのログインボタン）
      await page.getByTestId('header-xxx-button').click();
      // ...
    });
  });

  // SP版テスト
  test.describe('SP', () => {
    test.use({ viewport: { width: 375, height: 667 } });

    test('未ログイン状態から電話番号でログイン', async ({ page }) => {
      const isMobile = true;
      const tourTopPage = new TourTopPage(page, isMobile);
      await tourTopPage.open();

      // SP用のセレクター（バナー）
      await page.getByRole('link', {
        name: '会員限定のおトクな情報をお届け 無料で会員登録'
      }).click();
      // ...
    });
  });
});

5.6 コード生成優先ルール

## Code Generation Priority Rules

### Priority 1: Element Selectors & Robustness (HIGHEST)
- 既存コードパターンから安定したセレクターを使用
- Click before fill パターン
- Loading状態のハンドリング
- `.first()` や `.nth()` で複数要素に対応

### Priority 2: Flow & Navigation from MCP Behavior
- MCPが観測したページフローを信頼
- 実際に動作したナビゲーション順序を採用
- 必要な中間ステップを省略しない

### Priority 3: Values & Test Data
- 既存の定数ファイルを使用
- MCPで成功した値を適用
- ハードコードではなく定数をimport

// 良い例
await page.getByTestId('login-phoneNumber-input').click();
await page.getByTestId('login-phoneNumber-input').fill('08000000001');

// 避けるべき例
await page.getByTestId('login-phoneNumber-input').fill('08000000001');
// → フォーカスが当たっていない状態でfillすると失敗することがある

// 良い例
import { TEST_USER } from '@constants/user';
await page.fill('[data-testid="phone"]', TEST_USER.PHONE_NUMBER);

// 避けるべき例
await page.fill('[data-testid="phone"]', '08000000001');
// → ハードコードは変更に弱い

6. 実践例：生成されたテストコード

// spec: specs/signin-test.md

import { testNoAuth as test } from '@common/authUsingStorageState';
import { expect } from '@playwright/test';
import { TourTopPage } from '@/pages/tour/TourTopPage';
import { TEST_USER } from '@constants/user';

test.describe('TC-1: サインイン', () => {
  test.describe('PC', () => {
    test('未ログイン状態から電話番号でログイン', async ({ page }) => {
      const isMobile = false;

      // Page Objectを使用してトップページを開く
      const tourTopPage = new TourTopPage(page, isMobile);
      await tourTopPage.open();

      // ヘッダーからログイン（PC用のセレクター）
      await page.getByTestId('header-xxx-button').click();

      // ログイン画面が表示されることを確認
      await expect(page).toHaveURL(/\\\\/signin/);

      // 電話番号でログイン
      await page.getByRole('button', { name: '電話番号で続ける' }).click();
      await page.getByTestId('login-phoneNumber-xxx').click();
      await page.getByTestId('login-phoneNumber-xxx').fill(TEST_USER.PHONE_NUMBER);
      await page.getByTestId('login-phoneNumber-xxx').click();

      // 認証コードを入力
      await page.getByTestId('login-verificationCode-xxx').click();
      await page.getByTestId('login-verificationCode-xxx').fill(TEST_USER.VALIDATION_CODE);
      await page.getByTestId('login-xxx-yyy').click();

      // Loading待機処理
      await expect(page.locator('text=Loading...').first()).not.toBeVisible();

      // ログイン完了確認
      await expect(page).toHaveURL('<http://localhost:3000/>');
    });
  });

  test.describe('SP', () => {
    test.use({ viewport: { width: 375, height: 667 } });

    test('未ログイン状態から電話番号でログイン', async ({ page }) => {
      const isMobile = true;

      // Page Objectを使用してトップページを開く
      const tourTopPage = new TourTopPage(page, isMobile);
      await tourTopPage.open();

      // SPではバナーをクリック
      await page.getByRole('link', {
        name: '会員限定のおトクな情報をお届け 無料で会員登録'
      }).click();

      // 以降は共通フロー...
    });
  });
});

7. 導入効果と限界、今後の展望

導入効果

1. そのまま使うにはPlaywright Test Agents公式だけでは不十分だった
• プロジェクト固有のルールを注入する必要がある
• コーディング標準、Page Object、認証パターン等

2. Generator Skillのプロンプト設計が品質を決める
• 詳細なプロンプトにより、一貫した品質のコードを生成
• 優先順位の明示、具体例の提示がポイント

3. 要素選択、待機処理、テストデザインの3つが核心
• セマンティックロケーター優先
• sleep/wait禁止、明示的な条件待機
• Page Objectの使用強制

4. サブエージェントよりSkillsが運用しやすい
• 自動判断による呼び出し
• チーム全体で一貫したルール適用
• バージョン管理による継続的改善

現時点での限界

• 複雑なビジネスロジックの判断: テストシナリオの設計自体は人間の判断が必要

• エッジケースの網羅: AIが自動的に境界値テストを設計するわけではない

今後の展望

• Healer Agentのカスタマイズによる自動修復の品質向上

• Planner Agentと既存Page Objectの連携

• テストカバレッジの自動分析との統合

参考資料

• Playwright Test Agents公式ドキュメント

• Playwright MCP Server (GitHub)

• Claude Code公式ドキュメント

• Claude Code Skills

• Model Context Protocol (MCP)

• Anthropic MCP発表

📣 1月のイベント開催のお知らせ

【1/28 開催！3社共催】モバイルアプリ開発 ✕ AI ー 組織・技術課題と向き合い、AIと走る

【3社共催】モバイルアプリ開発 ✕ AI ー 組織・技術課題と向き合い、AIと走る (2026/01/28 19:30〜)

# 📍 イベント概要 今回のNEWT Tech Talkは、"モバイルアプリ開発 x AI - 組織・技術課題と向き合い、AIとの走る"をテーマに開催します！ AIの進化が進む中で、モバイルアプリ開発の現場でも、AIとの付き合い方について話題にのぼることが増えてきています。 本イベントでは、モバイルアプリ開発の現場でAI活用に取り組む3社のエンジニアが、個人・チーム・技術課題それぞれの視点から、AIとどのように向き合い、どのように開発を前に進めてきたのかを率直に共有します。 抽象論だけでなく、実際の現場での工夫や失敗、学びを通して、モバイルアプリ開発におけるAIとの「現実的な走り方...

https://reiwatravel.connpass.com/event/378543/

【NEWT Chat リリース記念】AI × Travel Innovation Week 開催！

AI × Travel Innvation Week｜株式会社令和トラベル｜note

【NEWT Chat リリース記念】AI × Travel Innovation Week 開催！ 12月3日より、「NEWT Chat」誕生の裏側や開発ストーリーをお届けする特別企画 “AI × Travel Innovation Week” を令和トラベルのnote上で開催します。NEWT Chatのリリース背景、プロダクトの価値、開発体制、そして今後の展望など“舞台裏”を12月3日〜6日まで毎日公開予定です。特に、AIプロダクト開発に関わるエンジニア・PMの皆さまにとって学びの多い内容となりますので、ぜひご覧ください。

https://note.com/reiwatravel/m/m5c84fad89ff4

NEWT Chat — 魔法のAIエージェントチャット

旅行・サービス業界に特化した魔法のAIエージェントチャット。24時間365日、多言語でお客様対応と売上最大化を支援します。

https://newt.net/ja/aichat

令和トラベルでは一緒に働く仲間を募集しています

エンジニア採用 | 株式会社令和トラベル

令和トラベルのエンジニア採用ページです。「あたらしい旅行を、デザインする。」というミッションのもと、日本と世界をつなぐ、旅行の未来を創りたいエンジニアを募集しています。

https://www.reiwatravel.co.jp/engineers

1年間の感謝を込めた、”クリスマスセール🎄” 開催中！

クリスマスセール🎄【東京発】｜NEWT（ニュート）

クリスマスセール🎄開催中！人気エリアが超おトク「韓国¥18,800〜、パリ ¥129,800~、ハワイ ¥99,800~」など。お手ごろ旅も、ごほうび旅も特別価格！海外旅行・国内旅行のツアーやホテル予約はNEWT。

https://newt.net/sale?utm_source=tech_blog

📣宣伝