# 機能設計書 29-@jest/globals

## 概要

本ドキュメントは、Jestのグローバル変数エクスポートパッケージ（@jest/globals）の機能設計を記述する。このパッケージは、テストコード内でJestのグローバル関数と型をESModuleとしてインポートするためのエントリーポイントを提供する。

### 本機能の処理概要

@jest/globalsは、Jestテスト環境で使用するグローバル変数（expect、test、describe、jest等）をESModule形式でエクスポートするパッケージである。TypeScriptプロジェクトで明示的なインポートによる型安全なテストコード作成を可能にする。

**業務上の目的・背景**：従来のJestではグローバル変数が暗黙的に利用可能だったが、ESModulesやTypeScriptの普及により、明示的なインポートが求められるケースが増加している。@jest/globalsは、これらのグローバル変数を明示的にインポート可能な形で提供し、型安全性と IDE のサポートを向上させる。

**機能の利用シーン**：
- ESModulesでテストを記述する場合
- TypeScriptで型安全なテストを記述する場合
- 明示的なインポートによるコードの可読性向上
- IDE での自動補完とエラー検出

**主要な処理内容**：
1. expect関数のエクスポート（JestExpect型）
2. テスト関数のエクスポート（it, test, fit, xit, xtest）
3. describe関数のエクスポート（describe, xdescribe, fdescribe）
4. フック関数のエクスポート（beforeAll, beforeEach, afterEach, afterAll）
5. jestオブジェクトのエクスポート（モック関連の型を含む）

**関連システム・外部連携**：
- @jest/environment: Jest型定義
- @jest/expect: expect関数
- @jest/types: Global型定義
- jest-mock: モック型定義

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージはプログラミングAPIを提供 |

## 機能種別

テストグローバル変数 / 型定義エクスポート

## 入力仕様

### 入力パラメータ

本パッケージは変数・型のエクスポートのみを行うため、入力パラメータは存在しない。

### 入力データソース

- Jest実行環境からのグローバル変数注入

## 出力仕様

### エクスポートされる関数

| 項目名 | 型 | 説明 |
|--------|-----|------|
| expect | JestExpect | アサーション関数 |
| it | Global.GlobalAdditions['it'] | テストケース定義 |
| test | Global.GlobalAdditions['test'] | テストケース定義（itのエイリアス） |
| fit | Global.GlobalAdditions['fit'] | focusedテスト（このテストのみ実行） |
| xit | Global.GlobalAdditions['xit'] | スキップされるテスト |
| xtest | Global.GlobalAdditions['xtest'] | スキップされるテスト（xitのエイリアス） |
| describe | Global.GlobalAdditions['describe'] | テストスイート定義 |
| xdescribe | Global.GlobalAdditions['xdescribe'] | スキップされるスイート |
| fdescribe | Global.GlobalAdditions['fdescribe'] | focusedスイート |
| beforeAll | Global.GlobalAdditions['beforeAll'] | スイート開始前フック |
| beforeEach | Global.GlobalAdditions['beforeEach'] | 各テスト前フック |
| afterEach | Global.GlobalAdditions['afterEach'] | 各テスト後フック |
| afterAll | Global.GlobalAdditions['afterAll'] | スイート終了後フック |
| jest | Jest | jestオブジェクト（モック機能等） |

### エクスポートされる型

| 型名 | 説明 |
|------|------|
| jest.Mock<T> | モック関数の型 |
| jest.Mocked<T> | モック化されたオブジェクト型 |
| jest.MockedClass<T> | モック化されたクラス型 |
| jest.MockedFunction<T> | モック化された関数型 |
| jest.MockedObject<T> | モック化されたオブジェクト型 |
| jest.Replaced<T> | 置換されたプロパティの型 |
| jest.Spied<T> | スパイされたクラス/関数の型 |
| jest.SpiedClass<T> | スパイされたクラスの型 |
| jest.SpiedFunction<T> | スパイされた関数の型 |
| jest.SpiedGetter<T> | スパイされたgetterの型 |
| jest.SpiedSetter<T> | スパイされたsetterの型 |

### 出力先

- テストコード内でのインポート

## 処理フロー

### 処理シーケンス

```
1. テストコードが @jest/globals をインポート
   └─ ESModule形式でのimport文

2. Jest実行環境がグローバル変数を注入
   └─ jest-runtimeによるグローバル設定

3. エクスポートされた変数をテストコードで使用
   └─ expect, test, describe等の呼び出し
```

