# 画面設計書 21-Jest Objectページ

## 概要

本ドキュメントは、Jestドキュメントサイトにおける「Jest Objectページ」の画面設計書です。JestオブジェクトのAPIリファレンスを提供し、テストファイル内で自動的に利用可能な`jest`オブジェクトの全メソッドを詳細に解説します。

### 本画面の処理概要

**業務上の目的・背景**：Jest Objectページは、開発者がテスト作成時に使用する`jest`オブジェクトの包括的なAPIリファレンスを提供します。`jest`オブジェクトは各テストファイル内で自動的にスコープに含まれ、モック作成、タイマー制御、モジュールシステム操作など、Jestの高度な機能にアクセスするためのエントリーポイントとなります。このドキュメントがなければ、開発者はJestの強力な機能を十分に活用できず、効果的なテスト作成が困難になります。

**画面へのアクセス方法**：ユーザーはヘッダーナビゲーションの「API」リンクからAPI Referenceページにアクセスし、サイドバーから「The Jest Object」を選択するか、Mock Function APIページの「次へ」リンクから遷移します。URLは `/docs/jest-object` です。

**主要な操作・処理内容**：
1. Mock Modules APIの参照（jest.mock, jest.unmock, jest.doMock等）
2. Mock Functions APIの参照（jest.fn, jest.spyOn, jest.replaceProperty等）
3. Fake Timers APIの参照（jest.useFakeTimers, jest.runAllTimers等）
4. その他のユーティリティAPIの参照（jest.setTimeout, jest.retryTimes等）
5. コードサンプルのコピーと実行
6. TypeScript使用例の確認

**画面遷移**：Mock Function APIページから遷移、Configurationページへ遷移可能。サイドバーから他のAPIドキュメントにも直接アクセス可能。

**権限による表示制御**：特になし。すべてのユーザーが全コンテンツにアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | jest-runtime | 主機能 | jestオブジェクトのAPIリファレンス（モジュールモック、モジュールリセット等） |
| 15 | @jest/fake-timers | 補助機能 | フェイクタイマー関連API（useFakeTimers, runAllTimers等） |
| 14 | jest-mock | 補助機能 | モック関連API（jest.fn, jest.spyOn等） |

## 画面種別

詳細（ドキュメント参照）

## URL/ルーティング

- URL: `/docs/jest-object`
- ファイルパス: `docs/JestObjectAPI.md`
- Docusaurusによる静的サイト生成

## 入出力項目

本画面は静的ドキュメントページのため、主要な入力項目はありません。

| 項目名 | 種別 | 説明 |
|--------|------|------|
| 検索クエリ | 入力（オプション） | サイト内検索機能で使用 |
| コードブロック | 出力 | コピー可能なサンプルコード |
| 目次（TOC） | 出力 | ページ内ナビゲーション |

## 表示項目

| セクション | 表示内容 | 備考 |
|------------|----------|------|
| Mock Modules | jest.disableAutomock(), jest.enableAutomock(), jest.createMockFromModule(), jest.mock(), jest.Mocked, jest.mocked(), jest.unmock(), jest.deepUnmock(), jest.doMock(), jest.dontMock(), jest.setMock(), jest.requireActual(), jest.requireMock(), jest.onGenerateMock(), jest.resetModules(), jest.isolateModules(), jest.isolateModulesAsync() | モジュールモック制御のAPI群 |
| Mock Functions | jest.fn(), jest.isMockFunction(), jest.replaceProperty(), jest.spyOn(), jest.Replaced, jest.Spied, jest.clearAllMocks(), jest.resetAllMocks(), jest.restoreAllMocks() | モック関数作成・管理のAPI群 |
| Fake Timers | jest.useFakeTimers(), jest.useRealTimers(), jest.runAllTicks(), jest.runAllTimers(), jest.runAllTimersAsync(), jest.runAllImmediates(), jest.advanceTimersByTime(), jest.advanceTimersByTimeAsync(), jest.runOnlyPendingTimers(), jest.runOnlyPendingTimersAsync(), jest.advanceTimersToNextTimer(), jest.advanceTimersToNextTimerAsync(), jest.advanceTimersToNextFrame(), jest.clearAllTimers(), jest.getTimerCount(), jest.now(), jest.setSystemTime(), jest.setTimerTickMode(), jest.getRealSystemTime() | タイマーモック制御のAPI群 |
| Misc | jest.getSeed(), jest.isEnvironmentTornDown(), jest.retryTimes(), jest.setTimeout() | その他のユーティリティAPI |

## イベント仕様

### 1-目次クリック

ページ内の該当セクションへスクロール移動

### 2-コードブロックコピー

コードブロックの内容をクリップボードにコピー

### 3-タブ切り替え（JavaScript/TypeScript）

コードサンプルの言語表示を切り替え

### 4-サイドバーナビゲーション

他のドキュメントページへ遷移

### 5-前へ/次へリンク

