# 機能設計書 54-@jest/test-globals

## 概要

本ドキュメントは、Jestテスティングフレームワークにおける `@jest/test-globals` パッケージの機能設計について記述する。このパッケージは、Jest内部テスト用のグローバル型定義を提供するプライベートパッケージである。

### 本機能の処理概要

`@jest/test-globals` は、Jest自身のテストコードで使用するグローバル変数（describe、it、test、expect、jest等）の型定義を提供する。これはTypeScript環境でJestのグローバルAPIを型安全に使用するための内部ユーティリティである。

**業務上の目的・背景**：Jestは自身のコードベースをJestでテストしている（セルフホスティング）。そのため、Jest内部のテストコードでもTypeScriptの型サポートが必要となる。このパッケージは、`declare global` によりグローバルスコープにJestのテスト関数とモック型を注入し、型安全な内部テスト開発を可能にする。外部向けには `@jest/globals` パッケージが同様の機能を提供する。

**機能の利用シーン**：
- Jest内部パッケージのテストコード作成時
- TypeScriptでのグローバルJest APIの型補完
- jest-mockの型定義（Mock、Mocked、Spied等）の利用

**主要な処理内容**：
1. グローバルスコープへのテスト関数型の宣言（beforeAll、afterAll、describe、it、test等）
2. expectとjestオブジェクトの型宣言
3. jest名前空間へのモック型定義エクスポート（Mock、Mocked、MockedClass、MockedFunction等）

**関連システム・外部連携**：
- `@jest/environment`：Jestオブジェクトの型定義
- `@jest/expect`：JestExpect型の参照
- `@jest/types`：Global.TestFrameworkGlobals型の参照
- `jest-mock`：モック関連型の参照

**権限による制御**：型定義のみのパッケージであり、実行時の権限制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 型定義パッケージのため画面なし |

## 機能種別

型定義提供 / グローバル宣言

## 入力仕様

### 入力パラメータ

本パッケージは型定義のみを提供するため、実行時の入力パラメータは存在しない。

### 入力データソース

- TypeScriptコンパイラによる型情報の読み込み
- tsconfig.jsonのtypes設定による参照

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| beforeAll | Global.TestFrameworkGlobals['beforeAll'] | 全テスト前フック |
| beforeEach | Global.TestFrameworkGlobals['beforeEach'] | 各テスト前フック |
| afterEach | Global.TestFrameworkGlobals['afterEach'] | 各テスト後フック |
| afterAll | Global.TestFrameworkGlobals['afterAll'] | 全テスト後フック |
| describe | Global.TestFrameworkGlobals['describe'] | テストスイート定義 |
| fdescribe | Global.TestFrameworkGlobals['fdescribe'] | 焦点テストスイート |
| xdescribe | Global.TestFrameworkGlobals['xdescribe'] | スキップテストスイート |
| it | Global.TestFrameworkGlobals['it'] | テストケース定義 |
| fit | Global.TestFrameworkGlobals['fit'] | 焦点テストケース |
| xit | Global.TestFrameworkGlobals['xit'] | スキップテストケース |
| test | Global.TestFrameworkGlobals['test'] | テストケース定義（itのエイリアス） |
| xtest | Global.TestFrameworkGlobals['xtest'] | スキップテストケース |
| expect | JestExpect | アサーション関数 |
| jest | Jest | Jestユーティリティオブジェクト |

### jest名前空間の型

| 型名 | 説明 |
|------|------|
| jest.Mock<T> | モック関数の型（jest.fn()の戻り値） |
| jest.Mocked<T> | オブジェクト/関数/クラスのモック型 |
| jest.MockedClass<T> | クラスのモック型 |
| jest.MockedFunction<T> | 関数のモック型 |
| jest.MockedObject<T> | オブジェクトのモック型 |
| jest.Spied<T> | スパイの型 |
| jest.SpiedClass<T> | クラススパイの型 |
| jest.SpiedFunction<T> | 関数スパイの型 |
| jest.SpiedGetter<T> | ゲッタースパイの型 |
| jest.SpiedSetter<T> | セッタースパイの型 |

### 出力先

TypeScriptのグローバルスコープ（declare global）

## 処理フロー

### 処理シーケンス

```
1. TypeScriptプロジェクトが@jest/test-globalsを参照
   └─ tsconfig.jsonのtypesまたはトリプルスラッシュディレクティブ

2. declare globalにより型がグローバルスコープに注入
   └─ beforeAll、describe、it、expect、jest等

3. jest名前空間の型が利用可能に
   └─ jest.Mock、jest.Mocked等

4. テストコードで型補完・型チェックが有効化
```

### フローチャート

