# 機能設計書 23-@jest/console

## 概要

本ドキュメントは、Jestのコンソール出力キャプチャ・整形機能（@jest/console）の機能設計を記述する。このパッケージは、テスト実行中のconsole.log等の出力をキャプチャし、テスト結果と共に表示するための機能を提供する。

### 本機能の処理概要

@jest/consoleは、テスト実行中に発生するコンソール出力（console.log、console.error等）をキャプチャし、整形してレポーターに渡すための機能を提供するパッケージである。Node.jsの標準Consoleクラスを拡張した複数のコンソール実装を提供する。

**業務上の目的・背景**：テスト実行中のconsole出力は、デバッグや動作確認において重要な情報源である。しかし、複数のテストが並列実行される環境では、出力がどのテストから発生したかを追跡することが困難になる。@jest/consoleは、各テストのコンソール出力をバッファリングし、発生元のスタックトレースと共に記録することで、この問題を解決する。

**機能の利用シーン**：
- テスト実行中のconsole.log/warn/errorの出力キャプチャ
- テスト結果レポートでのコンソール出力表示
- デバッグ目的でのログ出力の追跡
- テスト中の出力を完全に抑制（NullConsole）

**主要な処理内容**：
1. BufferedConsole: コンソール出力をバッファに蓄積し、後で取得可能にする
2. CustomConsole: カスタムストリームへの出力と整形をサポート
3. NullConsole: 全ての出力を抑制するnullオブジェクトパターン
4. getConsoleOutput: バッファリングされた出力を整形してレポート用文字列に変換

**関連システム・外部連携**：
- jest-message-util: スタックトレースの整形
- jest-util: 時間フォーマット、行クリア等のユーティリティ
- @jest/reporters: コンソール出力の表示

**権限による制御**：この機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 本パッケージは画面と直接関連しない内部機能 |

## 機能種別

ログ出力 / キャプチャ処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| stdout | WriteStream | Yes (CustomConsole) | 標準出力ストリーム | - |
| stderr | WriteStream | Yes (CustomConsole) | 標準エラーストリーム | - |
| formatBuffer | Formatter | No | 出力整形関数 | - |

### 入力データソース

- console.log/warn/error等のコンソールメソッド呼び出し
- テストコード内でのconsole出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ConsoleBuffer | Array<LogEntry> | バッファリングされたログエントリの配列 |
| LogEntry.message | string | ログメッセージ内容 |
| LogEntry.origin | string | 発生元スタックトレース |
| LogEntry.type | LogType | ログの種類（log/warn/error等） |

### 出力先

- BufferedConsole: 内部バッファ（getBuffer()で取得）
- CustomConsole: 指定されたstdout/stderrストリーム
- NullConsole: 出力なし（全て抑制）

## 処理フロー

### 処理シーケンス

```
1. テスト環境でConsoleインスタンスを設定
   └─ BufferedConsole: バッファリング用
   └─ CustomConsole: 直接出力用
   └─ NullConsole: 出力抑制用

2. テストコードからconsole.log()等を呼び出し
   └─ 引数をutil.format()で文字列化
   └─ グループインデントを適用

3. BufferedConsoleの場合
   └─ スタックトレースから発生元を抽出
   └─ LogEntryとしてバッファに追加

4. CustomConsoleの場合
   └─ formatBuffer関数で整形
   └─ stdout/stderrに出力

5. テスト完了後
   └─ getBuffer()でバッファ取得
   └─ getConsoleOutput()で整形
   └─ レポーターで表示
```

### フローチャート

```mermaid
flowchart TD
    A[console.log呼び出し] --> B{Console種別}
    B -->|BufferedConsole| C[スタックトレース取得]
    C --> D[バッファに追加]
    D --> E[getBuffer取得]
    E --> F[getConsoleOutput整形]
    F --> G[レポーターで表示]

    B -->|CustomConsole| H[formatBuffer適用]
    H --> I[stdout/stderrに出力]

    B -->|NullConsole| J[何もしない]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-23-01 | グループインデント | group()/groupCollapsed()呼び出しごとにインデントが深くなる | 常時 |
| BR-23-02 | タイマー計測 | time()で開始、timeEnd()で経過時間を出力 | time系メソッド使用時 |
| BR-23-03 | カウンター | count()呼び出しごとにラベル別カウントをインクリメント | count()使用時 |
| BR-23-04 | warn/errorの色分け | warnは黄色、errorは赤色で出力 | getConsoleOutput使用時 |

### 計算ロジック

- 経過時間計算: `timeEnd()`呼び出し時刻 - `time()`呼び出し時刻

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

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

データベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | AssertionError | console.assert()で条件がfalseの場合 | アサーションメッセージをログ出力 |

### リトライ仕様

リトライ処理は存在しない。

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

トランザクション処理は存在しない。

## パフォーマンス要件

- バッファリングはメモリ上で行われるため、大量のログ出力時はメモリ使用量に注意
- スタックトレース取得のオーバーヘッドがあるが、デバッグ情報として有用

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

特になし。テスト実行中のローカル処理のため、セキュリティリスクは低い。

## 備考

- BufferedConsoleは主にテスト環境で使用され、テスト結果と共にログを表示する
- NullConsoleは--silentオプション使用時やログ抑制が必要な場合に使用される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-console/src/types.ts` | LogEntry, LogType, ConsoleBufferの型定義 |

