# 画面設計書 5-Using Matchersページ

## 概要

本ドキュメントは、JestドキュメントサイトのUsing Matchersページについて、画面構成、機能、データフロー、コードリーディングガイドを記述した画面設計書です。

### 本画面の処理概要

Using MatchersページはJestのマッチャー（アサーション）の使い方を体系的に説明するドキュメントページです。toBe、toEqual等の基本的なマッチャーから、真偽値、数値、文字列、配列、例外処理に至るまで、カテゴリ別に詳細なサンプルコードとともに解説します。

**業務上の目的・背景**：テストコードを書く際に、適切なマッチャーを選択することは品質の高いテストを作成するために重要です。このページでは、よく使用されるマッチャーをカテゴリ別に整理し、各マッチャーの使い分けを理解できるようにします。

**画面へのアクセス方法**：
- Getting Startedページからの「Using Matchers」リンクをクリック
- サイドバーナビゲーションから選択
- 直接URL `/docs/using-matchers` にアクセス

**主要な操作・処理内容**：
1. Common Matchersセクションで基本的なマッチャー（toBe、toEqual、not）の確認
2. Truthinessセクションで真偽値マッチャー（toBeNull、toBeUndefined等）の確認
3. Numbersセクションで数値マッチャー（toBeGreaterThan、toBeCloseTo等）の確認
4. Stringsセクションで文字列マッチャー（toMatch）の確認
5. Arrays and iterablesセクションで配列マッチャー（toContain）の確認
6. Exceptionsセクションで例外マッチャー（toThrow）の確認
7. サイドバーナビゲーションで他のドキュメントページへ遷移

**画面遷移**：
- 遷移先：Expect APIリファレンスページ、Testing Asynchronous Codeページ
- 遷移元：Getting Startedページ、他のドキュメントページ

**権限による表示制御**：なし（全ユーザーに同一コンテンツを表示）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 10 | expect | 主機能 | マッチャー（toBe、toEqual等）の使い方説明 |
| 13 | jest-matcher-utils | 補助機能 | マッチャーユーティリティの内部動作説明 |

## 画面種別

ドキュメントページ

## URL/ルーティング

- URL: `/docs/using-matchers`
- ルーティング: `docs/UsingMatchers.md`（Docusaurusによる自動変換）

## 入出力項目

該当なし（Markdownコンテンツの静的表示）

## 表示項目

| セクション | 表示内容 | データソース |
|------------|----------|--------------|
| タイトル | "Using Matchers" | Markdown Front Matter |
| 導入文 | マッチャーの概要説明 | 静的コンテンツ |
| Common Matchers | toBe、toEqual、notの使い方 | 静的コンテンツ |
| Truthiness | toBeNull、toBeUndefined、toBeTruthy、toBeFalsy | 静的コンテンツ |
| Numbers | toBeGreaterThan、toBeLessThan、toBeCloseTo等 | 静的コンテンツ |
| Strings | toMatchによる正規表現マッチング | 静的コンテンツ |
| Arrays and iterables | toContainによる配列要素チェック | 静的コンテンツ |
| Exceptions | toThrowによる例外チェック | 静的コンテンツ |
| And More | Expect APIリファレンスへの誘導 | 静的コンテンツ |
| サイドバー | ドキュメントナビゲーション | sidebars.json |

## イベント仕様

### 1-サイドバーナビゲーション

サイドバーのリンクをクリックすると、対応するドキュメントページへ遷移します。

### 2-内部リンククリック

| リンク名 | 遷移先 |
|----------|--------|
| expect API doc | /docs/expect-api（ExpectAPI.md） |
| test asynchronous code | /docs/asynchronous（TestingAsyncCode.md） |

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

該当なし（静的サイトのため、データベース操作は発生しない）

## メッセージ仕様

該当なし（フォーム入力や処理結果のメッセージは存在しない）

## 例外処理

該当なし（静的Markdownコンテンツのため、例外処理は不要）

