testing-e2e

E2E テストのパターン

Playwright 1.59 以降を使ったエンドツーエンドテスト、ビジュアルリグレッション、アクセシビリティ、AI エージェントのワークフローです。

クイックリファレンス

カテゴリ	ルール	影響度	使用する場面
バックエンドを emulate する	rules/emulate-e2e.md	高	最優先 — E2E 用の決定論的な API バックエンド
Playwright のコア機能	rules/e2e-playwright.md	高	セマンティックロケーター、自動待機、不安定なテストの検出
ページオブジェクト	rules/e2e-page-objects.md	高	ページ操作のカプセル化、ビジュアルリグレッション
AI エージェント	rules/e2e-ai-agents.md	高	Planner／Generator／Healer、init-agents
A11y Playwright	rules/a11y-playwright.md	中	WCAG 2.2 AA に準拠した axe-core による全ページスキャン
A11y CI/CD	rules/a11y-testing.md	中	CI ゲート、jest-axe のユニットテスト、PR のブロック
エンドツーエンドの型	rules/validation-end-to-end.md	高	tRPC、Prisma、Pydantic の型安全性

合計：7 つのルール、2 つのリファレンス、3 つのチェックリスト、1 つの例、1 つのスクリプト

上流ドキュメントの対象範囲（重複して記載しない）

Playwright、axe-core、jest-axe の使い方は、それぞれのドキュメントで説明されています。このスキルには OrchestKit 固有の差分（references/ork-delta.md）と、rules/ にあるプロジェクト内のサブセットのみを掲載しています。以下の情報が必要な場合は、ここに記載されていると想定せず、ベンダーのページを参照してください。

トピック	出典
スクリーンショット比較のワークフロー、ベースラインファイル、snapshotPathTemplate	https://playwright.dev/docs/test-snapshots
toHaveScreenshot のオプション：mask、maxDiffPixelRatio、stylePath、animations	https://playwright.dev/docs/api/class-pageassertions
認証の再利用：storageState、セットアッププロジェクト、IndexedDB	https://playwright.dev/docs/auth
page.route によるネットワークのインターセプト（プロジェクト内では引き続き emulate を最初に使用します。rules/emulate-e2e.md を参照）	https://playwright.dev/docs/mock
リリースごとに削除・変更された API（SKILL.md には以下の短い使用禁止リストのみを記載）	https://playwright.dev/docs/release-notes
ロケーター API の全容（プロジェクト内の優先順位は引き続き rules/e2e-playwright.md に記載）	https://playwright.dev/docs/locators
CI での Playwright ランナーのセットアップ（プロジェクト内の a11y ゲートのワークフローは引き続き rules/a11y-testing.md に記載）	https://playwright.dev/docs/ci
init-agents CLI フラグと生成ファイル（Planner／Generator／Healer のワークフローは引き続き rules/e2e-ai-agents.md に記載）	https://playwright.dev/docs/test-agents
jest-axe のマッチャーと configureAxe API（プロジェクト内のコンポーネント状態のサブセットは引き続き rules/a11y-testing.md に記載）	https://github.com/NickColley/jest-axe
Lighthouse CI の設定とスコアのアサーション	https://github.com/GoogleChrome/lighthouse-ci

WCAG 2.2 の達成基準、およびキーボード、スクリーンリーダー、コントラスト、ズームによる手動テストは、参照先に移していません。これらは checklists/a11y-testing-checklist.md に引き続きすべて記載されており、規範的な参照先は https://www.w3.org/WAI/WCAG22/quickref/ です。

バックエンドを emulate する

外部 API（GitHub、Vercel、Google）と連携する E2E テストでは、実際の API に接続する代わりに、バックエンドとして emulate を使用してください。これにより、レート制限、ネットワークの問題、非決定的なデータによる不安定さを解消できます。

方法	結果
emulate バックエンド（最優先）	決定論的、高速、CI に適している
実際の API	不安定、レート制限あり、低速
MSW／Nock によるインターセプト	ステートマシンがなく、レスポンス管理が手動

