# 画面設計書 20-Mock Function APIページ

## 概要

本ドキュメントは、JestドキュメントサイトにおけるMock Function APIページの画面設計を定義する。このページはJestのモック関数（jest.fn()）の完全なAPIリファレンスを提供する技術ドキュメントページである。

### 本画面の処理概要

Mock Function APIページは、Jestのモック関数作成・操作に関するAPIの完全なリファレンスを提供する技術ドキュメントページである。jest.fn()、mockImplementation、mockReturnValue等のモック関数メソッドを網羅的に解説する。

**業務上の目的・背景**：モック関数はJestテストにおいて依存関係の分離に不可欠な機能である。関数の呼び出し履歴の追跡、戻り値の制御、実装の差し替え等、テストシナリオに応じた柔軟なモック設定を可能にする。TypeScriptとの型安全な連携方法も提供する。

**画面へのアクセス方法**：
1. ドキュメントサイトのナビゲーションメニューから「API」を選択
2. サイドバーの「API Reference」セクションから「Mock Functions」を選択
3. Expect APIページからの遷移

**主要な操作・処理内容**：
1. モック関数の作成方法：jest.fn()の使用方法
2. モック実装の設定：mockImplementation、mockImplementationOnce
3. 戻り値の設定：mockReturnValue、mockReturnValueOnce、mockResolvedValue等
4. 呼び出し履歴の参照：mock.calls、mock.results、mock.instances
5. モックのリセット：mockClear、mockReset、mockRestore
6. TypeScript連携：jest.Mock、jest.Mocked、jest.mocked()

**画面遷移**：
- 遷移元：Expect APIページ、サイドバーナビゲーション、検索結果
- 遷移先：Jest Object APIページ、Configurationページ

**権限による表示制御**：なし（公開ドキュメントのため全ユーザーが閲覧可能）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 14 | jest-mock | 主機能 | モック関数の生成と管理 |

## 画面種別

ドキュメント / APIリファレンス

## URL/ルーティング

- URL: `/docs/mock-function-api`
- ファイルパス: `docs/MockFunctionAPI.md`

## 入出力項目

該当なし（静的コンテンツページのため）

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | テキスト | "Mock Functions" |
| 2 | 導入文 | テキスト | モック関数の概要説明 |
| 3 | Methodsセクション | 目次 | API一覧へのリンク |
| 4 | mockFn.getMockImplementation() | コードブロック＋テキスト | 実装取得 |
| 5 | mockFn.getMockName() | コードブロック＋テキスト | モック名取得 |
| 6 | mockFn.mock.calls | コードブロック＋テキスト | 呼び出し引数配列 |
| 7 | mockFn.mock.results | コードブロック＋テキスト | 呼び出し結果配列 |
| 8 | mockFn.mock.instances | コードブロック＋テキスト | インスタンス配列 |
| 9 | mockFn.mock.contexts | コードブロック＋テキスト | コンテキスト配列 |
| 10 | mockFn.mock.lastCall | コードブロック＋テキスト | 最後の呼び出し引数 |
| 11 | mockFn.mockClear() | コードブロック＋テキスト | 呼び出し情報クリア |
| 12 | mockFn.mockReset() | コードブロック＋テキスト | モックリセット |
| 13 | mockFn.mockRestore() | コードブロック＋テキスト | 元の実装復元 |
| 14 | mockFn.mockImplementation(fn) | コードブロック＋テキスト | 実装設定 |
| 15 | mockFn.mockImplementationOnce(fn) | コードブロック＋テキスト | 一度だけの実装 |
| 16 | mockFn.mockReturnValue(value) | コードブロック＋テキスト | 戻り値設定 |
| 17 | mockFn.mockReturnValueOnce(value) | コードブロック＋テキスト | 一度だけの戻り値 |
| 18 | mockFn.mockResolvedValue(value) | コードブロック＋テキスト | Promise解決値 |
| 19 | mockFn.mockRejectedValue(value) | コードブロック＋テキスト | Promise拒否値 |
| 20 | mockFn.withImplementation(fn, callback) | コードブロック＋テキスト | 一時的実装 |
| 21 | TypeScript Usageセクション | コードブロック＋テキスト | 型安全なモック |
| 22 | サイドバー | ナビゲーション | ドキュメント目次 |
| 23 | Prev/Nextナビゲーション | ボタン | 前後ページへの遷移リンク |

## イベント仕様

### 1-コードブロックのコピー

ユーザーがコードブロックのコピーボタンをクリックすると、コード内容がクリップボードにコピーされる。

### 2-アンカーリンククリック

ユーザーが目次のアンカーリンクをクリックすると、該当するセクションにスクロールする。

### 3-内部ドキュメントリンククリック

ユーザーがJest Object API、Configuration等のリンクをクリックすると、該当するドキュメントページに遷移する。

### 4-コードタブの切り替え

JavaScript/TypeScriptタブを切り替えると、対応する言語のコードサンプルが表示される。

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