## 備考

- Docusaurusによりdocs/UsingMatchers.mdから自動生成
- Front Matterのidが`using-matchers`のため、URLは`/docs/using-matchers`
- コードブロックにはJavaScriptのシンタックスハイライトが適用
- tipやcautionなどのアドモニションが使用されている

---

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

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

### 推奨読解順序

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

Markdownドキュメントの構造とFront Matterを把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | UsingMatchers.md | `docs/UsingMatchers.md` | Front Matter（id: using-matchers, title: Using Matchers） |

**読解のコツ**: ドキュメントは7つのセクション（Common Matchers、Truthiness、Numbers、Strings、Arrays and iterables、Exceptions、And More）で構成されています。

#### Step 2: セクション構造を理解する

各セクションで説明されているマッチャーを把握します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | UsingMatchers.md | `docs/UsingMatchers.md` | 各セクションの構造（1-179行） |

**主要セクション**:
- **8-48行目**: Common Matchers（toBe、toEqual、not）
- **50-83行目**: Truthiness（toBeNull、toBeUndefined、toBeTruthy、toBeFalsy）
- **84-110行目**: Numbers（toBeGreaterThan、toBeLessThan、toBeCloseTo等）
- **112-124行目**: Strings（toMatch）
- **126-143行目**: Arrays and iterables（toContain）
- **145-172行目**: Exceptions（toThrow）
- **174-179行目**: And More（リファレンスへの誘導）

#### Step 3: 関連パッケージを理解する

expectパッケージの構造を把握します（実装詳細の参照用）。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | expect | `packages/expect/src/index.ts` | expectの実装エントリーポイント |
| 3-2 | jest-matcher-utils | `packages/jest-matcher-utils/src/index.ts` | マッチャーユーティリティ |

**読解のコツ**: ドキュメントで説明されているマッチャーは、packages/expectで実装されています。実装の詳細を確認することで、マッチャーの動作を深く理解できます。

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

```
Docusaurus Build Process
    │
    ├─ docs/UsingMatchers.md
    │      │
    │      ├─ Front Matter解析
    │      │      └─ id: using-matchers → URL: /docs/using-matchers
    │      │
    │      ├─ Markdown → HTML変換
    │      │      ├─ Common Matchers セクション
    │      │      ├─ Truthiness セクション
    │      │      ├─ Numbers セクション
    │      │      ├─ Strings セクション
    │      │      ├─ Arrays and iterables セクション
    │      │      ├─ Exceptions セクション
    │      │      └─ And More セクション
    │      │
    │      └─ Admonitions処理
    │             └─ :::tip → アドモニションUI
    │
    └─ sidebars.json
           └─ サイドバーナビゲーション生成
```

### データフロー図

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

UsingMatchers.md ───────▶ Markdown Parser ────────▶ HTML コンテンツ
                                │
                                ├─ コードブロック処理
                                │      └─ シンタックスハイライト
                                │
                                └─ Admonitions処理
                                       └─ :::tip → UI変換

sidebars.json ──────────▶ Sidebar Generator ──────▶ サイドバーUI
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| UsingMatchers.md | `docs/UsingMatchers.md` | ドキュメント | Using Matchersページのコンテンツ |
| sidebars.json | `website/sidebars.json` | 設定 | サイドバーナビゲーション定義 |
| docusaurus.config.js | `website/docusaurus.config.js` | 設定 | Docusaurus全体設定 |
| ExpectAPI.md | `docs/ExpectAPI.md` | ドキュメント | Expect APIリファレンス（参照先） |
| TestingAsyncCode.md | `docs/TestingAsyncCode.md` | ドキュメント | 非同期テストドキュメント（遷移先） |
| expect (package) | `packages/expect/` | ソース | マッチャー実装パッケージ |
| jest-matcher-utils (package) | `packages/jest-matcher-utils/` | ソース | マッチャーユーティリティパッケージ |
