# 機能設計書 25-@jest/environment

## 概要

本ドキュメントは、Jestのテスト環境インターフェース定義（@jest/environment）の機能設計を記述する。このパッケージは、テスト実行環境の基本インターフェースと、jestオブジェクトのAPI定義を提供する。

### 本機能の処理概要

@jest/environmentは、Jestテスティングフレームワークにおけるテスト環境の抽象インターフェースを定義するパッケージである。JestEnvironmentクラスとJestインターフェースを定義し、jest-environment-node、jest-environment-jsdom等の具象実装の基盤を提供する。

**業務上の目的・背景**：Jestは様々な実行環境（Node.js、jsdom、カスタム環境）でテストを実行できる必要がある。@jest/environmentは、これらの異なる環境が実装すべき共通のインターフェースを定義することで、環境の交換可能性と拡張性を実現する。また、テストコード内で使用されるjestオブジェクトのAPIを型定義し、モック、タイマー、モジュール操作の統一的なインターフェースを提供する。

**機能の利用シーン**：
- カスタムテスト環境を実装する際
- jestオブジェクトの型定義を参照する際
- テスト環境のライフサイクル（setup/teardown）を管理する際

**主要な処理内容**：
1. JestEnvironment: テスト環境の抽象クラス定義
2. Jest: jestオブジェクトのAPIインターフェース
3. EnvironmentContext: 環境コンテキスト（console, testPath等）
4. ModuleWrapper: モジュールラッパー関数の型定義
5. JestEnvironmentConfig: 環境設定の型定義

**関連システム・外部連携**：
- @jest/fake-timers: フェイクタイマー機能
- jest-mock: モック機能
- @jest/types: 共通型定義
- jest-environment-node / jest-environment-jsdom: 具象実装

**権限による制御**：この機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージはインターフェース定義を提供する内部機能 |

## 機能種別

インターフェース定義 / 型定義

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| config | JestEnvironmentConfig | Yes | 環境設定（projectConfig, globalConfig） | - |
| context | EnvironmentContext | Yes | 環境コンテキスト（console, testPath, docblockPragmas） | - |

### 入力データソース

- jest-runtime からのテスト実行リクエスト
- テストファイルのdocblockプラグマ
- Jest設定ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| global | Global.Global | グローバルオブジェクト |
| fakeTimers | LegacyFakeTimers / null | レガシーフェイクタイマー |
| fakeTimersModern | ModernFakeTimers / null | モダンフェイクタイマー |
| moduleMocker | ModuleMocker / null | モジュールモッカー |

### 出力先

- テスト実行環境
- jestオブジェクト

## 処理フロー

### 処理シーケンス

```
1. テスト環境の初期化
   └─ JestEnvironmentコンストラクタ呼び出し
   └─ config, contextを受け取る

2. setup()呼び出し
   └─ 環境の準備（グローバル設定等）

3. テスト実行
   └─ getVmContext()でVMコンテキスト取得
   └─ globalオブジェクトを使用
   └─ handleTestEvent()でテストイベント処理

4. teardown()呼び出し
   └─ 環境のクリーンアップ
```

### フローチャート

```mermaid
flowchart TD
    A[テスト開始] --> B[JestEnvironment生成]
    B --> C[setup]
    C --> D[getVmContext]
    D --> E[テスト実行]
    E --> F{handleTestEvent?}
    F -->|Yes| G[イベント処理]
    G --> H{次のテスト?}
    F -->|No| H
    H -->|Yes| E
    H -->|No| I[teardown]
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-25-01 | 環境ライフサイクル | setup() → テスト実行 → teardown()の順序で実行 | 常時 |
| BR-25-02 | タイマーモード | useFakeTimers()でフェイクタイマーを有効化、useRealTimers()で無効化 | タイマー関連テスト |
| BR-25-03 | デフォルトタイムアウト | setTimeout()を呼び出さない場合、デフォルトは5秒 | 常時 |
| BR-25-04 | retryTimes | jest-circusランナーでのみ使用可能 | テストリトライ時 |

### 計算ロジック

計算処理は存在しない（インターフェース定義パッケージ）。

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

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

データベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | - | - | インターフェース定義のみのため、エラー処理は具象実装に委譲 |

### リトライ仕様

retryTimes()メソッドでテストのリトライ回数を設定可能（jest-circusのみ）。

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

トランザクション処理は存在しない。

## パフォーマンス要件

特になし。インターフェース定義のみ。

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

特になし。テスト環境のインターフェースを定義するのみ。

## 備考

- 本パッケージは主に型定義を提供し、具象実装はjest-environment-node等で行われる
- Jestインターフェースは非常に多くのメソッドを定義しており、モック・タイマー・モジュール操作を網羅

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-environment/src/index.ts` | 全てのインターフェース・型定義 |

