# 通知設計書 18-コンソールログ出力

## 概要

本ドキュメントは、Jestテストフレームワークにおけるコンソールログ出力機能の設計について記載する。jest-consoleパッケージのBufferedConsoleおよびCustomConsoleクラスによって実装され、テスト内でconsole.log/warn/error/info/debug等を使用した場合の出力をバッファリングして表示する。

### 本通知の処理概要

**業務上の目的・背景**：テスト実行中にconsole.log等のコンソール出力が発生した場合、そのままリアルタイムで出力するとテスト結果の表示が乱れる。BufferedConsoleを使用することで、テスト実行中のコンソール出力をバッファリングし、テスト完了後にまとめて表示することで、出力の可読性を向上させる。また、出力元のスタックトレースも記録され、どのテストからの出力かを特定できる。

**通知の送信タイミング**：テスト内でconsole.log/warn/error/info/debug/assert等が呼び出された時点でバッファに記録され、テスト結果の表示時（DefaultReporter等）にまとめて出力される。

**通知の受信者**：コンソールを監視している開発者。テスト結果とともにコンソール出力を確認できる。

**通知内容の概要**：各console呼び出しについて、出力タイプ（console.log, console.warn等）、メッセージ内容、および出力元のスタックトレースが表示される。warnは黄色、errorは赤色で色分けされる。

**期待されるアクション**：開発者はデバッグ用のconsole.log等を確認し、テストの動作を理解する。不要なconsole出力がある場合は削除を検討する。

## 通知種別

コンソール出力（標準出力）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | バッファリング後に同期出力 |
| 優先度 | 低 |
| リトライ | なし |

### 送信先決定ロジック

BufferedConsoleでバッファリングされた出力は、getConsoleOutput関数によってフォーマットされ、各Reporterから出力される。

## 通知テンプレート

### コンソール出力形式

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| 形式 | テキスト（ANSIカラーコード付き） |

### 本文テンプレート

```
    console.{type}
      {メッセージ}
      {スタックトレース}
```

### 出力タイプと色分け

| タイプ | 表示 | 色 |
|-------|------|-----|
| log | console.log | 薄暗い（dim） |
| info | console.info | 薄暗い（dim） |
| debug | console.debug | 薄暗い（dim） |
| warn | console.warn | 黄色 |
| error | console.error | 赤色 |
| assert | console.assert | デフォルト |

### 添付ファイル

なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| type | console出力タイプ | LogEntry.type | Yes |
| message | 出力メッセージ | LogEntry.message | Yes |
| origin | 出力元スタックトレース | LogEntry.origin | Yes |
| buffer | コンソールバッファ | ConsoleBuffer | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| テスト内コンソール呼び出し | console.log等の呼び出し | BufferedConsole使用時 | バッファに記録される |
| テスト結果表示時 | onTestResult | バッファに内容がある場合 | getConsoleOutputで整形して出力 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| バッファが空 | console呼び出しがない場合 |
| silentモード | 一部のReporterでsilentオプションが有効な場合 |

## 処理フロー

### バッファリングフロー

```mermaid
flowchart TD
    A[テスト内console.log呼び出し] --> B[BufferedConsole._log]
    B --> C[ErrorWithStackでスタック取得]
    C --> D[originの抽出]
    D --> E[_buffer.push]
    E --> F[LogEntry作成]
    F --> G[バッファに保存]
```

### 出力フロー

```mermaid
flowchart TD
    A[テスト完了] --> B[Reporter.onTestResult]
    B --> C{buffer存在?}
    C -->|No| Z[終了]
    C -->|Yes| D[getConsoleOutput]
    D --> E[buffer.reduce]
    E --> F{typeチェック}
    F -->|warn| G[chalk.yellow]
    F -->|error| H[chalk.red]
    F -->|その他| I[デフォルト]
    G --> J[メッセージ整形]
    H --> J
    I --> J
    J --> K[formatStackTrace]
    K --> L[出力文字列構築]
    L --> M[this.log]
    M --> Z
```

## データベース参照・更新仕様

### 参照テーブル一覧

本機能はデータベースを使用しない。

### テーブル別参照項目詳細

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| スタックトレース取得失敗 | ErrorWithStackがundefinedを返す場合 | invariantでアサート |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし

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

- テスト内でconsole.logに機密情報を出力すると、テスト結果に含まれる
- CI/CD環境でのログ保持に注意

## 備考

- BufferedConsoleはテスト環境で使用、CustomConsoleは直接出力用
- グループ機能（console.group/groupEnd）をサポート
- タイマー機能（console.time/timeEnd/timeLog）をサポート
- カウンター機能（console.count/countReset）をサポート
- verboseモードでインデントが調整される

