# 機能設計書 8-jest-jasmine2

## 概要

本ドキュメントは、Jestのレガシーテストランナー「jest-jasmine2」の機能設計を記述したものである。

### 本機能の処理概要

jest-jasmine2パッケージは、Jasmineテストフレームワークをベースとしたテストランナーであり、Jest 26以前のデフォルトランナーであった。現在はjest-circusがデフォルトとなっているが、後方互換性のために引き続きサポートされている。

**業務上の目的・背景**：Jestは当初Jasmineをテストランナーとして採用しており、多くのプロジェクトがjasmine2の動作に依存している。jest-circusへの移行が完了していないプロジェクトや、jasmine2固有の機能を使用しているプロジェクトのために、引き続きサポートが必要である。

**機能の利用シーン**：
- Jest 26以前からのプロジェクト移行
- jasmine2固有のAPIを使用しているプロジェクト
- jest-circusで問題が発生する場合の代替
- `testRunner: 'jasmine2'`設定時

**主要な処理内容**：
1. Jasmineテストフレームワークの初期化
2. describe、it/test、beforeAll/afterAll等のDSL提供
3. テスト環境へのグローバル関数の注入
4. スナップショット機能の統合
5. テスト結果のレポーティング

**関連システム・外部連携**：
- jasmine-core: Jasmineライブラリ（内部に同梱）
- jest-each: パラメータ化テスト
- @jest/expect: アサーションライブラリ
- jest-snapshot: スナップショットテスト
- jest-runtime: モジュール実行環境

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | N/A | N/A | 本機能はテストフレームワークであり、画面は存在しない |

## 機能種別

テストフレームワーク / レガシーランナー / Jasmineラッパー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| globalConfig | Config.GlobalConfig | Yes | グローバル設定 | 検証済み |
| config | Config.ProjectConfig | Yes | プロジェクト設定 | 検証済み |
| environment | JestEnvironment | Yes | テスト環境 | 有効なインスタンス |
| runtime | Runtime | Yes | ランタイム | 有効なインスタンス |
| testPath | string | Yes | テストファイルパス | 存在するファイル |

### 入力データソース

- テストファイル
- jest.config.jsからの設定
- CLIオプション

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| TestResult | Object | テスト実行結果 |
| numPassingTests | number | 成功テスト数 |
| numFailingTests | number | 失敗テスト数 |
| testResults | Array | 個別テスト結果 |
| snapshot | Object | スナップショット情報 |

### 出力先

jest-runner経由でTestSchedulerへ

## 処理フロー

### 処理シーケンス

```
1. Jasmine初期化
   └─ jasmineLight.create()でJasmineインスタンス作成
2. 環境セットアップ
   └─ テスト環境にグローバル関数を注入
3. レポーター設定
   └─ JasmineReporterを追加
4. テストファイル読み込み
   └─ ESM/CommonJSに応じてインポート/リクワイア
5. テスト実行
   └─ env.execute()でテスト実行
6. 結果収集
   └─ レポーターから結果を取得
7. スナップショット処理
   └─ スナップショット情報を結果に追加
```

### フローチャート

```mermaid
flowchart TD
    A[jasmine2 呼び出し] --> B[Jasmine インスタンス作成]
    B --> C[テスト環境にグローバル注入]
    C --> D[JasmineReporter 追加]
    D --> E{fakeTimers 有効?}
    E -->|Yes| F[fakeTimers 設定]
    E -->|No| G[beforeEach フック設定]
    F --> G
    G --> H[jestExpect 設定]
    H --> I{ESM?}
    I -->|Yes| J[unstable_importModule]
    I -->|No| K[requireModule]
    J --> L[env.execute]
    K --> L
    L --> M[結果取得]
    M --> N[スナップショット処理]
    N --> O[TestResult 返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 環境変数判定 | JEST_JASMINE=1でjasmine2を使用 | 環境変数設定時 |
| BR-002 | testRunner設定 | testRunner: 'jasmine2'で使用 | 設定時 |
| BR-003 | failing非サポート | test.failingはエラーを投げる | failing使用時 |
| BR-004 | concurrent非サポート | test.concurrentは未サポート | concurrent使用時 |
| BR-005 | テスト名フィルタ | testNamePatternでテストをフィルタ | パターン指定時 |

### 計算ロジック

特になし

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| FAILING_NOT_SUPPORTED | 非サポート | test.failing使用 | jest-circusに移行 |
| TEST_TIMEOUT | タイムアウト | テストタイムアウト | タイムアウト値を調整 |

### リトライ仕様

jest-jasmine2自体にリトライ機能はない

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

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

## パフォーマンス要件

- jest-circusと同等のテスト実行性能
- スナップショットテストの効率的な処理

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

- テストコードは信頼されるコードとして実行される
- グローバル変数へのアクセスが可能

## 備考

- Jest 27以降ではjest-circusがデフォルト
- 新規プロジェクトではjest-circusの使用を推奨
- jest-jasmine2は将来的に非推奨となる可能性あり

---

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

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

### 推奨読解順序

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

Jasmine固有の型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-jasmine2/src/types.ts` | Jasmine型定義 |

