# 機能設計書 6-jest-runner

## 概要

本ドキュメントは、Jestテスティングフレームワークのテストファイル実行管理を担当する「jest-runner」の機能設計を記述したものである。

### 本機能の処理概要

jest-runnerパッケージは、個々のテストファイルを実行するためのランナーモジュールである。テストファイルの実行を単一プロセス（インバンド）または複数のワーカープロセス（並列）で行い、テスト結果を収集して報告する機能を提供する。

**業務上の目的・背景**：大規模なテストスイートを効率的に実行するためには、テストファイルの並列実行が不可欠である。jest-runnerは、jest-workerと連携してテストファイルをワーカープロセスに分配し、マルチコアCPUを最大限に活用することで、テスト実行時間を大幅に短縮する。

**機能の利用シーン**：
- 通常のテスト実行（並列モード）
- デバッグ時のシリアル実行（--runInBandモード）
- カスタムランナーの基底クラスとして
- テストファイル単位の実行制御

**主要な処理内容**：
1. TestSchedulerからテストファイルリストを受信
2. シリアルまたは並列モードでテストを実行
3. jest-workerを使用したワーカープロセスの管理
4. テスト環境（jest-environment）のセットアップ
5. テストフレームワーク（jest-circus/jest-jasmine2）の実行
6. テスト結果の収集と親プロセスへの報告

**関連システム・外部連携**：
- jest-worker: ワーカープロセス管理
- jest-runtime: モジュール実行環境
- @jest/environment: テスト環境（jsdom/node）
- jest-circus / jest-jasmine2: テストフレームワーク
- @jest/transform: ソースコード変換

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | N/A | N/A | 本機能はテスト実行エンジンであり、画面は存在しない |

## 機能種別

テスト実行管理 / 並列処理 / ワーカー管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| tests | Array<Test> | Yes | テストファイルリスト | 空でないこと |
| watcher | TestWatcher | Yes | テスト監視オブジェクト | 有効なインスタンス |
| options | TestRunnerOptions | Yes | 実行オプション | serial/maxWorkersを含む |

### 入力データソース

- TestSchedulerからのテストファイルリスト
- 設定ファイルからのテスト環境設定
- CLIオプション（--runInBand等）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| TestResult | Object | 各テストファイルの実行結果 |
| numPassingTests | number | 成功テスト数 |
| numFailingTests | number | 失敗テスト数 |
| testResults | Array | 個別テスト結果 |
| coverage | Object | カバレッジ情報 |

### 出力先

- イベントエミッター経由でTestSchedulerへ
- カバレッジレポーター

## 処理フロー

### 処理シーケンス

```
1. ランナー初期化
   └─ globalConfigとcontextの設定
2. 実行モード判定
   └─ serial/parallelの選択
3. テスト実行
   └─ runTests メソッドの実行
4. 結果収集
   └─ イベントを通じた結果の報告
5. クリーンアップ
   └─ ワーカーの終了処理
```

### フローチャート

```mermaid
flowchart TD
    A[runTests 呼び出し] --> B{シリアルモード?}
    B -->|Yes| C[インバンド実行]
    B -->|No| D[並列実行]
    C --> E[runTest 直接呼び出し]
    D --> F[jest-worker 初期化]
    F --> G[テストをワーカーに分配]
    E --> H{テスト完了?}
    G --> H
    H -->|No| I[次のテスト実行]
    H -->|Yes| J[結果収集]
    I --> H
    J --> K{中断要求?}
    K -->|Yes| L[ワーカー終了]
    K -->|No| M[正常終了]
    L --> N[CancelRun例外]
    M --> O[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | シリアル実行 | --runInBand時は単一プロセスで順次実行 | runInBand=true |
| BR-002 | 並列実行 | maxWorkersに応じたワーカー数で並列実行 | runInBand=false |
| BR-003 | メモリ制限 | workerIdleMemoryLimit到達時にワーカー再起動 | 設定時 |
| BR-004 | 中断処理 | watcher.isInterrupted()でテスト中断 | 中断要求時 |
| BR-005 | リトライ | ワーカークラッシュ時は最大3回リトライ | maxRetries=3 |

### 計算ロジック

ワーカー数の決定:
- `maxWorkers`設定値を使用
- 各ワーカーは独立したNode.jsプロセス

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

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

データベース操作は本パッケージでは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| WORKER_CRASH | ワーカークラッシュ | ワーカープロセスの異常終了 | 自動リトライ（最大3回） |
| CANCEL_RUN | テスト中断 | ユーザーによる中断要求 | 正常な中断処理 |
| FORCE_EXIT | 強制終了 | ワーカーが終了しない | 警告メッセージ出力 |

### リトライ仕様

- ワーカークラッシュ時は最大3回（maxRetries: 3）リトライ
- リトライ後も失敗した場合はエラーとして報告

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

トランザクション処理は本パッケージには存在しない

## パフォーマンス要件

- ワーカー数に応じた線形スケーリング
- メモリ効率のためのワーカー再起動機能
- テストファイルの実行開始時刻を追跡

## セキュリティ考慮事項

- テストコードは信頼されるコードとして実行される
- ワーカープロセスは親プロセスと同じ権限で実行

## 備考

- EmittingTestRunnerはイベントベースのテストランナー基底クラス
- CallbackTestRunnerはコールバックベースの代替実装

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

テストランナーで使用される型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-runner/src/types.ts` | TestRunnerOptions、Test型 |