### ランタイムエラー

```
Jest環境外で @jest/globals をインポートした場合:
→ Error: 'Do not import `@jest/globals` outside of the Jest test environment'
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-29-01 | Jest環境限定 | Jest環境外でのインポートは実行時エラー | 常時 |
| BR-29-02 | 型宣言のみ | 実際の関数実装はJestランタイムが提供 | 常時 |
| BR-29-03 | namespaceエクスポート | jest.Mock等の型はjest namespace内で提供 | TypeScript利用時 |

### 計算ロジック

計算処理は存在しない。

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

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

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

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Error | Jest環境外でインポート | Jestテストファイル内でのみ使用 |

### リトライ仕様

リトライ処理は存在しない。

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

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

## パフォーマンス要件

- 型定義のみのパッケージであり、実行時オーバーヘッドは最小限

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

- 特になし（型定義パッケージ）

## 備考

- @jest/globalsはTypeScriptの型安全性を提供するためのパッケージ
- 実際のグローバル関数はjest-runtimeによって注入される
- ESModulesでの明示的インポートを推奨する場合に使用

---

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

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

### 推奨読解順序

#### Step 1: パッケージ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | package.json | `packages/jest-globals/package.json` | 依存関係 |
| 1-2 | index.ts | `packages/jest-globals/src/index.ts` | エクスポート定義 |

**読解のコツ**:
- package.jsonで依存パッケージを確認（@jest/environment, @jest/expect, @jest/types, jest-mock）
- index.tsはdeclare文で型宣言のみを行い、最後にエラーをthrow

#### Step 2: エクスポートされる型を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-globals/src/index.ts` | jest namespace内の型 |

**主要処理フロー**:
- **8-10行目**: 型のインポート（Jest, JestExpect, Global）
- **11-26行目**: jest-mockからの型インポート
- **28行目**: expect関数の型宣言
- **30-41行目**: テスト関数・フック関数の型宣言
- **43行目**: jestオブジェクトの型宣言
- **46-91行目**: jest namespaceで型エイリアスを定義
- **93行目**: jestのエクスポート
- **95-97行目**: 環境外インポート時のエラーthrow

#### Step 3: Global型の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Global.ts | `packages/jest-types/src/Global.ts` | GlobalAdditions型 |

**主要処理フロー**:
- **122-126行目**: ItBase（テスト関数の基本インターフェース）
- **128-132行目**: It（only, skip, todoを含む拡張）
- **145-147行目**: ItConcurrent（concurrent対応）
- **149-157行目**: Describe（テストスイート定義）
- **159-172行目**: TestFrameworkGlobals（全グローバル関数）
- **174-176行目**: GlobalAdditions（__coverage__を追加）

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

```
テストコード
    │
    └─ import { expect, test, jest } from '@jest/globals'
           │
           └─ @jest/globals/src/index.ts
                  │
                  ├─ declare const expect: JestExpect
                  │      └─ @jest/expect (JestExpect型)
                  │
                  ├─ declare const it/test/describe等
                  │      └─ @jest/types (Global.GlobalAdditions)
                  │
                  └─ declare namespace jest
                         └─ jest-mock (Mock, Mocked等の型)
```

### データフロー図

```
[型定義]                            [ランタイム]

@jest/types ─────────────┐
   │                     │
   ├─ Global.GlobalAdditions    jest-runtime
   │                     │          │
@jest/expect ────────────┤          ├─▶ globalThis.expect
   │                     │          ├─▶ globalThis.test
   └─ JestExpect        ├─▶ @jest/globals ◀─┤
                        │          ├─▶ globalThis.describe
jest-mock ──────────────┤          └─▶ globalThis.jest
   │                     │
   ├─ Mock              │
   ├─ Mocked            │
   └─ Spied等           │
                        │
@jest/environment ──────┘
   │
   └─ Jest型
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-globals/src/index.ts` | ソース | グローバル変数エクスポート |
| package.json | `packages/jest-globals/package.json` | 設定 | パッケージ定義 |
| Global.ts | `packages/jest-types/src/Global.ts` | 型定義 | GlobalAdditions型 |
| index.ts | `packages/jest-expect/src/index.ts` | ソース | JestExpect実装 |
| index.ts | `packages/jest-environment/src/index.ts` | 型定義 | Jest型 |