**読解のコツ**: JasmineインターフェースはJasmineライブラリの型を定義している。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-jasmine2/src/index.ts` | jasmine2関数（メインエントリ） |

**主要処理フロー**:
1. **28-44行目**: Jasmineインスタンスの作成と設定
2. **46-78行目**: テスト環境へのグローバル関数注入
3. **80-101行目**: test.failingのエラー処理
4. **110-116行目**: fakeTimers設定
5. **118-141行目**: beforeEachフックの設定
6. **166-175行目**: スナップショット状態の初期化
7. **177-200行目**: テストファイルの読み込みと実行
8. **209-236行目**: addSnapshotData（スナップショット結果の追加）

#### Step 3: Jasmine軽量版の理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | jasmineLight.ts | `packages/jest-jasmine2/src/jasmine/jasmineLight.ts` | Jasmine軽量実装 |

**主要処理フロー**:
- Jasmineのコア機能のみを抽出した軽量実装
- Jest用にカスタマイズされたJasmine

#### Step 4: レポーターの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | reporter.ts | `packages/jest-jasmine2/src/reporter.ts` | JasmineReporter |

**主要処理フロー**:
- Jasmine形式の結果をJest形式に変換
- テスト開始/終了イベントの処理

#### Step 5: 非同期処理の理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | jasmineAsyncInstall.ts | `packages/jest-jasmine2/src/jasmineAsyncInstall.ts` | async/await対応 |

**主要処理フロー**:
- Jasmineのdone()コールバックパターンをPromiseに変換
- async/awaitテストのサポート

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

```
jest-jasmine2/src/index.ts (jasmine2)
    │
    ├─ jasmineLight.create()
    │      └─ Jasmine インスタンス
    │
    ├─ jasmineAsyncInstall()
    │      └─ async/await サポート
    │
    ├─ installEach()
    │      └─ jest-each パラメータ化
    │
    ├─ jestExpect.default()
    │      └─ @jest/expect 設定
    │
    ├─ setup_jest_globals
    │      └─ スナップショット状態
    │
    ├─ runtime.requireModule / unstable_importModule
    │      └─ テストファイル読み込み
    │
    └─ env.execute()
           │
           └─ JasmineReporter
                  └─ 結果収集
```

### データフロー図

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

globalConfig ────────────▶ jasmine2() ─────────────▶ Jasmine初期化
config       ────────────▶
environment  ────────────▶ グローバル注入 ─────────▶ it/describe等
runtime      ────────────▶
testPath     ────────────▶ テストファイル読み込み ──▶ テスト定義
                                │
                                ▼
                          env.execute() ───────────▶ テスト実行
                                │
                                ▼
                          JasmineReporter ─────────▶ 結果収集
                                │
                                ▼
                          addSnapshotData ─────────▶ TestResult
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-jasmine2/src/index.ts` | ソース | メインエントリ |
| jasmineLight.ts | `packages/jest-jasmine2/src/jasmine/jasmineLight.ts` | ソース | Jasmine軽量版 |
| reporter.ts | `packages/jest-jasmine2/src/reporter.ts` | ソース | 結果レポーター |
| jasmineAsyncInstall.ts | `packages/jest-jasmine2/src/jasmineAsyncInstall.ts` | ソース | async対応 |
| each.ts | `packages/jest-jasmine2/src/each.ts` | ソース | jest-each統合 |
| jestExpect.ts | `packages/jest-jasmine2/src/jestExpect.ts` | ソース | expect設定 |
| setup_jest_globals.ts | `packages/jest-jasmine2/src/setup_jest_globals.ts` | ソース | グローバル設定 |
| types.ts | `packages/jest-jasmine2/src/types.ts` | 型定義 | 型定義 |
