# 画面設計書 18-API Referenceページ

## 概要

本ドキュメントは、JestドキュメントサイトにおけるAPI Referenceページ（Globals）の画面設計を定義する。このページはJestのグローバルAPIリファレンスを提供する技術ドキュメントページである。

### 本画面の処理概要

API Referenceページは、Jestがテストファイルのグローバル環境に自動的に注入するメソッドとオブジェクト（describe、test、expect等）の完全なリファレンスを提供する技術ドキュメントページである。

**業務上の目的・背景**：Jestのテストを記述する際に使用するグローバルAPIの完全なリファレンスを提供することで、開発者が適切なAPIを選択し、正しく使用できるようにする。各APIの引数、戻り値、使用例を詳細に記載することで、学習コストを削減する。

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

**主要な操作・処理内容**：
1. テストブロックAPIの参照：describe、test/it、beforeAll/afterAll、beforeEach/afterEach
2. テスト修飾子の参照：.only、.skip、.todo、.each、.concurrent
3. expect APIへの誘導：アサーション関連は別ページを参照
4. TypeScript使用例の確認：型安全なテスト記述方法

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

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 4 | jest-circus | 主機能 | describe、test、hook関数の実行 |
| 10 | expect | 補助機能 | アサーション処理（別ページ参照） |

## 画面種別

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

## URL/ルーティング

- URL: `/docs/api`
- ファイルパス: `docs/GlobalAPI.md`

## 入出力項目

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

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | テキスト | "Globals" |
| 2 | 導入文 | テキスト | グローバルAPI概要説明 |
| 3 | Methodsセクション | 目次 | API一覧へのリンク |
| 4 | afterAll(fn, timeout) | コードブロック＋テキスト | afterAll APIリファレンス |
| 5 | afterEach(fn, timeout) | コードブロック＋テキスト | afterEach APIリファレンス |
| 6 | beforeAll(fn, timeout) | コードブロック＋テキスト | beforeAll APIリファレンス |
| 7 | beforeEach(fn, timeout) | コードブロック＋テキスト | beforeEach APIリファレンス |
| 8 | describe(name, fn) | コードブロック＋テキスト | describe APIリファレンス |
| 9 | describe.eachセクション | コードブロック＋テキスト | データ駆動テスト |
| 10 | test(name, fn, timeout) | コードブロック＋テキスト | test APIリファレンス |
| 11 | test.eachセクション | コードブロック＋テキスト | データ駆動テスト |
| 12 | test.concurrentセクション | コードブロック＋テキスト | 並行テスト実行 |
| 13 | test.failingセクション | コードブロック＋テキスト | 失敗期待テスト |
| 14 | test.todoセクション | コードブロック＋テキスト | TODO テスト |
| 15 | TypeScript Usageセクション | コードブロック＋テキスト | TypeScript使用例 |
| 16 | サイドバー | ナビゲーション | ドキュメント目次 |
| 17 | Prev/Nextナビゲーション | ボタン | 前後ページへの遷移リンク |

## イベント仕様

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

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

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

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

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

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

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

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

## メッセージ仕様

該当なし

## 例外処理

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

## 備考

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

---

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

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

### 推奨読解順序

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

テストブロックの型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-circus/src/types.ts` | DescribeBlock、TestEntry等の型定義を確認 |
| 1-2 | types.ts | `packages/@jest/types/src/Circus.ts` | Circus関連の型定義を確認 |

**読解のコツ**: jest-circusパッケージがテストブロック（describe、test）の実行を管理する。各ブロックは木構造で管理され、beforeAll/afterAll等のフック関数が適切なタイミングで実行される。

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

グローバルAPIのエクスポートを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/@jest/globals/src/index.ts` | グローバルAPIのエクスポートを確認 |
| 2-2 | index.ts | `packages/jest-circus/src/index.ts` | テストランナーのエントリーポイント |

**主要処理フロー**:
1. **describe(name, fn)**: テストスイートの作成とブロック登録
2. **test(name, fn, timeout)**: テストケースの作成と実行登録
3. **beforeAll/afterAll**: スイートレベルのセットアップ/ティアダウン
4. **beforeEach/afterEach**: テストレベルのセットアップ/ティアダウン

#### Step 3: テスト実行フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | run.ts | `packages/jest-circus/src/run.ts` | テスト実行ロジック |
| 3-2 | state.ts | `packages/jest-circus/src/state.ts` | テスト状態管理 |

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

```
describe('suite', () => {...})
    │
    ├─ packages/@jest/globals/src/index.ts
    │      └─ export { describe } from 'jest-circus'
    │
    └─ packages/jest-circus/src/index.ts
           └─ describe()
                  └─ state.ts: addDescribeBlock()
                         └─ DescribeBlock 追加

test('test', () => {...})
    │
    └─ packages/jest-circus/src/index.ts
           └─ test()
                  └─ state.ts: addTest()
                         └─ TestEntry 追加

テスト実行時:
    │
    └─ packages/jest-circus/src/run.ts
           └─ run()
                  ├─ beforeAll実行
                  ├─ テスト実行ループ
                  │      ├─ beforeEach実行
                  │      ├─ test fn実行
                  │      └─ afterEach実行
                  └─ afterAll実行
```

### データフロー図

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

describe() ───▶ DescribeBlock作成 ───▶ state登録
    │
    ├─ test() ───▶ TestEntry作成 ───▶ DescribeBlockに追加
    │
    ├─ beforeAll() ───▶ Hook登録 ───▶ スイート開始時実行
    │
    └─ afterEach() ───▶ Hook登録 ───▶ 各テスト後実行

                    run()実行
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
         [テスト成功]         [テスト失敗]
              │                   │
              ▼                   ▼
         結果: passed         結果: failed
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| GlobalAPI.md | `docs/GlobalAPI.md` | ドキュメント | ページコンテンツ定義 |
| index.ts | `packages/@jest/globals/src/index.ts` | ソース | グローバルAPIエクスポート |
| index.ts | `packages/jest-circus/src/index.ts` | ソース | テストランナー実装 |
| run.ts | `packages/jest-circus/src/run.ts` | ソース | テスト実行ロジック |
| state.ts | `packages/jest-circus/src/state.ts` | ソース | テスト状態管理 |
| types.ts | `packages/jest-circus/src/types.ts` | ソース | 型定義 |
| Circus.ts | `packages/@jest/types/src/Circus.ts` | ソース | Circus型定義 |