---

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

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

### 推奨読解順序

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

コンソールログで扱うデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-console/src/types.ts` | L8-14: LogEntry型（message, origin, type） |
| 1-2 | types.ts | `packages/jest-console/src/types.ts` | L24-36: LogType（assert, count, debug, ...） |
| 1-3 | types.ts | `packages/jest-console/src/types.ts` | L38: ConsoleBuffer = Array<LogEntry> |

**読解のコツ**: LogEntryはmessage（出力内容）、origin（スタックトレース）、type（console.logの種類）を持つ。

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

バッファリング処理の実装を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L21-37: クラス定義とコンストラクタ |
| 2-2 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L39-63: write静的メソッド |
| 2-3 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L65-72: _logメソッド |

**主要処理フロー**:
- **L21-22**: _buffer, _counters, _timers, _groupDepthのメンバー変数
- **L46-48**: ErrorWithStackでスタックトレース取得
- **L50-54**: スタックから出力元（origin）を抽出
- **L56-62**: LogEntryを_bufferにpush

#### Step 3: 各console.xxxメソッドの実装

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L98-100: debugメソッド |
| 3-2 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L111-113: errorメソッド |
| 3-3 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L137-139: infoメソッド |
| 3-4 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L141-143: logメソッド |
| 3-5 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L174-176: warnメソッド |

**主要処理フロー**:
- 各メソッドはformat()でメッセージを整形し、_log()を呼び出す
- _log()は_groupDepthに応じたインデントを追加してwrite()を呼び出す

#### Step 4: 出力の整形処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | getConsoleOutput.ts | `packages/jest-console/src/getConsoleOutput.ts` | L17-61: getConsoleOutput関数 |

**主要処理フロー**:
- **L22-24**: verboseモードに応じたインデント設定
- **L26-46**: buffer.reduceでログエントリを整形
- **L27-30**: メッセージに行単位のインデント追加
- **L36-46**: type（warn/error）に応じた色分け
- **L53-57**: formatStackTraceでスタックトレース整形

#### Step 5: getBuffer()でバッファ取得

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | L178-180: getBufferメソッド |

**主要処理フロー**:
- **L179**: バッファが空ならundefined、そうでなければ_bufferを返す

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

```
テスト内 console.log()
    │
    ▼
BufferedConsole.log (L141)
    │
    └─ _log (L65)
           │
           └─ BufferedConsole.write [static] (L39)
                  │
                  ├─ ErrorWithStack (L46)
                  │
                  └─ buffer.push (L56-61)
                         │
                         └─ LogEntry {message, origin, type}

─────────────────────────────────────────

テスト完了後
    │
    ▼
Reporter.onTestResult
    │
    └─ BufferedConsole.getBuffer (L178)
           │
           ▼
    getConsoleOutput (L17)
           │
           ├─ buffer.reduce (L26)
           │      │
           │      ├─ メッセージ整形 (L27-30)
           │      │
           │      ├─ 色分け (L36-46)
           │      │
           │      └─ formatStackTrace (L53)
           │
           └─ 出力文字列を返す
```

### データフロー図

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

console.log("msg")
    │
    ▼
BufferedConsole.log
    │
    ▼
format("msg")
    │
    ▼
_log("log", msg)
    │
    ▼
BufferedConsole.write ────▶ _buffer配列に追加
    │
    │ LogEntry {
    │   type: "log",
    │   message: "msg",
    │   origin: "at xxx:nn"
    │ }
    │
    ▼
getBuffer() ─────────────▶ ConsoleBuffer | undefined

─────────────────────────────────────────

ConsoleBuffer ──────────▶ getConsoleOutput
                               │
                               ▼
                         buffer.reduce
                               │
                               ├─ TITLE_INDENT + console.{type}
                               │
                               ├─ CONSOLE_INDENT + message
                               │
                               └─ formatStackTrace(origin)
                                       │
                                       ▼
                                    stdout
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BufferedConsole.ts | `packages/jest-console/src/BufferedConsole.ts` | ソース | バッファリングコンソール実装 |
| CustomConsole.ts | `packages/jest-console/src/CustomConsole.ts` | ソース | 直接出力コンソール実装 |
| getConsoleOutput.ts | `packages/jest-console/src/getConsoleOutput.ts` | ソース | 出力整形関数 |
| types.ts | `packages/jest-console/src/types.ts` | 型定義 | LogEntry, LogType, ConsoleBuffer |
| jest-util | `packages/jest-util/` | パッケージ | ErrorWithStack, formatTime |
| jest-message-util | `packages/jest-message-util/` | パッケージ | formatStackTrace |
