# 画面設計書 17-Troubleshootingページ

## 概要

本ドキュメントは、JestドキュメントサイトにおけるTroubleshootingページの画面設計を定義する。このページはJest使用時によくある問題と解決策をまとめたFAQ/トラブルシューティングガイドページである。

### 本画面の処理概要

Troubleshootingページは、Jest使用時に発生しやすい一般的な問題とその解決方法を解説する技術ドキュメントページである。エラーメッセージ、設定の問題、パフォーマンス問題など、幅広いトラブルシューティング情報を提供する。

**業務上の目的・背景**：Jestは多くのプロジェクトで使用されており、環境やプロジェクト設定に起因するさまざまな問題が発生する。よくある問題と解決策を一元的にまとめることで、開発者の問題解決を迅速化し、サポートコストを削減する。

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

**主要な操作・処理内容**：
1. 問題カテゴリの確認：テスト失敗、設定エラー、パフォーマンス問題等
2. 解決策の適用：各問題に対する具体的な解決手順の実行
3. 追加リソースの参照：GitHubイシュー、Stack Overflow等への誘導
4. デバッグ方法の学習：--detectOpenHandles、--runInBand等のデバッグオプション

**画面遷移**：
- 遷移元：Webpackページ、More Resourcesページ、サイドバーナビゲーション、検索結果
- 遷移先：Configurationページ、CLI Referenceページ、JestObjectAPIページ

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 1 | jest | 主機能 | 全般的なトラブルシューティング |
| 5 | jest-cli | 補助機能 | デバッグオプションの使用 |

## 画面種別

ドキュメント / FAQ / トラブルシューティング

## URL/ルーティング

- URL: `/docs/troubleshooting`
- ファイルパス: `docs/Troubleshooting.md`

## 入出力項目

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

## 表示項目

| No | 項目名 | 表示形式 | 説明 |
|----|--------|----------|------|
| 1 | ページタイトル | テキスト | "Troubleshooting" |
| 2 | 導入文 | テキスト | トラブルシューティングの概要 |
| 3 | Tests are Failingセクション | コードブロック＋テキスト | テスト失敗時の対処法 |
| 4 | Debugging in VS Codeセクション | コードブロック＋テキスト | VS Codeでのデバッグ設定 |
| 5 | Debugging in WebStormセクション | テキスト | WebStormでのデバッグ方法 |
| 6 | Caching Issuesセクション | コードブロック＋テキスト | キャッシュ問題の解決 |
| 7 | Unresolved Promisesセクション | コードブロック＋テキスト | 未解決Promise問題 |
| 8 | Watchman Issuesセクション | コードブロック＋テキスト | Watchman関連の問題 |
| 9 | Coverage Issuesセクション | テキスト | カバレッジ問題の解決 |
| 10 | Still unresolved?セクション | テキスト＋リンク | 追加サポートリソース |
| 11 | サイドバー | ナビゲーション | ドキュメント目次 |
| 12 | Prev/Nextナビゲーション | ボタン | 前後ページへの遷移リンク |

## イベント仕様

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

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

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

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

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

ユーザーがGitHub Issues、Stack Overflow、Node.jsドキュメント等の外部リンクをクリックすると、新しいタブで外部サイトが開く。

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

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

## メッセージ仕様

該当なし

## 例外処理

| 例外状態 | 表示・動作 |
|---------|-----------|
| ページが見つからない | 404エラーページを表示 |

## 備考

- Docusaurusフレームワークで自動生成されるページ
- Markdownファイル（docs/Troubleshooting.md）から静的HTMLに変換
- コードブロックにはシンタックスハイライトが適用される
- 外部リソース（GitHub、Stack Overflow）への積極的な誘導を含む

---

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

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

### 推奨読解順序

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

トラブルシューティングに関連するCLIオプションと設定を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | args.ts | `packages/jest-cli/src/args.ts` | CLIオプション定義（--detectOpenHandles等）を確認 |

**読解のコツ**: トラブルシューティングで使用されるオプション（--detectOpenHandles、--runInBand、--clearCache等）の定義を確認することで、各オプションの目的と効果を理解できる。

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

デバッグ関連の機能実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-runner/src/index.ts` | テスト実行処理とデバッグモードを確認 |
| 2-2 | runJest.ts | `packages/jest-core/src/runJest.ts` | 全体の実行フローを確認 |

**主要処理フロー**:
1. **--runInBand**: 並列実行を無効化しシングルプロセスで実行
2. **--detectOpenHandles**: 未クローズのハンドルを検出して報告
3. **--clearCache**: Jestキャッシュをクリア
4. **--watchman=false**: Watchman無効化

#### Step 3: キャッシュ管理の詳細を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Runtime.ts | `packages/jest-runtime/src/index.ts` | モジュールキャッシュ管理 |
| 3-2 | ScriptTransformer.ts | `packages/@jest/transform/src/ScriptTransformer.ts` | 変換結果キャッシュ |

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

```
jest --detectOpenHandles
    │
    ├─ packages/jest-cli/src/cli/index.ts
    │      └─ parseArgs() [args.ts]
    │
    └─ packages/jest-core/src/runJest.ts
           └─ detectOpenHandles: true
                  └─ Node.js async_hooks API使用
                         └─ 未クローズハンドルの検出・報告

jest --clearCache
    │
    └─ packages/jest-cli/src/cli/index.ts
           └─ clearCache()
                  └─ キャッシュディレクトリ削除
```

### データフロー図

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

トラブル発生 ───▶ 症状の特定 ───▶ 該当セクション参照
                        │
      ┌─────────────────┼─────────────────┐
      ▼                 ▼                 ▼
 [テスト失敗]      [キャッシュ]       [非同期]
      │                 │                 │
      ▼                 ▼                 ▼
 --runInBand      --clearCache   --detectOpenHandles
      │                 │                 │
      └─────────────────┴─────────────────┘
                        │
                        ▼
                   問題解決
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Troubleshooting.md | `docs/Troubleshooting.md` | ドキュメント | ページコンテンツ定義 |
| args.ts | `packages/jest-cli/src/args.ts` | ソース | CLIオプション定義 |
| index.ts | `packages/jest-runner/src/index.ts` | ソース | テスト実行 |
| runJest.ts | `packages/jest-core/src/runJest.ts` | ソース | 実行フロー制御 |
| ScriptTransformer.ts | `packages/@jest/transform/src/ScriptTransformer.ts` | ソース | キャッシュ管理 |
