# バッチ設計書 14-Integration Tests

## 概要

本ドキュメントは、Tailwind CSSプロジェクトにおけるGitHub Actions「Integration Tests」ワークフローのバッチ設計書である。push/PR時にupgrade・vite・cli・postcss・oxide・webpackの統合テストをマルチプラットフォームで実行する。

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

本バッチは、Tailwind CSSの統合テストを自動実行するCI/CDワークフローである。mainブランチへのpushおよびプルリクエスト作成時に、6種類の統合テストスイート（upgrade、vite、cli、postcss、oxide、webpack）を最大3つのプラットフォーム（Windows、Linux、macOS）で並列実行する。

**業務上の目的・背景**：Tailwind CSSは多様なビルドツールやフレームワークとの統合が求められる。Vite、PostCSS、Webpack、CLIなど異なるエコシステムとの互換性を保証するため、各統合ポイントにおけるテストを自動化している。また、v3からv4へのマイグレーションツール（upgrade）の正確性も統合テストで検証される。マルチプラットフォーム対応により、OS固有の問題も早期に検出できる。

**バッチの実行タイミング**：mainブランチへのpush時およびプルリクエスト作成・更新時に自動実行される。concurrency設定により、同一ワークフロー・同一refでの同時実行は最新のものが優先される。

**主要な処理内容**：
1. リポジトリチェックアウトおよびビルド環境構築
2. Tailwind CSS全体のビルド（Oxideネイティブバイナリ含む）
3. 6種類の統合テストスイートの並列実行
   - upgrade: v3からv4へのマイグレーションテスト
   - vite: Viteとの統合テスト
   - cli: CLIコマンドのテスト
   - postcss: PostCSS連携テスト
   - oxide: Oxideエンジンのテスト
   - webpack: Webpack連携テスト
4. mainブランチ失敗時のDiscord通知

**前後の処理との関連**：本ワークフローはCIワークフロー（No.10）と並行して実行される。CIワークフローが単体テスト・Lint等を担当するのに対し、本ワークフローは外部ツールとの統合テストに特化している。テスト実行にはpnpm run test:integrations（package.jsonで定義、内部的にvitestを使用）が使用される。

**影響範囲**：テストの実行結果はプルリクエストのステータスチェックに反映される。mainブランチでのテスト失敗時はDiscord通知が送信される。本ワークフロー自体はコードやパッケージに変更を加えない。

## バッチ種別

CI/CDワークフロー（統合テスト自動化）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（push/PR時） |
| 実行時刻 | 不定（push/PRタイミングに依存） |
| 実行曜日 | 不定 |
| 実行日 | 不定 |
| トリガー | mainブランチへのpush / プルリクエスト |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| mainブランチへのpushまたはPR | on: push: branches: [main] / on: pull_request |
| DISCORD_WEBHOOK_URLシークレット設定済み | mainブランチ失敗時のDiscord通知に必要 |
| Rustツールチェーンが利用可能 | 各ビルド環境でRustが利用可能であること |
| Node.js v24が利用可能 | 各ビルド環境でNode.js v24が利用可能であること |

### 実行可否判定

pushまたはpull_requestイベントにより自動判定。concurrency設定により同一ref内では最新の実行のみが有効。

プラットフォーム制限：
- mainブランチへのpush時: Windows、Linux、macOS全プラットフォームで実行
- PRで`[ci-all]`がbodyに含まれる場合: 全プラットフォームで実行
- 上記以外のPR時: Linuxのみで実行（WindowsとmacOSは除外）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| NODE_VERSION | number | Yes | 24 | Node.jsバージョン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| GitHubリポジトリソースコード | Git | actions/checkout@v6で取得 |
| integrations/ | TypeScript | 統合テストスイートのソースコード |
| Cargo.lock | TOML | Rustの依存関係定義 |
| crates/node/ | Rust/NAPI-RS | Oxideネイティブバイナリのソースコード |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| GitHub Checksステータス | ステータス | 各テストジョブの成功/失敗ステータス |
| Discord通知 | メッセージ | mainブランチ失敗時の通知メッセージ |

### 出力ファイル仕様

本バッチはファイル出力を行わない。テスト結果はGitHub Actionsのジョブログおよびステータスチェックとして出力される。

| 項目 | 内容 |
|-----|------|
| ファイル名 | N/A |
| 出力先 | GitHub Actions ログ |
| 文字コード | N/A |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. testsジョブ（最大18並列: 6テストスイート x 3プラットフォーム）
   ├─ リポジトリチェックアウト
   ├─ pnpmセットアップ
   ├─ Gitユーザー設定（github-actions[bot]）
   ├─ Node.js v24セットアップ
   ├─ Cargoキャッシュ復元
   ├─ Oxideビルドキャッシュ復元
   ├─ WASMターゲット追加（wasm32-wasip1-threads）
   ├─ 依存関係インストール（pnpm install）
   ├─ Tailwind CSSビルド（pnpm run build）
   │   ├─ CARGO_PROFILE_RELEASE_LTO=off
   │   └─ CARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER=lld-link
   └─ 統合テスト実行（pnpm run test:integrations ./integrations/{integration}）
