# 画面設計書 23-CLIページ

## 概要

本ドキュメントは、Jestドキュメントサイトにおける「CLIページ」の画面設計書です。Jestコマンドラインインターフェースの全オプションを詳細に解説し、テスト実行の柔軟な制御方法を提供します。

### 本画面の処理概要

**業務上の目的・背景**：CLIページは、Jestコマンドラインランナーの包括的なリファレンスを提供します。開発者はCLIオプションを理解することで、テストの実行方法（特定ファイル実行、ウォッチモード、カバレッジ収集など）を柔軟に制御できます。CI/CD環境での自動テスト、ローカル開発でのインタラクティブテスト、デバッグなど、様々なユースケースに対応するためのオプションが網羅されています。

**画面へのアクセス方法**：ユーザーはヘッダーナビゲーションの「API」リンクからAPI Referenceにアクセスし、サイドバーから「CLI Options」を選択します。Configurationページの「次へ」リンクから遷移することも可能です。URLは `/docs/cli` です。

**主要な操作・処理内容**：
1. コマンドライン実行方法の確認（jest、npm test経由等）
2. テストフィルタリングオプションの確認（--testPathPatterns、--testNamePattern等）
3. カバレッジ関連オプションの確認（--coverage、--coverageDirectory等）
4. ウォッチモードオプションの確認（--watch、--watchAll等）
5. デバッグ・診断オプションの確認（--detectOpenHandles、--debug等）
6. CI/CD関連オプションの確認（--ci、--json等）

**画面遷移**：Configurationページから遷移可能。API Referenceセクションの最後のページとして、次のセクション（Guidesなど）へ遷移可能。

**権限による表示制御**：特になし。すべてのユーザーが全コンテンツにアクセス可能。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 2 | jest-cli | 主機能 | コマンドラインオプションの詳細説明 |
| 5 | jest-config | 補助機能 | CLI経由での設定オプション指定方法 |

## 画面種別

詳細（ドキュメント参照）

## URL/ルーティング

- URL: `/docs/cli`
- ファイルパス: `docs/CLI.md`
- Docusaurusによる静的サイト生成

## 入出力項目

本画面は静的ドキュメントページのため、主要な入力項目はありません。

| 項目名 | 種別 | 説明 |
|--------|------|------|
| 検索クエリ | 入力（オプション） | サイト内検索機能で使用 |
| コードブロック | 出力 | コピー可能なCLIコマンド例 |
| 目次（TOC） | 出力 | ページ内ナビゲーション（CLIオプション一覧） |

## 表示項目