```mermaid
flowchart TD
    A[TypeScript コンパイル開始] --> B[types参照解決]
    B --> C[@jest/test-globals読み込み]
    C --> D[declare global処理]
    D --> E[テスト関数型をグローバルに追加]
    E --> F[jest名前空間型を追加]
    F --> G[型チェック・補完有効化]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-54-01 | プライベートパッケージ | package.jsonにprivate: trueが設定されている | 常時 |
| BR-54-02 | 型の再エクスポート | jest-mockの型をjest名前空間で再エクスポート | 常時 |
| BR-54-03 | Global型の参照 | @jest/typesのGlobal.TestFrameworkGlobals型を使用 | 常時 |

### 計算ロジック

本パッケージは型定義のみのため、計算ロジックは存在しない。

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

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

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

該当なし

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| TS2304 | TypeScriptエラー | 型が見つからない | 依存パッケージのインストール確認 |
| TS2339 | TypeScriptエラー | プロパティが存在しない | 型定義の更新確認 |

### リトライ仕様

該当なし（コンパイル時のみ使用）

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

該当なし

## パフォーマンス要件

- 型定義ファイルとして提供され、ランタイムコードは含まない
- TypeScriptコンパイラによる型解決は即座に完了

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

- 型定義のみのパッケージであり、実行時のセキュリティリスクはない
- private: trueによりnpmレジストリには公開されない

## 備考

- Jest内部使用のみ（private: true）
- Node.js ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0 が必要
- バージョン 30.2.0 時点の情報

---

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

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

### 推奨読解順序

#### Step 1: 依存型の理解

まず、インポートされている外部型を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/test-globals/src/index.ts` | インポート文（8-25行目） |

**主要処理フロー**:
- **8行目**: `@jest/environment`からJest型をインポート
- **9行目**: `@jest/expect`からJestExpect型をインポート
- **10行目**: `@jest/types`からGlobal型をインポート
- **11-25行目**: `jest-mock`からモック関連型をインポート

**読解のコツ**: 各インポートはtype importであり、ランタイムコードは含まれない。`as JestXxx` でリネームしているのは、グローバルの `jest` 名前空間と衝突を避けるため。

#### Step 2: グローバル宣言の理解

declare globalによるグローバルスコープへの型注入を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/test-globals/src/index.ts` | declare global（27-92行目） |

**主要処理フロー**:
- **27行目**: declare global開始
- **28-32行目**: beforeAll/beforeEach/afterEach/afterAll フック
- **34-36行目**: describe/fdescribe/xdescribe テストスイート
- **38-43行目**: it/fit/xit/test/xtest テストケース
- **45行目**: expect アサーション関数
- **47行目**: jest ユーティリティオブジェクト

**読解のコツ**: `const` 宣言でグローバル変数の型を定義している。各型は `Global.TestFrameworkGlobals` から取得。

#### Step 3: jest名前空間の理解

jest名前空間へのモック型エクスポートを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/test-globals/src/index.ts` | namespace jest（49-91行目） |

**主要処理フロー**:
- **49行目**: `namespace jest` 開始（eslint-disable-next-lineでlint無効化）
- **50-54行目**: Mock型 - `jest.fn()`の戻り値の型
- **55-58行目**: Mocked型 - オブジェクト全体のモック
- **59-62行目**: MockedClass型 - クラスのモック
- **63-66行目**: MockedFunction型 - 関数のモック
- **67-70行目**: MockedObject型 - オブジェクトのモック
- **71-74行目**: Spied型 - スパイ関数の型
- **75-78行目**: SpiedClass型 - クラススパイの型
- **79-82行目**: SpiedFunction型 - 関数スパイの型
- **83-86行目**: SpiedGetter型 - ゲッタースパイの型
- **87-90行目**: SpiedSetter型 - セッタースパイの型

**読解のコツ**: 各型はJSDocコメント付きでエクスポートされている。`JestMock` → `jest.Mock` のようにリネームして公開。

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

```
@jest/test-globals/src/index.ts
    │
    ├─ @jest/environment
    │      └─ Jest (jestオブジェクトの型)
    │
    ├─ @jest/expect
    │      └─ JestExpect (expect関数の型)
    │
    ├─ @jest/types
    │      └─ Global.TestFrameworkGlobals (テスト関数の型)
    │
    └─ jest-mock
           ├─ Mock
           ├─ Mocked
           ├─ MockedClass
           ├─ MockedFunction
           ├─ MockedObject
           ├─ Spied
           ├─ SpiedClass
           ├─ SpiedFunction
           ├─ SpiedGetter
           └─ SpiedSetter
```

### データフロー図

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

TypeScript ─────────────▶ 型定義読み込み ─────────────────▶ グローバル型
コンパイラ                      │
                              │
                              ├─▶ declare global ───────────▶ beforeAll, describe,
                              │                               it, expect, jest 等
                              │
                              └─▶ namespace jest ───────────▶ jest.Mock,
                                                              jest.Mocked 等
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/test-globals/src/index.ts` | ソース | グローバル型定義 |
| package.json | `packages/test-globals/package.json` | 設定 | パッケージメタデータ（private: true） |

### 依存パッケージの理解

| パッケージ | 役割 | 提供する型 |
|-----------|------|-----------|
| @jest/environment | テスト環境 | Jest（jestオブジェクト） |
| @jest/expect | アサーション | JestExpect（expect関数） |
| @jest/types | 共通型定義 | Global.TestFrameworkGlobals |
| jest-mock | モック機能 | Mock, Mocked, Spied等 |
