# バッチ設計書 8-E2E Tests

## 概要

本ドキュメントは、E2E Testsバッチ（e2e_tests.yml）の設計仕様を記載したものである。このバッチは、Vercelデプロイ完了後にPlaywrightを使用してエンドツーエンド（E2E）テストを実行するCI/CDバッチである。

### 本バッチの処理概要

**業務上の目的・背景**：Webアプリケーションの品質を担保するため、実際のブラウザ環境でのユーザー操作を模擬したE2Eテストが必要である。本バッチは、Vercelへのデプロイが成功した際に自動的にトリガーされ、Chromiumおよび Mobile Safari の2つのブラウザ環境でPlaywrightテストを実行する。本番環境およびプレビュー環境の両方でテストを行い、アプリケーションの動作を検証する。

**バッチの実行タイミング**：Vercelのデプロイステータスが「success」になった際に自動実行される（deployment_statusイベント）。

**主要な処理内容**：
1. デプロイ条件の確認（liam-app のProduction/Preview環境のみ対象）
2. Playwrightブラウザのインストール（キャッシュ利用）
3. E2Eテストの実行（Chromium/Mobile Safari並列）
4. テスト結果のGitHubステータス投稿
5. 本番環境で失敗時のSlack通知

**前後の処理との関連**：Vercelのデプロイ完了をトリガーとして実行される。テスト結果はGitHubコミットステータスとして反映される。

**影響範囲**：GitHubコミットステータス、Slackチャンネル（失敗時）

## バッチ種別

CI/CD / E2Eテスト

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動 |
| 実行時刻 | - |
| 実行曜日 | - |
| 実行日 | - |
| トリガー | deployment_status（Vercelデプロイ成功時） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Vercelデプロイ | liam-appプロジェクトのデプロイが成功していること |
| VERCEL_PROTECTION_BYPASS_SECRET | Vercel保護バイパスシークレットがSecretsに設定されていること |
| SLACK_CLI_CI_WEBHOOK_URL | Slack Webhook URLがSecretsに設定されていること |
| Playwright | テストランナーとして使用 |

### 実行可否判定

- `deployment_status`イベントで`state == 'success'`の場合のみ処理続行
- 対象環境：
  - Production: `environment.include?("Production")` かつ `target_url.include?("liam-app-git-main")`
  - Preview: `environment.include?("Preview")` かつ `environment.include?("liam-app")`
- 上記以外の環境（liam-erd-sample, liam-docs等）はスキップ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| URL | string | Yes | deployment_status.target_url | テスト対象URL |
| ENVIRONMENT | string | Yes | deployment.environment | デプロイ環境名 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| Vercel deployment_status | Webhook | デプロイ完了イベント |
| Playwright テストファイル | TypeScript | E2Eテストケース |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Commit Status | API | E2Eテスト結果ステータス |
| GitHub Actions Artifact | ZIP | 失敗時のテスト結果（30日間保持） |
| Slack通知 | JSON | 本番環境失敗時の通知 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | test-results-{browser}-{run_id}-{job} |
| 出力先 | frontend/internal-packages/e2e/test-results/ |
| 保持期間 | 30日間 |

## 処理フロー

### 処理シーケンス

```
1. コードチェックアウト
   └─ actions/checkout@v4.3.0
   └─ ref: deployment.sha
2. デプロイ条件確認
   └─ Ruby スクリプトで判定
   └─ should_run出力を設定
3. pnpm環境セットアップ（条件付き）
   └─ should_run == 'true'の場合のみ
4. Playwrightブラウザキャッシュ確認
   └─ actions/cache@v4.3.0
   └─ ~/.cache/ms-playwright
5. Playwrightブラウザインストール（キャッシュミス時）
   └─ pnpm exec playwright install --with-deps
6. WebKit依存関係インストール（キャッシュヒット時）
   └─ pnpm exec playwright install-deps webkit
7. E2Eテスト実行
   └─ pnpm exec playwright test --project="${browser}"
   └─ Chromium / Mobile Safari の並列実行
8. テスト結果アップロード（失敗時）
   └─ actions/upload-artifact@v4.6.2
9. GitHubステータス投稿
   └─ gh api repos/.../statuses/...
10. Slack通知（本番環境失敗時）
    └─ tokorom/action-slack-incoming-webhook@v1.3.0
```

### フローチャート

```mermaid
flowchart TD
    A[deployment_status イベント] --> B{state == success?}
    B -->|いいえ| C[スキップ]
    B -->|はい| D{liam-app環境?}
    D -->|いいえ| C
    D -->|はい| E[should_run=true]
    E --> F[pnpm環境セットアップ]
    F --> G{Playwrightキャッシュ?}
    G -->|あり| H[WebKit依存関係のみ]
    G -->|なし| I[全ブラウザインストール]
    H --> J[E2Eテスト実行]
    I --> J
    J --> K{テスト成功?}
    K -->|はい| L[GitHubステータス: success]
    K -->|いいえ| M[テスト結果アップロード]
    M --> N[GitHubステータス: failure]
    N --> O{本番環境?}
    O -->|はい| P[Slack通知]
    O -->|いいえ| Q[終了]
    L --> Q
    P --> Q
    C --> Q
```

## データベース操作仕様

### 操作別データベース影響一覧

データベース操作なし（E2Eテストは外部URLに対して実行）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | テスト失敗 | E2Eテストケース失敗 | テスト結果を確認し、コードまたはテストを修正 |
| - | Playwright起動失敗 | ブラウザインストールエラー | キャッシュクリア後に再実行 |
| - | タイムアウト | テスト実行が10分超過 | テストの最適化またはタイムアウト延長 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

- テスト失敗時：アップロードされたtest-results アーティファクトを確認
- 本番環境失敗時：Slack通知を確認し、緊急対応

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 1回/デプロイ |
| 目標処理時間 | 10分以内（timeout-minutes: 10） |
| メモリ使用量上限 | GitHub Actions標準ランナー制限内 |

## 排他制御

- 排他制御なし
- fail-fast: false（1つのブラウザで失敗しても他は継続）
- マトリックス実行（Chromium, Mobile Safari並列）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各ステップ開始時 | ステップ名 |
| 進捗ログ | 処理中 | Playwright実行ログ |
| 終了ログ | バッチ終了時 | テスト結果サマリー |
| エラーログ | エラー発生時 | エラー詳細、スクリーンショット |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テスト失敗（本番環境） | failure | Slack (#cli-ci チャンネル) |
| 処理時間 | 10分 | GitHub Actionsタイムアウト |

## 備考

- WARNING: `environment`を設定しないこと（Vercel deployment_status webhookとの無限ループを避けるため）
- テスト対象ブラウザ：chromium, "Mobile Safari"
- Playwrightキャッシュキー：`playwright-{os}-{hash(pnpm-lock.yaml, playwright.config.ts)}`
- WebKit依存関係は一部キャッシュ外のため、キャッシュヒット時も別途インストール
- VERCEL_PROTECTION_BYPASS_SECRETはVercel保護機能をバイパスするために使用
- GitHubステータスのcontext: `E2E Tests / e2e-tests ({browser})`
- テスト結果の保持期間：30日間