| セクション | 表示内容 | 備考 |
|------------|----------|------|
| Running from the command line | 基本的な実行方法（jest、パターン指定、変更ファイルのみ等） | 基本コマンド例 |
| Using with package manager | npm/yarn経由での実行方法 | npm test -- オプション形式 |
| Camelcase & dashed args support | キャメルケースとダッシュ形式の両方対応 | --collectCoverage = --collect-coverage |
| --bail | テスト失敗時の中断設定 | エイリアス: -b |
| --cache | キャッシュ使用設定 | デフォルト: true |
| --changedFilesWithAncestor | 変更ファイル関連テスト実行 | git/hg連携 |
| --changedSince | 指定ブランチからの変更テスト | git/hg連携 |
| --ci | CI環境モード | スナップショット自動更新無効 |
| --clearCache | キャッシュクリア | --showConfigでディレクトリ確認可能 |
| --clearMocks | モック自動クリア | jest.clearAllMocks()相当 |
| --collectCoverageFrom | カバレッジ対象指定 | globパターン |
| --colors | カラー出力強制 | FORCE_COLOR環境変数も対応 |
| --config | 設定ファイル指定 | エイリアス: -c |
| --coverage | カバレッジ収集 | --collectCoverageエイリアス |
| --coverageDirectory | カバレッジ出力先 | パス指定 |
| --coverageProvider | カバレッジプロバイダー | babel/v8 |
| --debug | デバッグ情報出力 | 設定内容確認用 |
| --detectOpenHandles | オープンハンドル検出 | --runInBand暗黙適用 |
| --env | テスト環境指定 | jsdom/node等 |
| --errorOnDeprecated | 非推奨APIでエラー | アップグレード支援 |
| --expand | 差分全表示 | エイリアス: -e |
| --filter | テストフィルタリング | カスタムフィルタモジュール |
| --findRelatedTests | 関連テスト検索 | ファイルリスト指定 |
| --forceExit | 強制終了 | リソースクリーンアップ問題時 |
| --help | ヘルプ表示 | - |
| --ignoreProjects | プロジェクト除外 | displayName指定 |
| --injectGlobals | グローバル注入 | false時は@jest/globalsからimport |
| --json | JSON出力 | 他出力はstderrへ |
| --lastCommit | 最終コミット関連テスト | git/hg連携 |
| --listTests | テストリスト出力 | 実行せず終了 |
| --logHeapUsage | ヒープ使用量ログ | メモリリークデバッグ用 |
| --maxConcurrency | 最大同時実行数 | test.concurrent用 |
| --maxWorkers | 最大ワーカー数 | エイリアス: -w |
| --noStackTrace | スタックトレース非表示 | - |
| --notify | 通知有効化 | node-notifier必要 |
| --onlyChanged | 変更関連テストのみ | エイリアス: -o |
| --onlyFailures | 失敗テストのみ | エイリアス: -f |
| --openHandlesTimeout | ハンドル警告タイムアウト | デフォルト: 1000ms |
| --outputFile | 出力ファイル指定 | --json併用 |
| --passWithNoTests | テストなしで成功 | - |
| --projects | プロジェクト指定 | パス配列 |
| --randomize | テスト順序ランダム化 | --seed連携 |
| --reporters | レポーター指定 | 複数指定可能 |
| --resetMocks | モック自動リセット | jest.resetAllMocks()相当 |
| --restoreMocks | モック自動リストア | jest.restoreAllMocks()相当 |
| --roots | ルートディレクトリ | パス配列 |
| --runInBand | シリアル実行 | エイリアス: -i |
| --runTestsByPath | パス直接指定実行 | 正規表現変換なし |
| --seed | シード値指定 | ランダム化用 |
| --selectProjects | プロジェクト選択 | displayName指定 |
| --setupFilesAfterEnv | セットアップファイル | パス配列 |
| --shard | シャード指定 | shardIndex/shardCount |
| --showConfig | 設定表示 | - |
| --showSeed | シード値表示 | - |
| --silent | コンソール出力抑制 | - |
| --testEnvironmentOptions | 環境オプション | JSON文字列 |
| --testLocationInResults | 位置情報追加 | レポーター用 |
| --testMatch | テストマッチパターン | glob配列 |
| --testNamePattern | テスト名パターン | エイリアス: -t |
| --testPathIgnorePatterns | パス除外パターン | 正規表現 |
| --testPathPatterns | パスパターン | 正規表現 |
| --testRunner | テストランナー | カスタムランナー |
| --testSequencer | テストシーケンサー | カスタムシーケンサー |
| --testTimeout | タイムアウト | デフォルト: 5000ms |
| --updateSnapshot | スナップショット更新 | エイリアス: -u |
| --useStderr | stderr出力 | - |
| --verbose | 詳細出力 | - |
| --version | バージョン表示 | エイリアス: -v |
| --waitForUnhandledRejections | 未処理rejection待機 | - |
| --watch | ウォッチモード | 変更関連テスト |
| --watchAll | 全ウォッチモード | 全テスト再実行 |
| --watchman | watchman使用 | デフォルト: true |
| --workerThreads | ワーカースレッド | 実験的機能 |

## イベント仕様

### 1-目次クリック

ページ内の該当CLIオプションセクションへスクロール移動

### 2-コードブロックコピー

CLIコマンド例をクリップボードにコピー

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

他のドキュメントページへ遷移

### 4-前へ/次へリンク

Configurationページまたは次セクションへ遷移

### 5-内部リンク（Configuration参照等）

Configurationページの該当オプションへ遷移

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

### 操作別データベース影響一覧

本画面は静的ドキュメントページのため、データベース操作は発生しません。

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| - | - | - | 静的コンテンツのみ |

## メッセージ仕様

| メッセージID | メッセージ内容 | 表示条件 | 種別 |
|-------------|--------------|----------|------|
| - | - | - | 静的コンテンツのため該当なし |

## 例外処理

| 例外状況 | 対応内容 |
|----------|----------|
| ページが見つからない | Docusaurus標準の404ページを表示 |
| ネットワークエラー | ブラウザ標準のエラー表示 |