主な機能：再現可能なデータ用のシード設定、Playwright の並列実行に対応したワーカーごとのポート分離、完全なステートマシンの遷移。

パターン、CI 設定、ワーカーごとの分離フィクスチャについては、rules/emulate-e2e.md を参照してください。

---

Playwright クイックスタート

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

test('user can complete checkout', async ({ page }) => {
  await page.goto('/products');
  await page.getByRole('button', { name: 'Add to cart' }).click();
  await page.getByRole('link', { name: 'Checkout' }).click();
  await page.getByLabel('Email').fill('[email protected]');
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});

ロケーターの優先順位： getByRole() > getByLabel() > getByPlaceholder() > getByTestId()

Playwright Core

堅牢なテストのためのセマンティックロケータのパターンとベストプラクティス。

ルール	ファイル	主なパターン
Playwright E2E	rules/e2e-playwright.md	セマンティックロケータ、自動待機、1.58+ の新機能

アンチパターン（禁止）：

• ハードコードされた待機：await page.waitForTimeout(2000)
• 操作に CSS セレクターを使用：await page.click('.submit-btn')
• XPath ロケータ

1.58/1.59 で削除済み — 使用しないでください：

• _react=ComponentName[prop=value] および _vue=... コンポーネントセレクターエンジン — 1.58 で削除
• :light セレクターのサフィックス — 削除済み
• launch({ devtools: true }) オプション — 削除済み；args: ['--auto-open-devtools-for-tabs'] を使用してください

Page Objects

ページ操作を再利用可能なクラスにカプセル化します。

ルール	ファイル	主なパターン
Page Object Model	rules/e2e-page-objects.md	コンストラクター内のロケータ、アクションメソッド、アサーションメソッド

const checkout = new CheckoutPage(page);
await checkout.fillEmail('[email protected]');
await checkout.submit();
await checkout.expectConfirmation();

AI Agents

テストの計画、生成、自己修復を行う Playwright 1.59+ の AI エージェントフレームワークです。コーディングエージェント向けに設計された、トークン効率の高い CLI モードを備えています。出力を最小限に抑え、構造化された応答を返し、コンテキストのオーバーヘッドを削減します。

ルール	ファイル	主なパターン
AI Agents	rules/e2e-ai-agents.md	Planner、Generator、Healer のワークフロー

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

トークン効率の高い CLI モード（1.58+）：Playwright には、コンパクトでエージェントに使いやすい出力を生成する、SKILL に特化した CLI モードが用意されています。AI エージェントから Playwright を実行してトークン消費を抑える場合に使用してください。

ワークフロー：Planner（アプリを調査して仕様を作成）-> Generator（仕様を読み、実行中のアプリをテスト）-> Healer（失敗を修正し、セレクターを更新）。

Playwright 1.59 の新機能（2026 年 4 月）— AI エージェントに関連する機能：

• page.screencast({ start, stop, showActions }) — 動画とリアルタイムの JPEG フレームストリーミングを統合します。動画ファイルを作成せずに、Healer エージェントが実行中のフレームを読み取り、視覚的なアサーションを行えます。
• browser.bind() / npx playwright-cli attach — MCP クライアントから、テストの途中で実行中のブラウザーに接続します。Healer がハングまたは失敗した CI 実行を調査する際に便利です。
• locator.normalize() — 脆弱なロケータをベストプラクティスに沿った同等のロケータに書き換えます。Healer と組み合わせると、可能な場合に getByTestId を getByRole へ自動的にアップグレードできます。

Accessibility (Playwright)

E2E テストで axe-core を使用したページ全体のアクセシビリティ検証を行います。

ルール	ファイル	主なパターン
Playwright + axe	rules/a11y-playwright.md	WCAG 2.2 AA、インタラクティブな状態のテスト

import AxeBuilder from '@axe-core/playwright';