**読解のコツ**: EmittingTestRunnerとCallbackTestRunnerの2種類のインターフェースが定義されている。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-runner/src/index.ts` | TestRunnerクラスの実装 |

**主要処理フロー**:
1. **50-61行目**: runTestsメソッド（シリアル/並列の振り分け）
2. **63-95行目**: #createInBandTestRun（インバンド実行）
3. **97-198行目**: #createParallelTestRun（並列実行）
4. **200-205行目**: onメソッド（イベントリスナー登録）

#### Step 3: テスト実行の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | runTest.ts | `packages/jest-runner/src/runTest.ts` | 単一テストファイルの実行 |

**主要処理フロー**:
- **79-398行目**: runTestInternal（テスト実行のコア処理）
- **87-108行目**: テスト環境の解決
- **155-173行目**: テスト環境のセットアップ
- **189-205行目**: Runtimeの初期化
- **309-340行目**: テストフレームワークの実行
- **400-428行目**: runTest（公開関数）

#### Step 4: ワーカー処理の理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | testWorker.ts | `packages/jest-runner/src/testWorker.ts` | ワーカープロセスの処理 |

**主要処理フロー**:
- ワーカープロセスでのテスト実行
- 親プロセスへの結果返却

### プログラム呼び出し階層図

```
jest-runner/index.ts (TestRunner)
    │
    ├─ runTests (エントリポイント)
    │      │
    │      ├─ #createInBandTestRun (シリアル)
    │      │      └─ runTest
    │      │             │
    │      │             ├─ ScriptTransformer
    │      │             ├─ TestEnvironment (jsdom/node)
    │      │             ├─ Runtime
    │      │             └─ testFramework (circus/jasmine2)
    │      │
    │      └─ #createParallelTestRun (並列)
    │             │
    │             └─ jest-worker
    │                    └─ testWorker
    │                           └─ runTest
    │
    └─ on (イベントリスナー)
           └─ Emittery イベント発火
```

### データフロー図

```
[入力]                        [処理]                         [出力]

Test[] ──────────────────▶ runTests ────────────────▶ 実行モード判定
    │                           │
    │                           ▼
    │                    ┌──────────────┐
    │                    │ シリアル/並列 │
    │                    └──────┬───────┘
    │                           │
    ▼                           ▼
testPath ───────────────▶ runTest ────────────────▶ TestResult
    │                           │
    ▼                           ▼
設定 ────────────────────▶ TestEnvironment ────────▶ テスト環境
    │                           │
    ▼                           ▼
ソースコード ────────────▶ Runtime ─────────────────▶ モジュール実行
    │                           │
    ▼                           ▼
                         testFramework ────────────▶ テスト実行
                                │
                                ▼
                         イベントエミット ──────────▶ TestScheduler
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-runner/src/index.ts` | ソース | TestRunnerクラス |
| runTest.ts | `packages/jest-runner/src/runTest.ts` | ソース | テストファイル実行 |
| testWorker.ts | `packages/jest-runner/src/testWorker.ts` | ソース | ワーカープロセス処理 |
| types.ts | `packages/jest-runner/src/types.ts` | 型定義 | インターフェース定義 |
| package.json | `packages/jest-runner/package.json` | 設定 | パッケージ定義 |