## 備考

- CLIオプションはConfigurationオプションより優先される
- キャメルケースとダッシュ形式の両方がサポートされている（--collectCoverage = --collect-coverage）
- `npm test -- オプション`形式でpackage manager経由でも利用可能
- --watchと--watchAllはCIで自動的に無効化される
- --detectOpenHandlesは--runInBandを暗黙的に有効化する

---

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

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

### 推奨読解順序

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

まず、CLIオプションの型定義を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Config.ts | `packages/@jest/types/src/Config.ts` | Argv型の定義を確認 |
| 1-2 | args.ts | `packages/jest-cli/src/args.ts` | optionsオブジェクトの定義（100行目以降） |

**読解のコツ**: args.tsのoptionsオブジェクトが各CLIオプションの定義元です。

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

CLIの実行フローを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-cli/src/index.ts` | run、buildArgvのエクスポート（8-9行目） |
| 2-2 | run.ts | `packages/jest-cli/src/run.ts` | run関数とbuildArgv関数（20-79行目） |

**主要処理フロー**:
1. **20-42行目**: `run`関数 - CLI実行のメインエントリーポイント
2. **44-79行目**: `buildArgv`関数 - コマンドライン引数のパースと検証
3. **81-102行目**: `getProjectListFromCLIArgs`関数 - プロジェクトパスの取得

#### Step 3: 引数検証を理解する

CLIオプションの検証ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | args.ts | `packages/jest-cli/src/args.ts` | check関数（12-93行目） |

**主要処理フロー**:
- **14-20行目**: --runInBandと--maxWorkersの排他チェック
- **22-35行目**: --onlyChangedと--watchAllの排他チェック
- **37-41行目**: --onlyFailuresと--watchAllの排他チェック
- **43-49行目**: --findRelatedTestsの引数チェック

#### Step 4: CLIオプション定義を理解する

各オプションの詳細定義を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | args.ts | `packages/jest-cli/src/args.ts` | options定義（100-300行目） |

**主要処理フロー**:
- 各オプションのdescription、type、alias、requiresArg等の定義
- yargsのOptions型に準拠

#### Step 5: テスト結果処理を理解する

テスト実行結果の処理と終了コードを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | run.ts | `packages/jest-cli/src/run.ts` | readResultsAndExit関数（104-148行目） |

**主要処理フロー**:
- **104-115行目**: 終了コードの決定
- **117-127行目**: --forceExit時の処理
- **128-147行目**: オープンハンドル警告の表示

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

```
jest (コマンド)
    │
    ├─ jest-cli/run
    │      ├─ buildArgv
    │      │      ├─ yargs (引数パース)
    │      │      └─ jest-validate/validateCLIOptions
    │      │
    │      ├─ getProjectListFromCLIArgs
    │      │
    │      └─ @jest/core/runCLI
    │             ├─ jest-config/readConfigs
    │             └─ テスト実行
    │
    └─ readResultsAndExit
           ├─ 終了コード設定
           └─ forceExit/オープンハンドル警告
```

### データフロー図

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

コマンドライン引数  ───▶ buildArgv       ───▶ Config.Argv
                          ├─ yargs
                          └─ validateCLIOptions
                                │
                                ▼
                          getProjectListFromCLIArgs
                                │
                                ▼
                          @jest/core/runCLI
                                │
                                ▼
                          readResultsAndExit ───▶ 終了コード
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| CLI.md | `docs/CLI.md` | ドキュメント | CLIページのソースファイル |
| index.ts | `packages/jest-cli/src/index.ts` | ソース | CLIエクスポート |
| run.ts | `packages/jest-cli/src/run.ts` | ソース | CLI実行ロジック |
| args.ts | `packages/jest-cli/src/args.ts` | ソース | CLIオプション定義と検証 |
| index.ts | `packages/@jest/core/src/index.ts` | ソース | テスト実行コア |
| runCLI.ts | `packages/@jest/core/src/cli/index.ts` | ソース | CLI実行エントリーポイント |
| Config.ts | `packages/@jest/types/src/Config.ts` | ソース | 設定型定義（Argv含む） |
| bin/jest.js | `packages/jest-cli/bin/jest.js` | ソース | jestコマンドのエントリーポイント |