該当なし（静的コンテンツページのためデータベース操作なし）

## メッセージ仕様

該当なし

## 例外処理

| 例外状態 | 表示・動作 |
|---------|-----------|
| ページが見つからない | 404エラーページを表示 |

## 備考

- Docusaurusフレームワークで自動生成されるページ
- Markdownファイル（docs/MockFunctionAPI.md）から静的HTMLに変換
- コードブロックにはシンタックスハイライトが適用される
- JavaScript/TypeScriptのコードタブ切り替え機能を使用
- TOCInlineコンポーネントで目次を自動生成
- Replaced Properties セクション（jest.replaceProperty関連）を含む

---

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

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

### 推奨読解順序

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

モック関数の型定義とデータ構造を理解する。

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

**読解のコツ**:
- Mock型はFunctionとMockInstanceを継承し、呼び出し可能でありながらモック機能を持つ
- MockFunctionStateはmock.calls、mock.results等の呼び出し履歴を管理する
- Replaced型はjest.replaceProperty()で作成されたプロパティ置換を管理する

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

jest.fn()とモックメソッドの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-mock/src/index.ts` | ModuleMocker.fn()の実装を確認 |

**主要処理フロー**:
1. **jest.fn()**: 新しいモック関数を生成
2. **mockImplementation(fn)**: 実装関数を設定（Line 146）
3. **mockReturnValue(value)**: 戻り値を設定（Line 152）
4. **mock.calls**: 呼び出し引数の配列を参照（Line 54）

#### Step 3: モック状態管理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | MockFunctionState | `packages/jest-mock/src/index.ts` | calls、results、instances、contexts、lastCallの管理（Line 178-207） |

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

```
jest.fn(implementation)
    │
    └─ packages/jest-mock/src/index.ts
           └─ ModuleMocker.fn(implementation)
                  │
                  ├─ createMockFunction()
                  │      └─ Mock関数オブジェクト生成
                  │
                  └─ mockImplementation(implementation)
                         └─ 実装関数を設定

mockFn(arg1, arg2)  // モック関数呼び出し
    │
    └─ モック関数内部処理
           ├─ mock.calls.push([arg1, arg2])
           ├─ mock.contexts.push(this)
           ├─ 実装関数実行 or 戻り値返却
           └─ mock.results.push({type: 'return', value: result})

mockFn.mockClear()
    │
    └─ packages/jest-mock/src/index.ts
           └─ mockClear() [Line 143]
                  └─ mock.calls = []
                     mock.results = []
                     mock.instances = []
                     mock.contexts = []
```

### データフロー図

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

jest.fn() ───▶ Mock関数生成 ───▶ mockFn オブジェクト
                                      │
                    ┌─────────────────┼─────────────────┐
                    ▼                 ▼                 ▼
          mockImplementation   mockReturnValue   mockResolvedValue
                    │                 │                 │
                    ▼                 ▼                 ▼
               実装関数設定       戻り値設定       Promise解決値設定

mockFn(args) ───▶ 呼び出し記録
                       │
                       ├─ mock.calls に引数追加
                       ├─ mock.contexts に this 追加
                       ├─ 実装関数実行 or 戻り値返却
                       └─ mock.results に結果追加
                                │
                                ▼
                          戻り値 or 例外
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| MockFunctionAPI.md | `docs/MockFunctionAPI.md` | ドキュメント | ページコンテンツ定義 |
| index.ts | `packages/jest-mock/src/index.ts` | ソース | モック関数実装（Line 1-785） |

#### 主要な型・インターフェース（packages/jest-mock/src/index.ts）

| 型名 | 行番号 | 役割 |
|-----|--------|------|
| Mock | Line 123-127 | モック関数の型定義 |
| MockInstance | Line 135-158 | モック関数インスタンスのインターフェース |
| Replaced | Line 160-169 | 置換プロパティのインターフェース |
| MockFunctionState | Line 178-207 | モック状態（calls, results等） |

#### 主要なメソッド（packages/jest-mock/src/index.ts）

| メソッド | 行番号 | 役割 |
|---------|--------|------|
| getMockImplementation | Line 140 | 現在の実装を取得 |
| getMockName | Line 141 | モック名を取得 |
| mockClear | Line 143 | 呼び出し情報をクリア |
| mockReset | Line 144 | モックをリセット |
| mockRestore | Line 145 | 元の実装を復元 |
| mockImplementation | Line 146 | 実装を設定 |
| mockImplementationOnce | Line 147 | 一度だけの実装を設定 |
| mockReturnValue | Line 152 | 戻り値を設定 |
| mockReturnValueOnce | Line 153 | 一度だけの戻り値を設定 |
| mockResolvedValue | Line 154 | Promise解決値を設定 |
| mockRejectedValue | Line 156 | Promise拒否値を設定 |
| withImplementation | Line 148-149 | 一時的な実装を設定 |
