# バッチ設計書 19-test262-finish

## 概要

本ドキュメントは、並列実行されたTest262テスト結果を集計・分析し、前回結果との比較を行うCI/CDバッチ「test262-finish」の設計を定義するものである。

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

test262-finishバッチは、test262ジョブで並列実行された8チャンクのテスト結果をマージし、mainブランチの前回結果と比較して差分を分析するCI/CDジョブである。新たに失敗したテストや修正されたテストを検出し、レグレッションの早期発見を可能にする。

**業務上の目的・背景**：Test262テストは大量のテストケースを含むため、8チャンクに分割して並列実行される。しかし、CI結果を確認する際には統合された結果が必要である。また、PRによるコード変更がパーサーの仕様準拠に影響を与えていないかを確認するため、mainブランチの結果との差分分析が重要である。新たな失敗はレグレッションを示し、新たな成功はバグ修正を示す。

**バッチの実行タイミング**：GitHub Actions上でpushおよびpull_requestイベント発生時に自動実行される。test262ジョブの全チャンクが完了した後に実行される依存関係がある。

**主要な処理内容**：
1. 8チャンクのテスト結果（TAPファイル）をダウンロード
2. 結果をマージして単一のTAPファイルを生成
3. マージ結果をアーティファクトとして保存
4. babel-test262-runnerをチェックアウト
5. mainブランチの前回結果をダウンロード
6. 前回結果と今回結果を比較して差分を分析
7. 差分レポートを出力

**前後の処理との関連**：本バッチはtest262ジョブの8つのTAPファイルを入力として使用する。マージされた結果は次回のmainブランチ結果として保存され、将来のPRとの比較に使用される。

**影響範囲**：本バッチは結果の集計・分析のみを行い、ソースコードやデータの変更は行わない。差分分析で新たな失敗が検出された場合、CIは失敗となりPRのマージがブロックされる。

## バッチ種別

結果集計 / 差分分析

## 実行スケジュール

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

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| test262完了 | 8チャンクすべてのテストが完了していること |
| test262-result-*存在 | 各チャンクのTAPファイルがダウンロード可能であること |
| GITHUB_TOKEN有効 | mainブランチの結果をダウンロードするためのトークン |

### 実行可否判定

test262ジョブが完了した場合に実行される（needs: test262）。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| GITHUB_TOKEN | string | Yes | secrets.GITHUB_TOKEN | GitHub API認証トークン |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| test262-result-0〜7 | GitHub Actions Artifact | 各チャンクのテスト結果（TAPファイル） |
| mainブランチの前回結果 | TAP形式 | 比較用の前回テスト結果 |
| babel/babel-test262-runner | Git Repository | 結果分析ツール |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| test262.tap | TAP形式 | マージされたテスト結果 |
| diff.tap | TAP形式 | 前回結果との差分 |
| test262-result | GitHub Actions Artifact | マージ結果アーティファクト |
| 標準出力 | テキスト | 差分分析ログ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | test262.tap, diff.tap |
| 出力先 | カレントディレクトリ |
| 文字コード | UTF-8 |
| 形式 | TAP（Test Anything Protocol） |

## 処理フロー

### 処理シーケンス

```
1. チャンク結果ダウンロード
   └─ test262-result-0〜7の8つのアーティファクトをダウンロード
2. 結果マージ
   └─ catコマンドで8ファイルを結合、npx tap-mergeでマージ
3. マージ結果アップロード
   └─ test262-resultとしてアーティファクト保存
4. テストランナーチェックアウト
   └─ babel/babel-test262-runnerをチェックアウト
5. テストランナーセットアップ
   └─ npm ciを実行
6. 前回結果ダウンロード
   └─ node lib/download-main-artifact/index.mjsを実行
7. 差分分析
   └─ node lib/compare-resultsを実行
8. 差分レポート出力
   └─ 結果をdiff.tapに保存
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[チャンク結果ダウンロード]
    B --> C[8ファイル結合]
    C --> D[tap-merge でマージ]
    D --> E[test262.tap 保存]
    E --> F[マージ結果アップロード]
    F --> G[テストランナーチェックアウト]
    G --> H[npm ci]
    H --> I[前回結果ダウンロード]
    I --> J[差分分析実行]
    J --> K{新規失敗あり?}
    K -->|なし| L[成功終了]
    K -->|あり| M[失敗終了]
```

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| REGRESSION_DETECTED | レグレッション検出 | 新たな失敗テストが検出された | パーサー実装を修正 |
| DOWNLOAD_FAILURE | ダウンロードエラー | mainブランチ結果の取得失敗 | GITHUB_TOKENを確認 |
| MERGE_FAILURE | マージエラー | TAPファイルのマージ失敗 | ファイル形式を確認 |
| ARTIFACT_NOT_FOUND | 入力エラー | チャンク結果が見つからない | test262ジョブを確認 |

### リトライ仕様

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

### 障害時対応

1. GitHub Actionsのログを確認し、失敗原因を特定する
2. レグレッションの場合、diff.tapで新たに失敗したテストを確認する
3. パーサーの問題であれば修正、意図的な仕様変更であればドキュメント化する
4. 前回結果のダウンロード失敗の場合、GITHUB_TOKENの有効性を確認する

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約50,000テスト結果のマージと比較 |
| 目標処理時間 | 10分以内 |
| メモリ使用量上限 | 4GB（GitHub Actionsランナーのデフォルト） |

## 排他制御

同一ブランチに対する同時実行は、GitHub Actionsのconcurrencyグループ設定により制御される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | ジョブ名 |
| ダウンロードログ | アーティファクトダウンロード時 | チャンク番号 |
| マージログ | マージ完了時 | マージ結果統計 |
| 比較ログ | 差分分析時 | 新規失敗数、新規成功数 |
| 終了ログ | バッチ終了時 | 総合結果 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 15分超過 | GitHub Actions UI |
| レグレッション数 | 1件以上 | GitHub Actions UI、PR Comment |

## 備考

- `npx tap-merge`はTAP形式のファイルをマージするツール
- `shell: bash`によりpipefailが有効になり、パイプ内のエラーも検出される
- mainブランチの前回結果は、babel-test262-runnerのlib/download-main-artifactスクリプトで取得される
- lib/compare-resultsは、2つのTAPファイルを比較して差分を出力する
- 新たな失敗（レグレッション）が検出された場合、CIは失敗となる
- 新たな成功はバグ修正を示し、CIは成功となる
- マージされたtest262.tapは次回のmainブランチ結果として使用される
