E2E テスト概要

20.5.1. フレームワーク選択

E2E テストフレームワークとして Playwright を使用することを推奨します。

項目	Playwright	Cypress
ブラウザサポート	Chromium、Firefox、WebKit	Chromium、Firefox、WebKit（実験的）
実行速度	高速（並列実行をデフォルトサポート）	普通（並列実行には有料プランが必要）
マルチタブ/ウィンドウ	サポート	未サポート
iframe サポート	ネイティブサポート	限定的
API テスト	内蔵サポート	プラグインが必要
デバッグツール	Trace Viewer、Codegen	Cypress Runner
言語サポート	TypeScript、JavaScript、Python、Java、.NET	TypeScript、JavaScript

• Playwright はマルチブラウザテスト、並列実行、API テストをデフォルトでサポートするため、TQS 基準の推奨フレームワークです。
• Cypress を既に使用中のプロジェクトは移行を強制しませんが、新規プロジェクトでは Playwright を採用します。

---

20.5.2. コアシナリオ

E2E テストはユーザーのコア業務フローを検証します。以下のシナリオは必須テスト対象です。

シナリオ	検証項目
ログイン/ログアウト	正常ログイン、不正な資格情報の処理、ログアウト後のリダイレクト
CRUD フロー	項目作成、一覧表示、詳細表示、編集、削除
エラー処理	404 ページ、サーバーエラー時のユーザーフィードバック、ネットワークエラーの復旧
権限制御	未認証ユーザーのアクセス遮断、権限別メニュー/機能の表示
フォーム送信	バリデーション、二重送信防止、成功/失敗フィードバック

// e2e/auth.spec.ts
import { test, expect } from '@playwright/test'

test.describe('認証フロー', () => {
  test('正常ログイン後にダッシュボードへ遷移しなければなりません', async ({ page }) => {
    await page.goto('/login')
    await page.fill('[data-testid="input-email"]', 'user@example.com')
    await page.fill('[data-testid="input-password"]', 'password123')
    await page.click('[data-testid="btn-login"]')

    await expect(page).toHaveURL('/dashboard')
    await expect(page.locator('[data-testid="user-greeting"]')).toBeVisible()
  })

  test('不正なパスワード時にエラーメッセージを表示しなければなりません', async ({ page }) => {
    await page.goto('/login')
    await page.fill('[data-testid="input-email"]', 'user@example.com')
    await page.fill('[data-testid="input-password"]', 'wrong')
    await page.click('[data-testid="btn-login"]')

    await expect(page.locator('[data-testid="error-message"]')).toBeVisible()
  })
})

• すべてのコアシナリオに対して正常パスと例外パスの両方をテストします。
• テストシナリオはユーザーストーリーまたは要件ドキュメントとマッピングして管理します。

---

20.5.3. テスト作成原則

ユーザー視点テスト

E2E テストは内部実装ではなく、ユーザーが見て操作する要素を基準に作成します。

• CSS クラス名やコンポーネント内部状態に依存しません。
• data-testid 属性を使用してテスト対象要素を選択します。
• data-testid 命名規則：{要素タイプ}-{説明}（例：btn-submit、input-email、list-users）

フレーキーテスト防止

不安定な（flaky）テストは信頼性を低下させるため、以下の原則を遵守します。

• 固定待機時間（waitForTimeout）の代わりに条件ベースの待機（waitForSelector、expect().toBeVisible()）を使用します。
• テストデータは各テストで独立して作成し、クリーンアップします。
• 外部 API 依存性は可能な限りモックサーバーで代替します。
• ネットワークリクエストの完了を waitForResponse() で明示的に待機します。

---

20.5.4. CI 連携

CI 環境で E2E テストを自動実行するための設定です。

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

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'on-first-retry',
  },
  webServer: {
    command: 'yarn dev',
    port: 3000,
    reuseExistingServer: !process.env.CI,
  },
})

設定項目	CI 環境値	説明
retries	2	失敗時に最大 2 回リトライ
workers	1	安定性のためにシリアル実行
screenshot	only-on-failure	失敗時にスクリーンショットを自動保存
video	on-first-retry	最初のリトライ時にビデオ録画
trace	on-first-retry	最初のリトライ時に Trace ファイルを保存

• CI 環境では headless モードで実行します（Playwright デフォルト）。
• 失敗時に生成されるスクリーンショット、ビデオ、Trace ファイルは CI アーティファクトとして保管します。
• webServer 設定を通じてテスト前に開発サーバーを自動起動します。
• リトライ回数は CI でのみ有効化し、ローカル開発時には即座に失敗を確認します。