# 画面設計書 12-Snapshot Testingページ

## 概要

本ドキュメントは、JestドキュメントサイトにおけるSnapshot Testingページの画面設計を定義する。このページはJestのスナップショットテスト機能の使い方を詳細に説明するガイドページである。

### 本画面の処理概要

Snapshot Testingページは、Jestのスナップショットテスト機能について包括的なガイダンスを提供する技術ドキュメントページである。UIコンポーネントの変更検出、スナップショットの更新方法、ベストプラクティスを解説する。

**業務上の目的・背景**：UIコンポーネントの意図しない変更を検出するためのスナップショットテスト機能は、Jestの重要な機能の一つである。開発者がこの機能を正しく理解し、効果的に活用できるよう、詳細なドキュメントを提供することで、テストの品質向上とバグの早期発見に貢献する。

**画面へのアクセス方法**：
1. ドキュメントサイトのナビゲーションメニューから「Docs」ドロップダウンを選択
2. サイドバーの「Guides」セクションから「Snapshot Testing」を選択
3. More Resourcesページの「Snapshot Testing」リンクから遷移

**主要な操作・処理内容**：
1. スナップショットテストの基本概念の理解：UIレンダリング結果をスナップショットとして保存し比較する仕組みの学習
2. toMatchSnapshot APIの使用方法の学習：基本的なスナップショットマッチャーの使い方
3. インラインスナップショットの理解：toMatchInlineSnapshotの使用方法
4. スナップショットの更新方法の確認：--updateSnapshotフラグの使い方
5. Property Matchersの活用：動的な値を含むオブジェクトのスナップショット取得方法
6. ベストプラクティスの習得：スナップショットテストの効果的な活用方法

**画面遷移**：
- 遷移元：More Resourcesページ、サイドバーナビゲーション、検索結果
- 遷移先：Timer Mocksページ、Configuration（snapshotSerializers）、Mock Functionsページ、TutorialReactNativeページ

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 16 | jest-snapshot | 主機能 | toMatchSnapshot、toMatchInlineSnapshotの使用方法 |
| 35 | pretty-format | 補助機能 | スナップショットの人間可読フォーマット処理 |
| 10 | expect | 補助機能 | スナップショットマッチャーの使用方法 |

## 画面種別

ドキュメント / ガイド

## URL/ルーティング

- URL: `/docs/snapshot-testing`
- ファイルパス: `docs/SnapshotTesting.md`

## 入出力項目

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

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | テキスト | "Snapshot Testing" |
| 2 | 導入文 | テキスト | スナップショットテストの概要説明 |
| 3 | Snapshot Testing with Jestセクション | コードブロック＋テキスト | 基本的な使用例 |
| 4 | Updating Snapshotsセクション | テキスト＋コマンド | スナップショット更新方法 |
| 5 | Interactive Snapshot Modeセクション | 画像＋テキスト | 対話的更新モードの説明 |
| 6 | Inline Snapshotsセクション | コードブロック＋テキスト | インラインスナップショットの使い方 |
| 7 | Property Matchersセクション | コードブロック＋テキスト | 動的値のマッチング方法 |
| 8 | Best Practicesセクション | 番号付きリスト | ベストプラクティス3項目 |
| 9 | FAQセクション | Q&A形式 | よくある質問と回答 |
| 10 | サイドバー | ナビゲーション | ドキュメント目次 |
| 11 | Prev/Nextナビゲーション | ボタン | 前後ページへの遷移リンク |

## イベント仕様

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

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

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

ユーザーが内部ドキュメントリンク（Configuration、Mock Functions等）をクリックすると、該当するドキュメントページに遷移する。

### 3-外部リンククリック

ユーザーがGitHub、npm、ブログ記事等の外部リンクをクリックすると、新しいタブで外部サイトが開く。

### 4-画像の表示

スナップショット更新の操作説明に使用される画像（GIF含む）が表示される。

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

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

## メッセージ仕様

該当なし

## 例外処理