Mock Function APIページまたはConfigurationページへ遷移

## データベース更新仕様

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

本画面は静的ドキュメントページのため、データベース操作は発生しません。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | 静的コンテンツのみ |

## メッセージ仕様

| メッセージID | メッセージ内容 | 表示条件 | 種別 |
|-------------|--------------|----------|------|
| - | - | - | 静的コンテンツのため該当なし |

## 例外処理

| 例外状況 | 対応内容 |
|----------|----------|
| ページが見つからない | Docusaurus標準の404ページを表示 |
| ネットワークエラー | ブラウザ標準のエラー表示 |

## 備考

- `jest`オブジェクトは`@jest/globals`から明示的にインポートすることも可能
- TypeScriptの型定義と使用例が各APIに提供されている
- jest.spyOnと`using`キーワードの組み合わせによる自動リストア機能が追加されている（Jest 30以降）
- フェイクタイマーは`@sinonjs/fake-timers`ライブラリをベースにしている

---

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

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

### 推奨読解順序

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

まず、Jestオブジェクトが提供するAPIの型定義を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-mock/src/index.ts` | MockInstance、Mock、MockMetadata等の型定義を確認（1-200行目） |
| 1-2 | index.ts | `packages/@jest/globals/src/index.ts` | jestオブジェクトのエクスポート構造を確認 |

**読解のコツ**: TypeScriptの型定義を先に理解することで、各APIの引数・戻り値が明確になります。

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

jestオブジェクトがどのようにテストファイルに注入されるかを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-runtime/src/index.ts` | Runtimeクラスの構造とjestオブジェクト生成を確認 |

**主要処理フロー**:
1. **159-200行目**: Runtimeクラスのプロパティ定義（モックレジストリ、タイマー実装等）
2. **169-171行目**: `_onGenerateMock`コールバック管理用Set

#### Step 3: モックモジュールAPIを理解する

jest.mock、jest.unmock等のモジュールモック機能の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/jest-runtime/src/index.ts` | jest.mock、jest.doMock、jest.unmockの実装 |

**主要処理フロー**:
- `_explicitShouldMock`: モック対象モジュールの管理Map
- `_mockFactories`: モックファクトリ関数の管理Map
- `_moduleRegistry`: モジュールキャッシュの管理

#### Step 4: モック関数APIを理解する

jest.fn、jest.spyOn等のモック関数作成機能の実装を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `packages/jest-mock/src/index.ts` | Mock、MockInstance型の定義（123-158行目） |

**主要処理フロー**:
- **123-127行目**: Mockインターフェースの定義（new演算子と関数呼び出しの両方に対応）
- **135-158行目**: MockInstanceインターフェース（mockImplementation、mockReturnValue等）
- **160-169行目**: Replacedインターフェース（プロパティ置換用）

#### Step 5: フェイクタイマーAPIを理解する

jest.useFakeTimers、jest.runAllTimers等のタイマーモック機能を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | modernFakeTimers.ts | `packages/@jest/fake-timers/src/modernFakeTimers.ts` | モダンフェイクタイマーの実装 |

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

```
テストファイル (*.test.ts)
    │
    ├─ jest.fn() / jest.spyOn()
    │      └─ jest-mock/ModuleMocker
    │             └─ Mock / MockInstance 生成
    │
    ├─ jest.mock() / jest.unmock()
    │      └─ jest-runtime/Runtime
    │             ├─ _explicitShouldMock 更新
    │             └─ _mockFactories 登録
    │
    └─ jest.useFakeTimers() / jest.runAllTimers()
           └─ @jest/fake-timers
                  └─ @sinonjs/fake-timers ラッパー
```

### データフロー図

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

jest.fn()    ───▶ ModuleMocker      ───▶ Mock関数オブジェクト
                  ・generateFromMetadata
                  ・_makeComponent

jest.mock()  ───▶ Runtime           ───▶ モック済みモジュール
                  ・_explicitShouldMock
                  ・_mockFactories

jest.useFakeTimers() ───▶ FakeTimers ───▶ モックタイマー環境
                          ・@sinonjs/fake-timers
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| JestObjectAPI.md | `docs/JestObjectAPI.md` | ドキュメント | Jest Objectページのソースファイル |
| index.ts | `packages/jest-runtime/src/index.ts` | ソース | Runtimeクラス（jestオブジェクト生成） |
| index.ts | `packages/jest-mock/src/index.ts` | ソース | モック関数の型定義と実装 |
| index.ts | `packages/@jest/globals/src/index.ts` | ソース | グローバルjestオブジェクトのエクスポート |
| modernFakeTimers.ts | `packages/@jest/fake-timers/src/modernFakeTimers.ts` | ソース | モダンフェイクタイマー実装 |
| legacyFakeTimers.ts | `packages/@jest/fake-timers/src/legacyFakeTimers.ts` | ソース | レガシーフェイクタイマー実装 |