**読解のコツ**: LogTypeはコンソールメソッドの種類（log/warn/error/debug等）を表す。LogEntryはメッセージ、発生元、種類を含む。ConsoleBufferはLogEntryの配列である。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-console/src/index.ts` | エクスポートされるクラスと関数 |

**主要処理フロー**:
- **8行目**: BufferedConsoleのエクスポート
- **9行目**: CustomConsoleのエクスポート
- **10行目**: NullConsoleのエクスポート
- **11行目**: getConsoleOutputのエクスポート

#### Step 3: BufferedConsoleを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | バッファリングコンソールの実装 |

**主要処理フロー**:
- **21-27行目**: クラス定義とプロパティ（_buffer, _counters, _timers, _groupDepth）
- **29-37行目**: コンストラクタ - 親クラスConsoleへのストリーム設定
- **39-63行目**: write()静的メソッド - スタックトレース取得とバッファへの追加
- **65-72行目**: _log()メソッド - インデント適用とバッファ追加
- **74-84行目**: assert() - アサーション失敗時のログ出力
- **145-151行目**: time() - タイマー開始
- **153-162行目**: timeEnd() - タイマー終了と経過時間出力
- **178-180行目**: getBuffer() - バッファの取得

#### Step 4: CustomConsoleを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | CustomConsole.ts | `packages/jest-console/src/CustomConsole.ts` | カスタムストリーム出力 |

**主要処理フロー**:
- **28-37行目**: コンストラクタ - stdout/stderr/formatBufferの設定
- **39-44行目**: _log() - stdoutへの出力
- **46-51行目**: _logError() - stderrへの出力
- **90-92行目**: error() - エラー出力（_logError使用）
- **153-155行目**: warn() - 警告出力（_logError使用）

#### Step 5: 出力整形を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | getConsoleOutput.ts | `packages/jest-console/src/getConsoleOutput.ts` | バッファ出力の整形 |

**主要処理フロー**:
- **17-21行目**: 関数シグネチャ - buffer, config, globalConfigを受け取る
- **22-24行目**: インデント設定（verboseモードで異なる）
- **26-58行目**: ログエントリのreduce処理 - 色付け、スタックトレース整形
- **36-46行目**: warn/errorの色分け処理

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

```
@jest/environment (テスト環境)
    │
    └─ @jest/console
           │
           ├─ BufferedConsole (Console拡張)
           │      ├─ log/warn/error/debug/info
           │      ├─ time/timeEnd/timeLog
           │      ├─ count/countReset
           │      ├─ group/groupCollapsed/groupEnd
           │      └─ getBuffer() → ConsoleBuffer
           │
           ├─ CustomConsole (Console拡張)
           │      └─ 同上メソッド → stdout/stderr出力
           │
           ├─ NullConsole (CustomConsole拡張)
           │      └─ 全メソッド空実装
           │
           └─ getConsoleOutput()
                  └─ ConsoleBuffer → 整形済み文字列
```

### データフロー図

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

console.log() ─────────▶ BufferedConsole ─────────▶ ConsoleBuffer
console.warn()                  │                         │
console.error()                 │                         ▼
    │                           │               getConsoleOutput()
    │                           │                         │
    │                           │                         ▼
    │                     CustomConsole ────────▶ stdout/stderr
    │                           │
    │                           │
    └──────────────────▶ NullConsole ─────────▶ (出力なし)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-console/src/index.ts` | ソース | パッケージエントリーポイント |
| types.ts | `packages/jest-console/src/types.ts` | ソース | 型定義 |
| BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | ソース | バッファリングコンソール |
| CustomConsole.ts | `packages/jest-console/src/CustomConsole.ts` | ソース | カスタムストリームコンソール |
| NullConsole.ts | `packages/jest-console/src/NullConsole.ts` | ソース | 出力抑制コンソール |
| getConsoleOutput.ts | `packages/jest-console/src/getConsoleOutput.ts` | ソース | 出力整形関数 |
| package.json | `packages/jest-console/package.json` | 設定 | パッケージ定義 |
