# 機能設計書 3-@jest/core

## 概要

本ドキュメントは、Jestテスティングフレームワークのコア実行エンジン「@jest/core」の機能設計を記述したものである。

### 本機能の処理概要

@jest/coreパッケージは、Jestのテスト実行における中核機能を提供するモジュールである。テストファイルの検索、テストの並列実行スケジューリング、ウォッチモードの制御、結果の集約など、テスト実行のオーケストレーションを担当する。

**業務上の目的・背景**：テスト実行の効率化と信頼性の確保が本パッケージの目的である。大規模プロジェクトでは数千のテストファイルが存在することがあり、それらを効率的に発見、スケジューリング、並列実行し、結果を集約する仕組みが不可欠である。また、開発中のウォッチモードで変更されたファイルに関連するテストのみを再実行する機能は、開発効率を大幅に向上させる。

**機能の利用シーン**：
- テストの一括実行（CI/CDパイプライン）
- 変更ファイルに関連するテストの選択的実行
- ウォッチモードでの継続的テスト実行
- カバレッジレポートの生成
- テスト結果のレポーティング

**主要な処理内容**：
1. SearchSourceによるテストファイルの検索とフィルタリング
2. TestSchedulerによるテスト実行のスケジューリングとワーカー管理
3. TestWatcherによるファイル変更監視と再実行制御
4. レポーターを通じたテスト結果の出力
5. カバレッジ情報の収集と集約

**関連システム・外部連携**：
- jest-haste-map: ファイルシステムのインデックス作成
- jest-runner: テストファイルの実行
- jest-worker: 並列実行のためのワーカープロセス管理
- jest-resolve: モジュール解決
- watchman: ファイル変更監視（オプション）

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | N/A | N/A | 本機能はCLIコア機能であり、画面は存在しない |

## 機能種別

テスト実行オーケストレーション / 並列処理管理 / ファイル監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| globalConfig | Config.GlobalConfig | Yes | グローバル設定 | jest-configで検証済み |
| projectConfigs | Array<Config.ProjectConfig> | Yes | プロジェクト別設定 | jest-configで検証済み |
| testPathPatterns | TestPathPatterns | No | テストパスフィルタ | 有効な正規表現 |
| testNamePattern | string | No | テスト名フィルタ | 有効な正規表現 |

### 入力データソース

- jest-configから正規化された設定オブジェクト
- ファイルシステム（テストファイル、ソースファイル）
- jest-haste-mapからのファイルインデックス

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| AggregatedResult | Object | 全テストの集約結果 |
| results | boolean | テスト成否 |
| numTotalTests | number | 総テスト数 |
| numPassedTests | number | 成功テスト数 |
| numFailedTests | number | 失敗テスト数 |
| coverageMap | CoverageMap | カバレッジ情報 |

### 出力先

- レポーターを通じた標準出力
- カバレッジレポート（HTML、JSON等）
- JUnit XMLレポート（設定時）

## 処理フロー

### 処理シーケンス

```
1. 設定の読み込みと初期化
   └─ jest-configから設定を取得
2. HasteMapの構築
   └─ ファイルシステムのインデックス作成
3. テストファイル検索
   └─ SearchSourceでテストパターンにマッチするファイルを取得
4. テストスケジューリング
   └─ TestSchedulerでテスト実行順序を決定
5. 並列テスト実行
   └─ jest-workerでワーカープロセスを管理
6. 結果収集
   └─ 各テストの結果を集約
7. レポート出力
   └─ 設定されたレポーターで結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[runCLI 呼び出し] --> B[設定読み込み]
    B --> C[HasteMap 構築]
    C --> D[SearchSource でテスト検索]
    D --> E{テストが存在?}
    E -->|No| F[終了]
    E -->|Yes| G[TestScheduler でスケジューリング]
    G --> H{ウォッチモード?}
    H -->|Yes| I[TestWatcher 開始]
    H -->|No| J[runJest でテスト実行]
    I --> K[ファイル変更待機]
    K -->|変更検出| L[関連テスト再実行]
    L --> K
    J --> M[結果集約]
    M --> N[レポーター出力]
    N --> O[終了コード設定]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 失敗優先実行 | 前回失敗したテストを優先的に実行 | キャッシュ存在時 |
| BR-002 | 長時間テスト先行 | 実行時間が長いテストを先に開始 | キャッシュ存在時 |
| BR-003 | 変更関連テスト | 変更されたファイルに関連するテストのみ実行 | --onlyChangedモード |
| BR-004 | シャーディング | テストを複数に分割して並列実行 | --shard指定時 |
| BR-005 | ベイルアウト | 指定数の失敗でテスト中断 | --bail指定時 |

### 計算ロジック

並列度の決定:
- `maxWorkers`で指定されたワーカー数まで並列実行
- 各ワーカーは独立したNode.jsプロセス
- メモリ制限（workerIdleMemoryLimit）に達したワーカーは再起動

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

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

データベース操作は本パッケージでは行わない。ただし、キャッシュファイルへの読み書きを行う。

| 操作 | 対象ファイル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| キャッシュ読込 | .jest-cache | READ | 前回実行結果の読み込み |
| キャッシュ保存 | .jest-cache | WRITE | 実行結果のキャッシュ保存 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NO_TESTS | テスト不存在 | マッチするテストがない | testMatch/testRegexを確認 |
| SETUP_ERROR | セットアップエラー | globalSetup失敗 | セットアップスクリプトを確認 |
| TIMEOUT | タイムアウト | テストがタイムアウト | testTimeoutを調整 |

### リトライ仕様

テストレベルでのリトライはjest-circusが担当。@jest/coreレベルでのリトライはない。

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

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

## パフォーマンス要件

- HasteMap構築: 初回は時間がかかるがキャッシュにより2回目以降は高速化
- ウォッチモード: 変更検出から再実行開始まで100ms以内が目標
- 並列実行: maxWorkersに応じた線形スケールアップ

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

- テストコードは信頼されるコードとして実行される
- globalSetup/globalTeardownは任意のコードを実行可能
- カバレッジ情報にはソースコードパスが含まれる

## 備考

- jest-workerはforkまたはworker_threadsを使用可能
- watchmanが利用可能な場合は優先的に使用される

---

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

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

### 推奨読解順序

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

テスト実行で使用される主要な型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.ts | `packages/@jest/types/src/Config.ts` | GlobalConfigとProjectConfigの違い |
| 1-2 | TestResult.ts | `packages/@jest/test-result/src/types.ts` | テスト結果の型定義 |

**読解のコツ**: GlobalConfigは全プロジェクト共通の設定、ProjectConfigはプロジェクト固有の設定を表す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-core/src/index.ts` | 公開APIの一覧 |
| 2-2 | cli/index.ts | `packages/jest-core/src/cli/index.ts` | runCLI関数の実装 |

