# 機能設計書 10-expect

## 概要

本ドキュメントは、Jestのアサーションライブラリ「expect」の機能設計を記述したものである。

### 本機能の処理概要

expectパッケージは、テストにおけるアサーション（検証）機能を提供するライブラリである。`expect(value).toBe(expected)`のような直感的なAPIにより、テスト対象の値が期待通りであることを検証する。マッチャー（toBe、toEqual、toContain等）、修飾子（not、resolves、rejects）、非対称マッチャー（expect.any、expect.arrayContaining等）を組み合わせて、柔軟なアサーションを記述できる。

**業務上の目的・背景**：テストの核心は「期待通りの動作をしているか」の検証にある。expectは、この検証を直感的かつ表現力豊かに記述できるAPIを提供する。明確なエラーメッセージ、カスタムマッチャーの拡張性、TypeScriptサポートにより、テストコードの品質と保守性を向上させる。

**機能の利用シーン**：
- 値の等価性検証（toBe、toEqual）
- 配列・オブジェクトの部分一致（toContain、toMatchObject）
- 例外のスロー検証（toThrow）
- モック関数の呼び出し検証（toHaveBeenCalled）
- Promise の解決/拒否検証（resolves/rejects）
- スナップショットテスト（toMatchSnapshot）

**主要な処理内容**：
1. expect関数による期待値オブジェクトの生成
2. マッチャー関数による実際の値と期待値の比較
3. 比較結果に応じたテスト成功/失敗の判定
4. 失敗時の明確なエラーメッセージ生成
5. カスタムマッチャーの登録と実行
6. 非対称マッチャーによる柔軟な比較

**関連システム・外部連携**：
- jest-matcher-utils: マッチャーエラーメッセージのフォーマット
- @jest/expect-utils: 等価性比較ユーティリティ
- jest-diff: オブジェクト差分の表示
- jest-mock: モック関数のアサーション

**権限による制御**：特になし。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | N/A | N/A | 本機能はアサーションライブラリであり、画面は存在しない |

## 機能種別

アサーションライブラリ / マッチャーエンジン / 拡張機能

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| actual | any | Yes | 検証対象の値 | N/A |
| expected | any | Yes（マッチャーによる） | 期待値 | N/A |

### 入力データソース

- テストコード内のexpect呼び出し
- カスタムマッチャーの登録（expect.extend）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| pass | boolean | アサーション成功/失敗 |
| message | string | 失敗時のエラーメッセージ |

### 出力先

- テストフレームワーク（jest-circus/jest-jasmine2）
- 失敗時は例外としてスロー

## 処理フロー

### 処理シーケンス

```
1. expect呼び出し
   └─ 期待値オブジェクトの生成
2. マッチャー呼び出し
   └─ .toBe()、.toEqual()等
3. 比較実行
   └─ actual と expected の比較
4. 結果判定
   └─ pass: true/false の決定
5. 結果処理
   └─ 失敗時は JestAssertionError をスロー
```

### フローチャート

```mermaid
flowchart TD
    A[expect actual] --> B[Expectation オブジェクト生成]
    B --> C[マッチャー呼び出し]
    C --> D{修飾子あり?}
    D -->|not| E[結果を反転]
    D -->|resolves| F[Promise 解決を待機]
    D -->|rejects| G[Promise 拒否を待機]
    D -->|なし| H[マッチャー実行]
    E --> H
    F --> H
    G --> H
    H --> I{pass?}
    I -->|Yes| J[テスト成功]
    I -->|No| K[エラーメッセージ生成]
    K --> L[JestAssertionError スロー]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | not修飾子 | 結果を反転する | .not使用時 |
| BR-002 | resolves | Promiseの解決値を検証 | .resolves使用時 |
| BR-003 | rejects | Promiseの拒否理由を検証 | .rejects使用時 |
| BR-004 | 厳密等価 | toBeはObject.isで比較 | toBe使用時 |
| BR-005 | 深い等価 | toEqualは再帰的に比較 | toEqual使用時 |
| BR-006 | カスタムテスター | addEqualityTestersで等価性判定をカスタマイズ | 設定時 |

### 計算ロジック

等価性の判定（@jest/expect-utils）:
- プリミティブ: Object.is()
- オブジェクト: 再帰的なプロパティ比較
- 配列: 長さと各要素の比較
- Map/Set: 内容の比較
- カスタムテスター: ユーザー定義の比較関数

## データベース操作仕様

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

データベース操作は本パッケージでは行わない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ASSERTION_FAILED | アサーション失敗 | 期待値と実際値が不一致 | テストまたはコードを修正 |
| INVALID_MATCHER | マッチャーエラー | 不正なマッチャー使用 | 正しいマッチャーを使用 |
| PROMISE_NOT_RESOLVED | Promise未解決 | resolvesでPromiseが解決しない | Promiseの実装を確認 |

### リトライ仕様

アサーションにリトライ機能はない

## トランザクション仕様

トランザクション処理は本パッケージには存在しない

## パフォーマンス要件

- マッチャー実行は同期的（一部を除く）
- 大きなオブジェクトの比較は時間がかかる可能性あり

## セキュリティ考慮事項

- 期待値にはテストコードで指定した値のみ使用
- 機密情報がエラーメッセージに含まれる可能性あり

## 備考

- expect.extend()でカスタムマッチャーを追加可能
- expect.assertions(n)で期待するアサーション数を指定可能

---

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

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

### 推奨読解順序

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

マッチャーの型定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/expect/src/types.ts` | MatcherState、MatcherContext、Matchers型 |