2. notifyジョブ（testsジョブ失敗 かつ mainブランチの場合のみ）
   └─ Discord通知送信
```

### フローチャート

```mermaid
flowchart TD
    A[push/PRイベント] --> B{mainブランチ or ci-all?}
    B -->|Yes| C[全プラットフォームで実行]
    B -->|No| D[Linuxのみで実行]
    C --> E[testsジョブ: 6テスト x 3プラットフォーム並列]
    D --> F[testsジョブ: 6テスト x 1プラットフォーム並列]
    E --> G{全テスト成功?}
    F --> G
    G -->|Yes| H[ワークフロー完了]
    G -->|No| I{mainブランチ?}
    I -->|Yes| J[Discord通知送信]
    I -->|No| K[ワークフロー失敗のみ]
    J --> L[ワークフロー完了]
    K --> L
```

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

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

本バッチはデータベースを使用しない。

| 処理 | 対象 | 操作種別 | 概要 |
|-----|------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

### テーブル別操作詳細

N/A（データベース操作なし）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| BUILD_FAIL | ビルドエラー | Tailwind CSSビルド失敗（Rust/TypeScript） | ビルドログを確認し、ソースコードを修正 |
| TEST_FAIL | テスト失敗 | 統合テストのアサーション失敗 | テストログを確認し、テストまたはソースコードを修正 |
| ENV_FAIL | 環境エラー | Rustツールチェーン/Node.jsのセットアップ失敗 | GitHub Actionsランナーの状態を確認 |
| TIMEOUT | タイムアウト | 30分以内にテストが完了しない | テストの実行時間を確認し最適化 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 自動リトライなし |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（PRの再pushまたはワークフロー手動再実行） |

### 障害時対応

1. テスト失敗時：GitHub Actionsのジョブログからどのテストスイート・プラットフォームで失敗したかを特定し、該当する統合テストコードまたはソースコードを修正する。
2. mainブランチでの失敗時：Discord通知が送信されるため、チームメンバーが速やかに対応する。
3. 環境依存の失敗（特定プラットフォームのみ失敗）：OS固有の問題（パス区切り、改行コード等）を調査する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（テスト実行のためデータ変更なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 最大18ジョブ（6テストスイート x 3プラットフォーム） |
| 目標処理時間 | 各テストジョブ: 30分以内 |
| メモリ使用量上限 | GitHub Actionsランナーのデフォルト |

## 排他制御

concurrency設定による排他制御が実装されている。

- group: `${{ github.workflow }}-${{ github.ref }}`（ワークフロー名+refの組み合わせ）
- cancel-in-progress: true（同一グループの実行中ワークフローをキャンセル）

また、strategy.fail-fast: falseにより、一つのテストジョブが失敗しても他のジョブは継続実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各テストジョブ開始時 | GitHub Actions標準のジョブ開始ログ、プラットフォーム/テストスイート名 |
| ビルドログ | ビルド中 | Rustコンパイル進捗、pnpmインストール進捗 |
| テストログ | テスト実行中 | vitestによるテスト実行結果（パス/フェイル） |
| 終了ログ | 各テストジョブ終了時 | 成功/失敗ステータス |
| 通知ログ | mainブランチ失敗時 | Discord通知メッセージ（ワークフローURLを含む） |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テストジョブ実行時間 | 30分 | GitHub Actions（timeout-minutesで自動停止） |
| mainブランチテスト失敗 | 1回 | Discord（DISCORD_WEBHOOK_URL） |

## 備考

- テストスイート一覧: upgrade、vite、cli、postcss、oxide、webpack
- プラットフォーム一覧: Windows（windows-latest）、Linux（namespace-profile-default）、macOS（macos-14）
- フィーチャーブランチ（main以外）のPRでは、WindowsとmacOSのテストがスキップされLinuxのみで実行される。PRのbodyに`[ci-all]`を含めることで全プラットフォームでの実行を強制できる
- Gitユーザー設定（github-actions[bot]）は、upgradeテストなど内部的にgitコミットを行うテストのために必要
- Tailwind CSSビルド時にCARGO_PROFILE_RELEASE_LTO=offが設定され、LTO（Link Time Optimization）が無効化される。これはテスト用ビルドの高速化のためである
- Windows環境ではCARGO_TARGET_X86_64_PC_WINDOWS_MSVC_LINKER=lld-linkが設定され、LLDリンカが使用される
- テスト実行時にGITHUB_WORKSPACE環境変数が渡される
- Discord通知はdiscord-actions/message@v2を使用し、失敗したワークフロー実行のURLを含むメッセージが送信される
