# 通知設計書 3-テスト実行開始通知

## 概要

本ドキュメントは、Jestテストフレームワークにおけるコンソール出力機能のうち、テスト実行開始時にコンソールへ出力される「テスト実行開始通知」の設計を記載する。

### 本通知の処理概要

テスト実行開始通知は、Jestのテスト実行が開始された際にコンソールへ実行予定のテスト情報を出力する機能である。BaseReporter.onRunStartメソッドで実行され、preRunMessage（テスト実行前のメッセージ）をクリアする役割も担う。

**業務上の目的・背景**：開発者がテスト実行を開始したことを視覚的に確認できるようにし、テストが正常に開始されたことを示す。インタラクティブモード（watchモード等）では、前回の実行結果やプロンプトメッセージをクリアして新しいテスト実行のためのクリーンな表示を提供する。

**通知の送信タイミング**：テスト実行が開始された時点（onRunStartイベント）で即座に実行される。これはテストスイートの解析・実行が始まる前のタイミングである。

**通知の受信者**：テストを実行した開発者のコンソール（標準エラー出力）に表示される。

**通知内容の概要**：preRunMessageの削除（クリア）が主な処理であり、これによりテスト開始前の「Determining test suites to run...」等のメッセージがクリアされる。

**期待されるアクション**：開発者はテストが正常に開始されたことを確認し、テスト結果の出力を待つ。

## 通知種別

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

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（onRunStart内で直接呼び出し） |
| 優先度 | 中 |
| リトライ | なし |

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

テストを実行しているプロセスの標準エラー出力（process.stderr）に対して出力する。

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力先 | process.stderr |
| 処理内容 | preRunMessageの削除（ANSIエスケープシーケンスによるクリア） |

### 本文テンプレート

```
（preRunMessageのクリア処理 - ANSIエスケープシーケンス）
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| なし | preRunMessageクリアのみのため変数なし | - | - |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| イベント | onRunStart | 常に実行 | テスト実行開始時に発火 |

### 送信条件詳細

onRunStartイベントが発火した時点で無条件に実行される。

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| なし | 常に実行される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[テスト実行開始] --> B[onRunStart発火]
    B --> C[preRunMessage.remove呼び出し]
    C --> D[process.stderrへANSIエスケープシーケンス出力]
    D --> E[preRunMessageがクリアされる]
    E --> F[終了]
```

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

### 参照テーブル一覧

本通知はデータベースを使用しない。

| データソース | 用途 | 備考 |
|-----------|------|------|
| なし | - | preRunMessageクリアのみ |

### 参照項目詳細

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| なし | preRunMessage.removeは安全に実行される | - |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | N/A |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（テスト実行開始時に即座に出力）

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

- コンソール出力のみのため、機密情報は含まれない
- ローカル環境でのみ表示される

## 備考

- preRunMessageは`jest-util`パッケージで提供される
- ANSIエスケープシーケンスを使用してターミナルの行をクリアする
- インタラクティブモードでない場合も実行されるが、視覚的な効果は限定的

---

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

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

### 推奨読解順序

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

まず、通知処理で使用されるデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | types.ts | `packages/jest-reporters/src/types.ts` | ReporterOnStartOptions型の定義を確認 |

**読解のコツ**: ReporterOnStartOptionsには estimatedTime と showStatus が含まれるが、BaseReporterでは使用されない。

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

処理の起点となるファイル・関数を特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | onRunStartメソッドが通知の起点 |

**主要処理フロー**:
1. **16行目**: `preRunMessage`のインポート（jest-utilから）
2. **19行目**: `preRunMessageRemove`への代入
3. **28-33行目**: `onRunStart`メソッドの実装
4. **32行目**: `preRunMessageRemove(process.stderr)`の呼び出し

#### Step 3: preRunMessageの実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | jest-util | `packages/jest-util/src/preRunMessage.ts` | preRunMessage.remove関数の実装 |

**主要処理フロー**:
- ANSIエスケープシーケンスを使用してターミナルの行をクリア

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

```
jest-core/runJest
    │
    ├─ ReporterDispatcher.onRunStart()
    │      │
    │      └─ BaseReporter.onRunStart()
    │             │
    │             └─ preRunMessageRemove(process.stderr)
    │                    │
    │                    └─ ANSIエスケープシーケンス出力
    │                           └─ ターミナル行クリア
```

### データフロー図

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

onRunStart イベント ───▶ BaseReporter.onRunStart()
                              │
                              └─▶ preRunMessage.remove() ───▶ process.stderr
                                                                (ANSIエスケープ)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| BaseReporter.ts | `packages/jest-reporters/src/BaseReporter.ts` | ソース | onRunStart実装 |
| types.ts | `packages/jest-reporters/src/types.ts` | ソース | ReporterOnStartOptions型定義 |
| preRunMessage.ts | `packages/jest-util/src/preRunMessage.ts` | ソース | preRunMessage.remove実装 |
| index.ts | `packages/jest-util/src/index.ts` | ソース | preRunMessageのエクスポート |
