# 機能設計書 13-jest-matcher-utils

## 概要

本ドキュメントは、Jestテスティングフレームワークにおける`jest-matcher-utils`パッケージの機能設計を記述する。このパッケージは、マッチャーのエラーメッセージ生成と値の表示に使用されるユーティリティ関数群を提供する。

### 本機能の処理概要

**業務上の目的・背景**：テストが失敗した際、開発者が素早く問題を特定できるよう、分かりやすいエラーメッセージを表示することが重要である。`jest-matcher-utils`は、期待値と実際の値の差分表示、色分け、フォーマット処理を提供し、テスト失敗時のデバッグ効率を大幅に向上させる。

**機能の利用シーン**：マッチャーが失敗した際のエラーメッセージ生成、カスタムマッチャー開発時のメッセージフォーマット、テスト結果の視覚的表示において使用される。

**主要な処理内容**：
1. `matcherHint()` - マッチャー名のヒント表示（expect(received).toBe(expected)形式）
2. `printExpected()` / `printReceived()` - 期待値/実際値の色付き表示
3. `printDiffOrStringify()` - 差分表示または文字列化
4. `stringify()` - pretty-formatを使用した値の文字列化
5. `diff()` - jest-diffを使用した差分計算
6. `ensureNumbers()` / `ensureNoExpected()` - 入力値バリデーション
7. 色定数（EXPECTED_COLOR, RECEIVED_COLOR等）の提供

**関連システム・外部連携**：`jest-diff`（差分計算）、`pretty-format`（値のフォーマット）と連携する。

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 5 | Using Matchersページ | 参照画面 | マッチャーユーティリティの内部動作説明 |

## 機能種別

ユーティリティ関数 / フォーマット処理 / 差分表示

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| matcherName | string | Yes | マッチャー名（toBe等） | 文字列 |
| received | string | No | 実際の値のラベル | デフォルト'received' |
| expected | string | No | 期待値のラベル | デフォルト'expected' |
| options | MatcherHintOptions | No | 表示オプション | オブジェクト |

### 入力データソース

マッチャー関数からの引数として渡される

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| フォーマット済み文字列 | string | 色付きのエラーメッセージ |
| 差分結果 | string \| null | 差分表示文字列 |

### 出力先

コンソール出力（テストレポーター経由）

## 処理フロー

### 処理シーケンス

```
1. マッチャー失敗検出
2. matcherHint()でヒント文字列生成
3. printExpected()/printReceived()で値表示
4. printDiffOrStringify()で差分生成（必要に応じて）
5. matcherErrorMessage()でエラーメッセージ組み立て
6. 最終出力文字列を返却
```

### フローチャート

```mermaid
flowchart TD
    A[マッチャー失敗] --> B[matcherHint生成]
    B --> C[printExpected/printReceived]
    C --> D{差分表示必要?}
    D -->|Yes| E[printDiffOrStringify]
    D -->|No| F[stringify]
    E --> G[メッセージ組み立て]
    F --> G
    G --> H[フォーマット済み文字列返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 色付け規則 | 期待値は緑(EXPECTED_COLOR)、実際値は赤(RECEIVED_COLOR) | 常時 |
| BR-02 | 差分表示条件 | 文字列が複数行または同型オブジェクトの場合に差分表示 | isLineDiffable=true |
| BR-03 | 文字列長制限 | MAX_DIFF_STRING_LENGTH(20000)を超える場合は差分省略 | 長大文字列 |

### 計算ロジック

stringify: pretty-formatを使用し、maxDepth=10, maxWidth=10でフォーマット

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | Error | ensureActualIsNumber/ensureExpectedIsNumberで型不一致 | 適切な型の値を渡す |

### リトライ仕様

該当なし

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

該当なし

## パフォーマンス要件

stringify処理は再帰的な深さ制限により性能を確保。

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

特になし

## 備考

- chalkライブラリを使用した色付け処理
- 末尾空白の可視化（middle dot記号使用）

---

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

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

### 推奨読解順序

#### Step 1: 色定数とフォーマット設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-matcher-utils/src/index.ts` | 色定数、PLUGINS配列 |

**主要処理フロー**:
- **64-68行目**: 色定数定義（EXPECTED_COLOR=緑、RECEIVED_COLOR=赤等）
- **40-47行目**: pretty-formatプラグイン配列（React, DOM, Immutable対応）
- **70行目**: MULTILINE_REGEXP（改行検出用正規表現）

**読解のコツ**: Chalk型はchalkライブラリの色付け関数を表す。

#### Step 2: 基本フォーマット関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-matcher-utils/src/index.ts` | stringify, printExpected, printReceived |

**主要処理フロー**:
- **94-126行目**: stringify関数 - pretty-formatを使用した値の文字列化
- **128-129行目**: highlightTrailingWhitespace - 末尾空白の強調
- **133-134行目**: replaceTrailingSpaces - 末尾スペースをmiddle dotに置換
- **136-139行目**: printReceived/printExpected - 色付き値表示

#### Step 3: マッチャーヒント生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/jest-matcher-utils/src/index.ts` | matcherHint, matcherErrorMessage |

**主要処理フロー**:
- **524-587行目**: matcherHint関数 - expect(received).matcherName(expected)形式の生成
- **512-519行目**: matcherErrorMessage関数 - エラーメッセージ組み立て

#### Step 4: 差分表示処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | index.ts | `packages/jest-matcher-utils/src/index.ts` | printDiffOrStringify, diff |

**主要処理フロー**:
- **320-394行目**: printDiffOrStringify - 差分表示または文字列化の判断・実行
- **275-316行目**: isLineDiffable - 差分表示可能かの判定
- **487-491行目**: diff関数 - jest-diffラッパー

#### Step 5: バリデーション関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | index.ts | `packages/jest-matcher-utils/src/index.ts` | ensure系関数 |

**主要処理フロー**:
- **155-173行目**: ensureNoExpected - 引数なしマッチャーのチェック
- **178-194行目**: ensureActualIsNumber - 数値型チェック
- **220-228行目**: ensureNumbers - actual/expected両方の数値チェック

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

```
matcherHint (index.ts:524)
    │
    ├─ DIM_COLOR (dim表示)
    │
    ├─ receivedColor (引数色)
    │
    └─ expectedColor (引数色)

printDiffOrStringify (index.ts:320)
    │
    ├─ diffStringsUnified (jest-diff)
    │
    ├─ diffStringsRaw (jest-diff)
    │
    ├─ diffDefault (jest-diff)
    │
    └─ replaceMatchedToAsymmetricMatcher
           │
           └─ deepCyclicCopyReplaceable

stringify (index.ts:94)
    │
    └─ prettyFormat (pretty-format)
```

### データフロー図

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

期待値/実際値 ───────────▶ stringify() ──────────────▶ フォーマット済み文字列
                              │
                              ├── prettyFormat適用
                              │
                              └── 色付け適用

マッチャー情報 ───────────▶ matcherHint() ─────────────▶ ヒント文字列
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-matcher-utils/src/index.ts` | ソース | メイン実装、全関数のエクスポート |
| Replaceable.ts | `packages/jest-matcher-utils/src/Replaceable.ts` | ソース | 置換可能値のラッパークラス |
| deepCyclicCopyReplaceable.ts | `packages/jest-matcher-utils/src/deepCyclicCopyReplaceable.ts` | ソース | 循環参照対応のディープコピー |