**読解のコツ**:
- EnvironmentContext（13-17行目）はテスト環境の初期化時に渡されるコンテキスト
- JestEnvironmentConfig（35-38行目）はprojectConfigとglobalConfigを含む
- JestEnvironment（40-51行目）はテスト環境の抽象クラス
- Jest（56-449行目）はjestオブジェクトの全APIを定義

#### Step 2: JestEnvironmentクラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-environment/src/index.ts` | JestEnvironmentクラス定義（40-51行目） |

**主要処理フロー**:
- **41行目**: constructor - 環境の初期化
- **42行目**: global - グローバルオブジェクト
- **43-44行目**: fakeTimers/fakeTimersModern - タイマーモック
- **45行目**: moduleMocker - モジュールモッカー
- **46行目**: getVmContext() - VMコンテキスト取得
- **47行目**: setup() - 環境セットアップ
- **48行目**: teardown() - 環境クリーンアップ
- **49行目**: handleTestEvent? - テストイベントハンドラ（オプショナル）
- **50行目**: exportConditions? - エクスポート条件（オプショナル）

#### Step 3: Jestインターフェースを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/jest-environment/src/index.ts` | Jestインターフェース定義（56-449行目） |

**主要API分類**:

**タイマー関連API（56-111, 163-173, 227, 322-359, 378, 412-448行目）**:
- advanceTimersByTime/advanceTimersByTimeAsync
- advanceTimersToNextFrame/advanceTimersToNextTimer
- clearAllTimers/getTimerCount
- runAllTimers/runOnlyPendingTimers
- useFakeTimers/useRealTimers
- setSystemTime/getRealSystemTime

**モック関連API（96-106, 119, 137-147, 155, 188, 203-217, 223, 244, 267-291, 398, 404-410行目）**:
- fn/spyOn/mocked
- mock/unmock/doMock/dontMock
- clearAllMocks/resetAllMocks/restoreAllMocks
- createMockFromModule
- requireActual/requireMock

**モジュール関連API（124-131, 151, 195-201, 282, 368行目）**:
- isolateModules/isolateModulesAsync
- resetModules
- enableAutomock/disableAutomock
- setMock

**その他API（168, 184, 237, 308-315, 386行目）**:
- getSeed - シード値取得
- isEnvironmentTornDown - 環境終了確認
- onGenerateMock - モック生成コールバック
- retryTimes - テストリトライ
- setTimeout - タイムアウト設定

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

```
@jest/runtime
    │
    └─ @jest/environment (インターフェース)
           │
           ├─ JestEnvironment (抽象クラス)
           │      ├─ constructor(config, context)
           │      ├─ setup()
           │      ├─ teardown()
           │      ├─ getVmContext()
           │      └─ handleTestEvent?
           │
           └─ Jest (インターフェース)
                  ├─ タイマーAPI
                  ├─ モックAPI
                  └─ モジュールAPI
```

### データフロー図

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

JestEnvironmentConfig ─────▶ JestEnvironment ─────▶ テスト実行環境
EnvironmentContext                  │
                                    │
                                    ├─▶ global (グローバルオブジェクト)
                                    │
                                    ├─▶ fakeTimers (タイマーモック)
                                    │
                                    └─▶ moduleMocker (モジュールモック)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-environment/src/index.ts` | ソース | インターフェース・型定義 |
| package.json | `packages/jest-environment/package.json` | 設定 | パッケージ定義 |
