# 機能設計書 11-@jest/expect

## 概要

本ドキュメントは、Jestテスティングフレームワークにおける`@jest/expect`パッケージの機能設計を記述する。このパッケージは、基本的な`expect`アサーションライブラリにスナップショットテスト機能を統合し、Jestのエコシステム全体で使用される`jestExpect`関数をエクスポートする。

### 本機能の処理概要

**業務上の目的・背景**：テスト駆動開発(TDD)やビヘイビア駆動開発(BDD)において、アサーション機能は不可欠である。`@jest/expect`は、基本的なアサーション機能に加え、UIコンポーネントやAPIレスポンスの変更検知に有効なスナップショットテスト機能を統合することで、開発者がより効率的にテストを記述できる環境を提供する。これにより、リグレッションテストの自動化と品質保証プロセスの効率化を実現する。

**機能の利用シーン**：開発者がJestでテストコードを記述する際に、`expect()`関数を使用してテスト対象の値を検証する場面で使用される。特に、`toMatchSnapshot()`や`toMatchInlineSnapshot()`などのスナップショットマッチャーを使用したUIコンポーネントテストやAPIレスポンステストで活用される。

**主要な処理内容**：
1. `expect`パッケージの基本アサーション機能のインポートと再エクスポート
2. `jest-snapshot`パッケージからスナップショットマッチャーのインポート
3. `expect.extend()`を使用したスナップショットマッチャーの拡張登録
4. `addSnapshotSerializer`メソッドの追加によるカスタムシリアライザー登録機能の提供
5. 型定義の拡張によるTypeScriptサポートの強化

**関連システム・外部連携**：`expect`パッケージ（基本アサーション機能）、`jest-snapshot`パッケージ（スナップショット機能）と密接に連携する。

**権限による制御**：特になし。全てのテストコードから同等にアクセス可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 19 | Expect APIページ | 参照画面 | スナップショットマッチャーを含むexpect拡張の説明 |

## 機能種別

API統合 / マッチャー拡張

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| actual | T (generic) | Yes | テスト対象の実際の値 | 任意の型を受け付ける |

### 入力データソース

テストコード内で`expect()`関数の引数として渡される任意の値

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| jestExpect | JestExpect | スナップショットマッチャー統合済みのexpect関数 |
| 各種型定義 | TypeScript types | AsymmetricMatchers, Matchers, MatcherContext等 |

### 出力先

テストランタイム環境（グローバルまたはモジュールインポート経由）

## 処理フロー

### 処理シーケンス

```
1. モジュール初期化
   └─ createJestExpect()関数の実行
2. expect.extend()呼び出し
   └─ スナップショットマッチャー4種の登録
      ├─ toMatchInlineSnapshot
      ├─ toMatchSnapshot
      ├─ toThrowErrorMatchingInlineSnapshot
      └─ toThrowErrorMatchingSnapshot
3. addSnapshotSerializer追加
   └─ expect.addSnapshotSerializer = addSerializer
4. jestExpectとしてキャスト・エクスポート
```

### フローチャート

```mermaid
flowchart TD
    A[モジュールロード] --> B[createJestExpect関数実行]
    B --> C[expect.extend呼び出し]
    C --> D[スナップショットマッチャー4種を登録]
    D --> E[addSnapshotSerializerメソッド追加]
    E --> F[JestExpect型にキャスト]
    F --> G[jestExpectをエクスポート]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | マッチャー拡張 | expect.extend()で追加されたマッチャーは全てのexpect()呼び出しで利用可能 | モジュール初期化完了後 |
| BR-02 | シリアライザー登録 | addSnapshotSerializerで登録されたシリアライザーはスナップショット生成時に使用される | スナップショットマッチャー使用時 |

### 計算ロジック

特になし

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

該当なし（インメモリ処理のみ）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | TypeError | 無効なシリアライザーの登録 | 正しいシリアライザーオブジェクトを渡す |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

モジュール初期化は一度のみ実行され、以降の`expect()`呼び出しは高速に処理される。

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

テスト環境での使用を前提としており、本番環境での使用は想定していない。

## 備考

- このパッケージは`expect`と`jest-snapshot`のブリッジとして機能する
- TypeScriptの型拡張を使用してMatcherStateにsnapshotStateを追加している

---

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

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

### 推奨読解順序

#### Step 1: 型定義を理解する

まず、JestExpect型の構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-expect/src/types.ts` | JestExpect型の定義、MatcherStateの拡張 |

**読解のコツ**: TypeScriptのモジュール拡張（declare module）構文に注目。`expect`モジュールのMatcherStateインターフェースにsnapshotStateを追加している。

**主要処理フロー**:
- **15-25行目**: JestExpect型の定義。BaseExpect、AsymmetricMatchersの組み合わせ
- **27-28行目**: JestMatchers型でMatchers<R, T>とSnapshotMatchers<R, T>を統合
- **45-54行目**: expectモジュールのMatcherState拡張でsnapshotStateを追加

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-expect/src/index.ts` | createJestExpect関数、エクスポート構造 |

**主要処理フロー**:
- **8行目**: expectパッケージからexpect関数をインポート
- **9-15行目**: jest-snapshotからスナップショットマッチャーをインポート
- **29-40行目**: createJestExpect関数でexpect.extend()を呼び出しマッチャーを登録
- **37行目**: addSnapshotSerializerメソッドを追加
- **42行目**: jestExpectとしてエクスポート

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

```
jestExpect (index.ts:42)
    │
    └─ createJestExpect() (index.ts:29-40)
           │
           ├─ expect.extend() (expectパッケージ)
           │      ├─ toMatchInlineSnapshot (jest-snapshot)
           │      ├─ toMatchSnapshot (jest-snapshot)
           │      ├─ toThrowErrorMatchingInlineSnapshot (jest-snapshot)
           │      └─ toThrowErrorMatchingSnapshot (jest-snapshot)
           │
           └─ addSerializer (jest-snapshot)
```

### データフロー図

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

expectパッケージ ───────▶ createJestExpect() ───────▶ jestExpect
                              │
jest-snapshotマッチャー ────┤
                              │
addSerializerメソッド ────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-expect/src/index.ts` | ソース | メインエントリーポイント、jestExpect生成 |
| types.ts | `packages/jest-expect/src/types.ts` | ソース | TypeScript型定義、モジュール拡張 |
| package.json | `packages/jest-expect/package.json` | 設定 | パッケージ依存関係定義 |