| 例外状態 | 表示・動作 |
|---------|-----------|
| ページが見つからない | 404エラーページを表示 |
| 画像読み込み失敗 | 代替テキストを表示 |

## 備考

- Docusaurusフレームワークで自動生成されるページ
- Markdownファイル（docs/SnapshotTesting.md）から静的HTMLに変換
- コードブロックにはシンタックスハイライトが適用される
- 操作説明用のスクリーンショット・GIF画像を含む

---

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

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

### 推奨読解順序

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

スナップショットテストの内部データ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-snapshot/src/types.ts` | SnapshotState、Context等の型定義を確認 |
| 1-2 | State.ts | `packages/jest-snapshot/src/State.ts` | スナップショットの状態管理クラスを理解 |

**読解のコツ**: スナップショットはテストファイルと対になる.snapファイルに保存される。SnapshotStateクラスがこのファイルの読み書きを管理する。

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

スナップショットマッチャーの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-snapshot/src/index.ts` | toMatchSnapshot、toMatchInlineSnapshotの実装を確認 |

**主要処理フロー**:
1. **Line 157-200**: `toMatchSnapshot`関数の実装。propertiesまたはhint引数を受け取り、スナップショットとの比較を実行
2. **Line 48-51**: NOT_SNAPSHOT_MATCHERSエラーメッセージの定義（.notとの組み合わせ不可）
3. **Line 57-70**: スナップショット名の生成ロジック

#### Step 3: スナップショット保存処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | utils.ts | `packages/jest-snapshot/src/utils.ts` | serialize、deepMerge関数の実装 |
| 3-2 | InlineSnapshots.ts | `packages/jest-snapshot/src/InlineSnapshots.ts` | インラインスナップショットの書き込み処理 |

#### Step 4: pretty-formatとの連携を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | plugins.ts | `packages/jest-snapshot/src/plugins.ts` | シリアライザプラグインの管理 |
| 4-2 | printSnapshot.ts | `packages/jest-snapshot/src/printSnapshot.ts` | スナップショットの整形出力処理 |

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

```
expect(value).toMatchSnapshot()
    │
    ├─ packages/jest-snapshot/src/index.ts
    │      ├─ toMatchSnapshot() [Line 157]
    │      │      ├─ serialize() [utils.ts]
    │      │      ├─ SnapshotState.match() [State.ts]
    │      │      └─ printSnapshotAndReceived() [printSnapshot.ts]
    │      │
    │      └─ toMatchInlineSnapshot()
    │             └─ saveInlineSnapshots() [InlineSnapshots.ts]
    │
    └─ packages/pretty-format
           └─ format() - 値のシリアライズ
```

### データフロー図

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

テスト対象の値 ───▶ serialize() ───▶ スナップショット文字列
                        │
                        ▼
                  SnapshotState.match()
                        │
              ┌─────────┴─────────┐
              ▼                   ▼
         [一致]              [不一致]
              │                   │
              ▼                   ▼
         テスト成功           差分表示＋
                              テスト失敗
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| SnapshotTesting.md | `docs/SnapshotTesting.md` | ドキュメント | ページコンテンツ定義 |
| index.ts | `packages/jest-snapshot/src/index.ts` | ソース | スナップショットマッチャー実装 |
| State.ts | `packages/jest-snapshot/src/State.ts` | ソース | スナップショット状態管理 |
| utils.ts | `packages/jest-snapshot/src/utils.ts` | ソース | ユーティリティ関数 |
| InlineSnapshots.ts | `packages/jest-snapshot/src/InlineSnapshots.ts` | ソース | インラインスナップショット処理 |
| plugins.ts | `packages/jest-snapshot/src/plugins.ts` | ソース | シリアライザプラグイン |
| printSnapshot.ts | `packages/jest-snapshot/src/printSnapshot.ts` | ソース | スナップショット整形出力 |
| types.ts | `packages/jest-snapshot/src/types.ts` | ソース | 型定義 |