**読解のコツ**: MatcherStateはマッチャー実行時のコンテキスト情報を保持し、isNot、promise等の修飾子情報を含む。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/expect/src/index.ts` | expect関数の実装 |

**主要処理フロー**:
1. **105-157行目**: expect関数（Expectationオブジェクト生成）
2. **119-154行目**: 各マッチャーへのバインディング
3. **163-217行目**: makeResolveMatcher（resolves修飾子）
4. **219-273行目**: makeRejectMatcher（rejects修飾子）
5. **275-395行目**: makeThrowingMatcher（マッチャー実行とエラー処理）
6. **397-398行目**: expect.extend（カスタムマッチャー登録）

#### Step 3: 組み込みマッチャーの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | matchers.ts | `packages/expect/src/matchers.ts` | toBe、toEqual等の実装 |

**主要処理フロー**:
- toBe: Object.isによる厳密等価比較
- toEqual: @jest/expect-utilsのequalsによる深い比較
- toContain: 配列/文字列の包含チェック
- toMatchObject: オブジェクトの部分一致

#### Step 4: 非対称マッチャーの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | asymmetricMatchers.ts | `packages/expect/src/asymmetricMatchers.ts` | expect.any、expect.arrayContaining等 |

**主要処理フロー**:
- any: 型チェック
- anything: undefinedとnull以外にマッチ
- arrayContaining: 配列の部分一致
- objectContaining: オブジェクトの部分一致
- stringContaining/stringMatching: 文字列マッチ

#### Step 5: モック用マッチャーの理解

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | spyMatchers.ts | `packages/expect/src/spyMatchers.ts` | toHaveBeenCalled等 |

**主要処理フロー**:
- toHaveBeenCalled: モック関数が呼ばれたか
- toHaveBeenCalledWith: 特定の引数で呼ばれたか
- toHaveBeenCalledTimes: 呼び出し回数

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

```
expect/src/index.ts
    │
    ├─ expect(actual)
    │      │
    │      └─ Expectation オブジェクト生成
    │             │
    │             ├─ .toBe/.toEqual/... (マッチャー)
    │             │      └─ makeThrowingMatcher
    │             │             │
    │             │             ├─ matchers.ts
    │             │             │
    │             │             └─ 結果判定・エラー処理
    │             │
    │             ├─ .not.toBe/... (否定)
    │             │      └─ makeThrowingMatcher (isNot=true)
    │             │
    │             ├─ .resolves.toBe/... (Promise解決)
    │             │      └─ makeResolveMatcher
    │             │             └─ makeThrowingMatcher
    │             │
    │             └─ .rejects.toBe/... (Promise拒否)
    │                    └─ makeRejectMatcher
    │                           └─ makeThrowingMatcher
    │
    ├─ expect.extend(matchers)
    │      └─ setMatchers
    │
    └─ expect.any/anything/arrayContaining/...
           └─ asymmetricMatchers.ts
```

### データフロー図

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

actual ──────────────────▶ expect(actual) ─────────▶ Expectation
    │                           │
    ▼                           ▼
expected ────────────────▶ .matcher(expected) ────▶ マッチャー実行
    │                           │
    ▼                           ▼
                          比較処理 ─────────────────▶ { pass, message }
                                │
                                ▼
                          ┌─────────────┐
                          │ pass = true │ → テスト成功
                          │ pass = false│ → JestAssertionError
                          └─────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/expect/src/index.ts` | ソース | メインエントリ |
| matchers.ts | `packages/expect/src/matchers.ts` | ソース | 組み込みマッチャー |
| spyMatchers.ts | `packages/expect/src/spyMatchers.ts` | ソース | モック用マッチャー |
| toThrowMatchers.ts | `packages/expect/src/toThrowMatchers.ts` | ソース | 例外マッチャー |
| asymmetricMatchers.ts | `packages/expect/src/asymmetricMatchers.ts` | ソース | 非対称マッチャー |
| jestMatchersObject.ts | `packages/expect/src/jestMatchersObject.ts` | ソース | マッチャー管理 |
| types.ts | `packages/expect/src/types.ts` | 型定義 | 型定義 |
| extractExpectedAssertionsErrors.ts | `packages/expect/src/extractExpectedAssertionsErrors.ts` | ソース | アサーションエラー抽出 |
