# 画面設計書 19-Expect APIページ

## 概要

本ドキュメントは、JestドキュメントサイトにおけるExpect APIページの画面設計を定義する。このページはJestのexpectアサーションAPIの完全なリファレンスを提供する技術ドキュメントページである。

### 本画面の処理概要

Expect APIページは、Jestのexpect関数とマッチャー（toBe、toEqual、toContain等）の完全なAPIリファレンスを提供する技術ドキュメントページである。テストのアサーション記述に必要なすべてのマッチャーを網羅的に解説する。

**業務上の目的・背景**：テストの核心となるアサーション部分について、開発者が適切なマッチャーを選択し、正しく使用できるようにする。各マッチャーの動作、引数、使用例を詳細に記載することで、テスト精度の向上とデバッグ効率の改善に寄与する。

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

**主要な操作・処理内容**：
1. 基本マッチャーの参照：toBe、toEqual、toBeTruthy等
2. 非同期マッチャーの参照：resolves、rejects
3. 例外マッチャーの参照：toThrow、toThrowError
4. スナップショットマッチャーの参照：toMatchSnapshot、toMatchInlineSnapshot
5. 非対称マッチャーの参照：expect.any、expect.objectContaining等
6. カスタムマッチャーの作成方法：expect.extend

**画面遷移**：
- 遷移元：API Reference（Globals）ページ、サイドバーナビゲーション、検索結果
- 遷移先：Mock Function APIページ、Snapshot Testingページ

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | expect | 主機能 | expectマッチャー処理 |
| 16 | jest-snapshot | 補助機能 | スナップショットマッチャー |

## 画面種別

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

## URL/ルーティング

- URL: `/docs/expect`
- ファイルパス: `docs/ExpectAPI.md`

## 入出力項目

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

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | テキスト | "Expect" |
| 2 | 導入文 | テキスト | expectの概要説明 |
| 3 | Methodsセクション | 目次 | マッチャー一覧へのリンク |
| 4 | expect(value) | テキスト | expect基本使用法 |
| 5 | expect.extend(matchers) | コードブロック＋テキスト | カスタムマッチャー追加 |
| 6 | expect.anything() | コードブロック＋テキスト | 任意値マッチャー |
| 7 | expect.any(constructor) | コードブロック＋テキスト | 型マッチャー |
| 8 | expect.arrayContaining(array) | コードブロック＋テキスト | 配列部分一致 |
| 9 | expect.objectContaining(object) | コードブロック＋テキスト | オブジェクト部分一致 |
| 10 | expect.stringContaining(string) | コードブロック＋テキスト | 文字列部分一致 |
| 11 | expect.stringMatching(regexp) | コードブロック＋テキスト | 正規表現マッチ |
| 12 | .not | コードブロック＋テキスト | 否定マッチャー |
| 13 | .resolves | コードブロック＋テキスト | Promise解決マッチャー |
| 14 | .rejects | コードブロック＋テキスト | Promise拒否マッチャー |
| 15 | .toBe(value) | コードブロック＋テキスト | 厳密等価マッチャー |
| 16 | .toEqual(value) | コードブロック＋テキスト | 深い等価マッチャー |
| 17 | .toMatchSnapshot() | コードブロック＋テキスト | スナップショット |
| 18 | .toThrow(error?) | コードブロック＋テキスト | 例外マッチャー |
| 19 | サイドバー | ナビゲーション | ドキュメント目次 |
| 20 | Prev/Nextナビゲーション | ボタン | 前後ページへの遷移リンク |

## イベント仕様

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

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

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

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

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

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

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

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

## メッセージ仕様

該当なし

## 例外処理

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

## 備考

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

---

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

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

### 推奨読解順序

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

expectの型定義とマッチャーの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/expect/src/types.ts` | Expect型、MatcherFunction型の定義を確認 |
| 1-2 | asymmetricMatchers.ts | `packages/expect/src/asymmetricMatchers.ts` | 非対称マッチャーの実装を確認 |

**読解のコツ**: expectパッケージはテストアサーションの中核を担う。各マッチャーはMatcherFunction型に準拠し、{pass: boolean, message: () => string}を返却する。

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

expect関数とマッチャーのエクスポートを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/expect/src/index.ts` | expectのエクスポートと初期化処理（Line 105-157）を確認 |
| 2-2 | matchers.ts | `packages/expect/src/matchers.ts` | 組み込みマッチャーの実装 |

**主要処理フロー**:
1. **expect(actual)**: expectation オブジェクトを生成
2. **expectation.toBe(expected)**: マッチャー実行、結果判定
3. **マッチャー失敗時**: JestAssertionError をスロー

#### Step 3: 各マッチャーの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | matchers.ts | `packages/expect/src/matchers.ts` | toBe、toEqual、toContain等の実装 |
| 3-2 | toThrowMatchers.ts | `packages/expect/src/toThrowMatchers.ts` | toThrow系マッチャーの実装 |
| 3-3 | spyMatchers.ts | `packages/expect/src/spyMatchers.ts` | toHaveBeenCalled等のスパイマッチャー |

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

```
expect(value).toBe(expected)
    │
    ├─ packages/expect/src/index.ts
    │      └─ expect() [Line 105]
    │             └─ expectation オブジェクト作成
    │
    └─ expectation.toBe()
           │
           └─ packages/expect/src/matchers.ts
                  └─ toBe マッチャー実行
                         │
                         ├─ Object.is(actual, expected)
                         │
                         └─ 結果: {pass: boolean, message: () => string}
                                │
                      ┌─────────┴─────────┐
                      ▼                   ▼
                  [pass]              [fail]
                      │                   │
                      ▼                   ▼
                   成功                JestAssertionError
```

### データフロー図

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

actual値 ───▶ expect(actual) ───▶ expectation オブジェクト
                                         │
expected値 ───────────────────────▶ .toBe(expected)
                                         │
                                         ▼
                                   マッチャー実行
                                         │
                      ┌──────────────────┼──────────────────┐
                      ▼                  ▼                  ▼
                   toBe              toEqual            toContain
                      │                  │                  │
                      ▼                  ▼                  ▼
              Object.is比較      deep-equal比較      includes比較
                      │
                      └──────────────────┬──────────────────┘
                                         │
                                         ▼
                                   {pass, message}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| ExpectAPI.md | `docs/ExpectAPI.md` | ドキュメント | ページコンテンツ定義 |
| index.ts | `packages/expect/src/index.ts` | ソース | expectエクスポート |
| matchers.ts | `packages/expect/src/matchers.ts` | ソース | 組み込みマッチャー |
| asymmetricMatchers.ts | `packages/expect/src/asymmetricMatchers.ts` | ソース | 非対称マッチャー |
| toThrowMatchers.ts | `packages/expect/src/toThrowMatchers.ts` | ソース | toThrow系マッチャー |
| spyMatchers.ts | `packages/expect/src/spyMatchers.ts` | ソース | スパイマッチャー |
| types.ts | `packages/expect/src/types.ts` | ソース | 型定義 |