test('page meets WCAG 2.2 AA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

Accessibility (CI/CD)

CI パイプラインとの統合、および jest-axe を使用したコンポーネント単位のテストです。

ルール	ファイル	主なパターン
CI Gates + jest-axe	rules/a11y-testing.md	PR のブロック、コンポーネントの状態テスト

End-to-End Types

API レイヤー全体で型安全性を確保し、実行時の型エラーを排除します。

ルール	ファイル	主なパターン
Type Safety	rules/validation-end-to-end.md	tRPC、Zod、Pydantic、スキーマ拒否テスト

Visual Regression

外部サービスを使わず、Playwright ネイティブのスクリーンショット比較を行います。

await expect(page).toHaveScreenshot('checkout-page.png', {
  maxDiffPixels: 100,
  mask: [page.locator('.dynamic-content')],
});

ベンダーのドキュメントには記載されていない運用ルール（CI 専用のベースライン、単一のスナップショットプロジェクト、しきい値を超える部分のマスク）：references/ork-delta.md。オプションのリファレンスとベースラインのワークフローについては、上記の Upstream coverage テーブルを参照してください。

Key Decisions

決定事項	推奨事項
E2E フレームワーク	セマンティックロケータを使用する Playwright 1.59+
ロケータ戦略	getByRole > getByLabel > getByTestId
ブラウザー	Chromium（1.59+ では Chrome for Testing）
ページのパターン	複雑なページには Page Object Model
ビジュアルリグレッション	Playwright ネイティブの toHaveScreenshot()
アクセシビリティテスト	axe-core（E2E）+ jest-axe（ユニット）
CI の再試行	CI では 2〜3 回、ローカルでは 0 回
不安定なテストの検出	CI で failOnFlakyTests: true
AI エージェント	init-agents による Planner/Generator/Healer
型安全性	エンドツーエンドには tRPC、実行時検証には Zod

参考資料

リソース	説明
references/ork-delta.md	ベンダーのドキュメントに記載されていない独自ルール：vitest-axe ではなく jest-axe を使用、エージェントの初期化は CLI のみ、ベースラインは CI のみ、スナップショットプロジェクトは 1 つ、しきい値ではなくマスクを使用
references/playwright-setup.md	インストール、MCP サーバー、シードテスト、エージェントの初期化

チェックリスト

チェックリスト	説明
checklists/e2e-checklist.md	ロケーター戦略、ページオブジェクト、CI/CD、ビジュアルリグレッション
checklists/e2e-testing-checklist.md	包括的なチェックリスト：計画、実装、SSE、レスポンシブ対応、メンテナンス
checklists/a11y-testing-checklist.md	自動テストと手動テスト：キーボード、スクリーンリーダー、色のコントラスト、WCAG

例

例	説明
examples/orchestkit-e2e-tests.md	OrchestKit の分析フロー：ページオブジェクト、SSE の進捗状況、エラー処理

ユーザーフロー、認証フィクスチャ、API モック、複数タブ、ファイル アップロード、axe スキャンなどの汎用 Playwright サンプルは、現在、Upstream coverage テーブルにあるベンダーページから提供されています。

スクリプト

スクリプト	説明
scripts/create-page-object.md	パターンを自動検出して Playwright のページオブジェクトを生成

関連スキル

• testing-unit - モック、フィクスチャ、データファクトリーを使ったユニットテストのパターン
• testing-integration - API 境界とコントラクトのテスト
• cover - テストスイートがまだ存在しない場合に E2E ティアを生成
• verify - 既存のテストスイートを評価し、マージ判定を返す
• expect - agent-browser による差分を考慮したブラウザー検証
• emulate-seed - emulate プロバイダー向けのシード設定の作成
• portless (上流) - ローカル E2E テスト向けの安定した HTTPS baseURL（ポートを推測する代わりに https://myapp.localhost を使用。portless 0.10 以降は HTTPS の 443 番ポートがデフォルト）