# 画面設計書 13-Timer Mocksページ

## 概要

本ドキュメントは、JestドキュメントサイトにおけるTimer Mocksページの画面設計を定義する。このページはJestのタイマーモック機能（Fake Timers）の使い方を詳細に説明するガイドページである。

### 本画面の処理概要

Timer Mocksページは、JavaScriptのネイティブタイマー関数（setTimeout、setInterval等）をモックする方法を解説する技術ドキュメントページである。テスト環境でのタイマー制御により、時間経過に依存するコードを効率的にテストする方法を提供する。

**業務上の目的・背景**：実際の時間経過を待つことなくタイマー関連のコードをテストする必要がある。setTimeout、setInterval等を使用するコードのテストでは、実時間を待つと非効率であり、テストが不安定になる可能性がある。Fake Timers機能により、時間を制御してテストを高速かつ確実に実行できる。

**画面へのアクセス方法**：
1. ドキュメントサイトのナビゲーションメニューから「Docs」ドロップダウンを選択
2. サイドバーの「Guides」セクションから「Timer Mocks」を選択
3. Snapshot Testingページの「Next」ボタンから遷移

**主要な操作・処理内容**：
1. Fake Timersの有効化方法の学習：jest.useFakeTimers()の使用方法
2. タイマーの実行制御：jest.runAllTimers()、jest.runOnlyPendingTimers()の使い方
3. 時間の進行制御：jest.advanceTimersByTime()によるミリ秒単位の時間進行
4. アニメーションフレームの制御：jest.advanceTimersToNextFrame()の使用方法
5. 選択的フェイク：doNotFakeオプションによる特定APIの除外方法
6. 実タイマーへの復元：jest.useRealTimers()の使用方法

**画面遷移**：
- 遷移元：Snapshot Testingページ、サイドバーナビゲーション、検索結果
- 遷移先：Manual Mocksページ、JestObjectAPIページ（Fake Timers API）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 15 | @jest/fake-timers | 主機能 | useFakeTimers、runAllTimers等のタイマーモック機能 |
| 14 | jest-mock | 補助機能 | jest.spyOn()によるsetTimeoutのスパイ |

## 画面種別

ドキュメント / ガイド

## URL/ルーティング

- URL: `/docs/timer-mocks`
- ファイルパス: `docs/TimerMocks.md`

## 入出力項目

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

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | テキスト | "Timer Mocks" |
| 2 | 導入文 | テキスト | タイマーモックの概要説明 |
| 3 | Enable Fake Timersセクション | コードブロック＋テキスト | Fake Timersの有効化方法 |
| 4 | Run All Timersセクション | コードブロック＋テキスト | すべてのタイマー実行方法 |
| 5 | Run Pending Timersセクション | コードブロック＋テキスト | 保留中タイマーのみ実行 |
| 6 | Advance Timers by Timeセクション | コードブロック＋テキスト | 時間進行による実行制御 |
| 7 | Advance Timers to Next Frameセクション | コードブロック＋テキスト | アニメーションフレーム制御 |
| 8 | Selective Fakingセクション | コードブロック＋テキスト | 選択的モック設定 |
| 9 | Fake Timers API リンク | 情報ボックス | JestObjectAPI へのリンク |
| 10 | サイドバー | ナビゲーション | ドキュメント目次 |
| 11 | Prev/Nextナビゲーション | ボタン | 前後ページへの遷移リンク |

## イベント仕様

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

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

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

ユーザーが内部ドキュメントリンク（JestObjectAPI等）をクリックすると、該当するドキュメントページに遷移する。

### 3-外部リンククリック

ユーザーがYouTube等の外部リンクをクリックすると、新しいタブで外部サイトが開く。

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

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

## メッセージ仕様

該当なし

## 例外処理

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

## 備考

- Docusaurusフレームワークで自動生成されるページ
- Markdownファイル（docs/TimerMocks.md）から静的HTMLに変換
- コードブロックにはシンタックスハイライトが適用される
- 「Back to the Future」への参照リンク含む（Great Scott!）

---

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

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

### 推奨読解順序

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

Fake Timersの内部データ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/@jest/fake-timers/src/index.ts` | FakeTimers クラスの型定義とエクスポートを確認 |

**読解のコツ**: @jest/fake-timersパッケージは@sinonjs/fake-timersを内部で使用している。JestはこれをラップしてuseFakeTimers等のAPIを提供する。

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

jestオブジェクトからのFake Timers APIの呼び出しを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | JestObjectAPI.md | `docs/JestObjectAPI.md` | Fake Timers セクションのAPI定義を確認 |
| 2-2 | index.ts | `packages/jest-runtime/src/index.ts` | jestオブジェクトの実装を確認 |

**主要処理フロー**:
1. **jest.useFakeTimers()**: グローバルタイマー関数をモックに置き換え
2. **jest.runAllTimers()**: すべての保留中タイマーを即座に実行
3. **jest.advanceTimersByTime(ms)**: 指定ミリ秒分時間を進める
4. **jest.useRealTimers()**: 元のタイマー関数を復元

#### Step 3: Fake Timers の実装詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | modernFakeTimers.ts | `packages/@jest/fake-timers/src/modernFakeTimers.ts` | Modern Fake Timers の実装（@sinonjs/fake-timers使用） |
| 3-2 | legacyFakeTimers.ts | `packages/@jest/fake-timers/src/legacyFakeTimers.ts` | Legacy Fake Timers の実装 |

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

```
jest.useFakeTimers()
    │
    ├─ packages/jest-runtime/src/index.ts
    │      └─ _fakeTimersImplementation.useFakeTimers()
    │
    └─ packages/@jest/fake-timers/src/
           ├─ modernFakeTimers.ts (デフォルト)
           │      └─ @sinonjs/fake-timers
           │
           └─ legacyFakeTimers.ts (legacy モード)
                   └─ 独自実装

jest.runAllTimers()
    │
    └─ FakeTimers.runAllTimers()
           └─ すべての setTimeout/setInterval コールバックを実行

jest.advanceTimersByTime(ms)
    │
    └─ FakeTimers.advanceTimersByTime(ms)
           └─ 指定時間分のタイマーコールバックを実行
```

### データフロー図

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

jest.useFakeTimers() ───▶ グローバル関数置換 ───▶ モックタイマー有効
                               │
                               ▼
                    setTimeout() 呼び出し
                               │
                               ▼
                    タイマーキューに登録
                               │
jest.runAllTimers() ───▶ キュー内タイマー実行 ───▶ コールバック実行
       or                      │
jest.advanceTimersByTime() ────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| TimerMocks.md | `docs/TimerMocks.md` | ドキュメント | ページコンテンツ定義 |
| index.ts | `packages/@jest/fake-timers/src/index.ts` | ソース | Fake Timers エクスポート |
| modernFakeTimers.ts | `packages/@jest/fake-timers/src/modernFakeTimers.ts` | ソース | Modern実装 |
| legacyFakeTimers.ts | `packages/@jest/fake-timers/src/legacyFakeTimers.ts` | ソース | Legacy実装 |
| JestObjectAPI.md | `docs/JestObjectAPI.md` | ドキュメント | API リファレンス |
| index.ts | `packages/jest-runtime/src/index.ts` | ソース | jestオブジェクト実装 |
