# バッチ設計書 13-test-babel9-windows-mac

## 概要

本ドキュメントは、Babel 9環境でのWindowsおよびmacOSにおけるクロスプラットフォームテストを実行するCI/CDバッチ「test-babel9-windows-mac」の設計を定義するものである。

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

test-babel9-windows-macバッチは、Babel 9の破壊的変更を含むコードベースに対して、WindowsとmacOSの両プラットフォームでJestテストを実行し、クロスプラットフォーム互換性を検証するCI/CDジョブである。

**業務上の目的・背景**：Babelはクロスプラットフォームで動作するツールであり、Linux環境でのテストだけでは検出できないプラットフォーム固有の問題（パス区切り文字、改行コード、ファイルシステムの違いなど）を検出する必要がある。特にBabel 9では破壊的変更が含まれるため、新しいコードパスがWindowsやmacOSでも正しく動作することを確認することが重要である。

**バッチの実行タイミング**：GitHub Actions上でpushおよびpull_requestイベント発生時に自動実行される。build-babel9ジョブの完了後に実行される依存関係がある。マトリクスビルドにより、WindowsとmacOSで並列実行される。

**主要な処理内容**：
1. リポジトリのチェックアウト
2. Node.js最新版のセットアップとYarnキャッシュの利用
3. 依存関係のインストール
4. Babel 9ビルドアーティファクトのダウンロード
5. Jestテストの実行（各プラットフォームで）

**前後の処理との関連**：本バッチはbuild-babel9ジョブの成果物（babel9-artifact）を入力として使用する。他のジョブへの出力はなく、テスト結果の合否のみを報告する。

**影響範囲**：本バッチはテスト実行のみを行い、ソースコードやデータの変更は行わない。テスト失敗時はCI全体が失敗となり、PRのマージがブロックされる。

## バッチ種別

テスト実行 / クロスプラットフォーム検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（随時） |
| 実行時刻 | N/A |
| 実行曜日 | N/A |
| 実行日 | N/A |
| トリガー | GitHub Actions（push/pull_request） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| build-babel9完了 | Babel 9のビルドアーティファクトが生成済みであること |
| babel9-artifact存在 | ビルド成果物がダウンロード可能であること |

### 実行可否判定

build-babel9ジョブが成功した場合のみ実行される（needs: build-babel9）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| BABEL_ENV | string | No | test | Babel環境設定 |
| BABEL_9_BREAKING | boolean | No | true | Babel 9破壊的変更フラグ |
| matrix.os | string | Yes | N/A | 実行OS（windows-latest/macos-latest） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| babel9-artifact | GitHub Actions Artifact | Babel 9ビルド成果物 |
| テストファイル | TypeScript/JavaScript | Jestテストファイル |
| jest.config.js | JavaScript | Jest設定ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト結果サマリー |
| GitHub Actions Log | ログ | ジョブ実行ログ |

### 出力ファイル仕様

本バッチはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. リポジトリチェックアウト
   └─ actions/checkout@v4を使用
2. Node.js環境セットアップ
   └─ Node.js 25.6.1をセットアップ、Yarnキャッシュを有効化
3. 依存関係インストール
   └─ yarn installを実行
4. ビルドアーティファクトダウンロード
   └─ babel9-artifactをダウンロードして展開
5. テスト実行
   └─ yarn jest --ciを実行
6. 結果報告
   └─ 成功/失敗ステータスをGitHub Actionsに報告
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[マトリクス分岐]
    B --> C1[Windows環境]
    B --> C2[macOS環境]

    C1 --> D1[チェックアウト]
    D1 --> E1[Node.js セットアップ]
    E1 --> F1[yarn install]
    F1 --> G1[artifact ダウンロード]
    G1 --> H1[yarn jest --ci]
    H1 --> I1{テスト成功?}
    I1 -->|成功| J1[成功終了]
    I1 -->|失敗| K1[失敗終了]

    C2 --> D2[チェックアウト]
    D2 --> E2[Node.js セットアップ]
    E2 --> F2[yarn install]
    F2 --> G2[artifact ダウンロード]
    G2 --> H2[yarn jest --ci]
    H2 --> I2{テスト成功?}
    I2 -->|成功| J2[成功終了]
    I2 -->|失敗| K2[失敗終了]
```

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

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

本バッチはデータベース操作を行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TEST_FAILURE | テスト失敗 | Jestテストケースの失敗 | テストコードまたは実装を修正 |
| PLATFORM_ERROR | プラットフォームエラー | OS固有の問題 | パス処理やファイル操作を見直す |
| ARTIFACT_NOT_FOUND | 入力エラー | babel9-artifactが見つからない | build-babel9ジョブを確認 |
| YARN_INSTALL_FAILURE | インストールエラー | 依存関係インストール失敗 | ロックファイルを確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（自動リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

1. GitHub Actionsのログを確認し、失敗したテストケースと対象OSを特定する
2. 該当OSでローカルまたはリモート環境を用意して再現確認する
3. プラットフォーム固有の問題（パス区切り、改行コード等）を調査する
4. 必要に応じて`path`モジュールや`os.EOL`を使用した修正を行う

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データ操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約5000テストケース/OS |
| 目標処理時間 | 30分以内/OS |
| メモリ使用量上限 | 7GB（GitHub Actionsランナーのデフォルト） |

## 排他制御

同一ブランチに対する同時実行は、GitHub Actionsのconcurrencyグループ設定により制御される。新しい実行が開始されると、進行中の古い実行はキャンセルされる。マトリクスビルド内の各OS間では並列実行される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | ジョブ名、対象OS、Node.jsバージョン |
| 進捗ログ | テスト実行中 | テストスイート進捗 |
| 終了ログ | バッチ終了時 | テスト結果サマリー |
| エラーログ | エラー発生時 | 失敗テスト名、アサーションエラー詳細、スタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 45分超過 | GitHub Actions UI |
| テスト失敗率 | 1件以上 | GitHub Actions UI |

## 備考

- マトリクスビルドでは`fail-fast: false`が設定されており、一方のOSで失敗しても他方のテストは継続される
- WindowsとmacOSでは異なるランナー環境が使用される（windows-latest, macos-latest）
- `yarn jest --ci`の`--ci`フラグは、CI環境に最適化された設定（スナップショット更新無効化、ウォッチモード無効化）を有効にする
- Windows環境ではパス区切り文字（バックスラッシュ）の扱いに注意が必要