**主要処理フロー**:
1. **cli/index.ts 30-50行目**: 設定の読み込みと検証
2. **cli/index.ts 52-80行目**: HasteMapの構築
3. **cli/index.ts 82-120行目**: テスト実行のディスパッチ

#### Step 3: テスト検索の理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | SearchSource.ts | `packages/jest-core/src/SearchSource.ts` | テストファイル検索ロジック |

**主要処理フロー**:
- **getTestPaths**: パターンに基づくテストファイル検索
- **findMatchingTests**: glob/regexによるマッチング
- **filterPathsWithStats**: ファイルサイズ情報の付加

#### Step 4: テストスケジューリングの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | TestScheduler.ts | `packages/jest-core/src/TestScheduler.ts` | テスト実行スケジューリング |

**主要処理フロー**:
- **60-80行目**: ランナーの初期化
- **82-120行目**: テストのディスパッチ
- **122-160行目**: 結果の収集と集約

#### Step 5: テスト実行の理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | runJest.ts | `packages/jest-core/src/runJest.ts` | テスト実行のメインロジック |

**主要処理フロー**:
- **50-80行目**: テストファイルの検索
- **82-100行目**: シャーディングの適用
- **102-140行目**: TestSchedulerによる実行
- **142-180行目**: カバレッジの処理

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

```
@jest/core/cli/index.ts (runCLI)
    │
    ├─ jest-config (readConfigs)
    │
    ├─ jest-haste-map (HasteMap.create)
    │
    ├─ SearchSource.getTestPaths
    │      └─ jest-resolve
    │
    ├─ TestScheduler.scheduleTests
    │      │
    │      ├─ jest-runner (テスト実行)
    │      │      └─ jest-worker (並列処理)
    │      │
    │      └─ レポーター
    │
    └─ runJest
           ├─ シャーディング処理
           ├─ カバレッジ収集
           └─ 結果集約
```

### データフロー図

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

jest.config.* ───────▶ readConfigs ───────▶ GlobalConfig
      │                                      ProjectConfigs
      │                     │
      ▼                     ▼
ファイルシステム ───▶ jest-haste-map ───▶ ファイルインデックス
      │                     │
      ▼                     ▼
testPathPattern ───▶ SearchSource ───────▶ テストファイル一覧
      │                     │
      ▼                     ▼
テストファイル ───▶ TestScheduler ───────▶ ワーカーへディスパッチ
      │                     │
      ▼                     ▼
テスト実行 ────────▶ 結果収集 ────────────▶ AggregatedResult
      │                     │
      ▼                     ▼
レポーター ────────▶ 出力 ──────────────────▶ stdout/ファイル
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-core/src/index.ts` | ソース | モジュールエクスポート |
| cli/index.ts | `packages/jest-core/src/cli/index.ts` | ソース | CLIエントリポイント |
| runJest.ts | `packages/jest-core/src/runJest.ts` | ソース | テスト実行メインロジック |
| SearchSource.ts | `packages/jest-core/src/SearchSource.ts` | ソース | テストファイル検索 |
| TestScheduler.ts | `packages/jest-core/src/TestScheduler.ts` | ソース | テストスケジューリング |
| TestWatcher.ts | `packages/jest-core/src/TestWatcher.ts` | ソース | ファイル変更監視 |
| ReporterDispatcher.ts | `packages/jest-core/src/ReporterDispatcher.ts` | ソース | レポーター管理 |
