# 通知設計書 31-テストファイル更新ログ

## 概要

本ドキュメントは、Babelのテストランナーヘルパー（`@babel/helper-transform-fixture-test-runner`）がテストファイルを作成・更新した際のログ出力に関する設計を記載する。

### 本通知の処理概要

テストファイル更新ログは、Babelの変換テスト実行時に、期待結果ファイルの自動生成・更新を開発者に通知する機能である。

**業務上の目的・背景**：Babelの変換処理テストでは、入力コードに対する期待出力を比較検証する。新規テスト追加時や既存テスト更新時に、期待結果ファイルを手動で作成するのは煩雑であるため、テストランナーが自動生成・更新する仕組みを持つ。この通知は、どのファイルが自動生成・更新されたかを開発者に明示し、意図しない変更を検出できるようにする。

**通知の送信タイミング**：以下のイベントで通知が発生する：(1) 新規テストの期待出力ファイルが存在しない場合の自動生成時、(2) `OVERWRITE`環境変数が設定されている状態でテスト実行し、期待結果が異なる場合の更新時、(3) ソースマップやソースマップ可視化ファイルの更新時。

**通知の受信者**：テストを実行している開発者（コンソール出力を見ているユーザー）。

**通知内容の概要**：更新・作成されたファイルのパスが出力される。「New test file created:」または「Updated test file:」というプレフィックスと共にファイルパスが表示される。

**期待されるアクション**：開発者は通知を確認し、自動生成・更新されたファイルの内容をレビューする。必要に応じてGitでの差分確認やコミットを行う。

## 通知種別

コンソール出力（標準出力 / console.log）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期 |
| 優先度 | 低 |
| リトライ | 無し |

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

テストランナーを実行しているプロセスの標準出力に対して直接出力される。送信先の動的決定は行われない。

## 通知テンプレート

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

| 項目 | 内容 |
|-----|------|
| 出力先 | 標準出力（stdout） |
| 形式 | テキスト |

### 本文テンプレート

```
New test file created: {ファイルパス}
```

または

```
Updated test file: {ファイルパス}
```

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| ファイルパス | 作成・更新されたファイルの絶対パス | expected.loc, task.sourceMapVisual.loc, task.sourceMapFile.loc, expectedLoc 等 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| テスト実行 | 新規期待出力ファイル生成 | expected.code が空、outputCode が存在、opts.throws が false、親ディレクトリが存在、CI環境でない | 新しいテストファイルが自動作成される |
| テスト実行 | 期待出力ファイル更新 | OVERWRITE環境変数が設定されており、actualCode !== expectedCode | 既存テストの期待結果が更新される |
| テスト実行 | ソースマップ可視化ファイル更新 | OVERWRITE環境変数が設定、またはsourceMapVisual.codeが未設定 | ソースマップの可視化ファイルが更新される |
| テスト実行 | ソースマップJSONファイル更新 | OVERWRITE環境変数が設定、またはtask.sourceMapが未設定 | ソースマップJSONが更新される |
| テスト実行 | stdout/stderrファイル更新 | OVERWRITE環境変数が設定されており、期待値と異なる | 標準出力・エラー出力の期待ファイルが更新される |
| テスト実行 | out-filesファイル更新 | OVERWRITE環境変数が設定されており、期待値と異なる | 出力ファイルの期待結果が更新される |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| CI環境（process.env.CI が設定）| CI環境では新規ファイル作成を行わず、通知も発生しない |
| ファイル内容が一致 | 期待結果と実際の出力が一致する場合は更新・通知は発生しない |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[テスト実行開始] --> B[コード変換実行]
    B --> C{期待出力ファイルが存在?}
    C -->|No| D{CI環境?}
    D -->|No| E[新規ファイル作成]
    E --> F[console.log で通知]
    D -->|Yes| G[スキップ]
    C -->|Yes| H{出力が一致?}
    H -->|Yes| I[テスト成功]
    H -->|No| J{OVERWRITE設定?}
    J -->|Yes| K[ファイル更新]
    K --> L[console.log で通知]
    J -->|No| M[テスト失敗]
    F --> I
    L --> I
```

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

該当なし（ファイルシステムへの直接書き込み）

### 参照テーブル一覧

該当なし

### 更新テーブル一覧

該当なし

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| ファイル書き込みエラー | ディスク容量不足、権限不足等 | 例外がスローされ、テストが失敗する |
| ファイル削除エラー | 古い拡張子のファイル削除失敗 | try-catch で無視される（処理継続） |

### リトライ仕様

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

## 配信設定

### レート制限

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

### 配信時間帯

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

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

- ファイルパスがログに出力されるが、開発環境での使用を想定しており、機密情報は含まれない
- CI環境では新規ファイル作成が抑止されるため、意図しないファイル生成のリスクを軽減

## 備考

- `OVERWRITE`環境変数を設定してテストを実行することで、期待結果ファイルの一括更新が可能
- 新規テストの期待出力ファイルは、変換結果の`sourceType`に応じて`.js`または`.mjs`拡張子で生成される

---

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

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

### 推奨読解順序

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

テストタスクの構造とファイル情報の管理方法を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | Test型、TestFile型のインポートと使用方法を確認（4-13行目） |

**読解のコツ**: `@babel/helper-fixtures`から提供されるTest型が、テストタスクの基本構造を定義している。`actual`, `expect`, `exec`などのプロパティがTestFile型として定義されている。

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

テスト実行のメインフローを把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | run関数（252-420行目）がテスト実行のメインロジック |

**主要処理フロー**:
1. **252-264行目**: テストタスクから必要な情報を取得（actual, expected, exec等）
2. **317-361行目**: 変換結果と期待結果の比較、新規ファイル作成
3. **386-415行目**: ソースマップ関連ファイルの更新

#### Step 3: ログ出力箇所を理解する

console.logによる通知出力の具体的な実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | 新規ファイル作成通知（344行目） |
| 3-2 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | ソースマップ可視化ファイル更新通知（393行目） |
| 3-3 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | ソースマップJSON更新通知（409行目） |
| 3-4 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | validateFile内の更新通知（429行目） |
| 3-5 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | assertTest内のstderr更新通知（658行目） |
| 3-6 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | assertTest内のstdout更新通知（678行目） |
| 3-7 | index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | assertTest内のout-files更新通知（708行目） |

**主要処理フロー**:
- **344行目**: `console.log(`New test file created: ${expectedFile}`);`
- **393行目**: `console.log(`Updated test file: ${task.sourceMapVisual.loc}`);`
- **409行目**: `console.log(`Updated test file: ${task.sourceMapFile.loc}`);`
- **429行目**: `console.log(`Updated test file: ${expectedLoc}`);`

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

```
default export (テストスイート登録)
    │
    ├─ getFixtures() - テストケース読み込み
    │
    └─ run(task) - テスト実行
           │
           ├─ babel.transformAsync() - コード変換
           │
           ├─ validateFile() - 出力検証・更新
           │      └─ console.log() - 更新通知
           │
           ├─ fs.writeFileSync() - 新規ファイル作成
           │      └─ console.log() - 作成通知
           │
           └─ visualizeSourceMap() - ソースマップ可視化
                  └─ console.log() - 更新通知

buildProcessTests()
    │
    └─ test.fn (テスト関数)
           │
           └─ assertTest() - 出力検証
                  └─ console.log() - 更新通知
```

### データフロー図

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

テストタスク ───▶ run()関数 ───▶ 変換結果
    │                                  │
    │                                  ▼
    │                          期待結果と比較
    │                                  │
    │                          ┌───────┴───────┐
    │                          ▼               ▼
    │                      一致           不一致
    │                        │               │
    │                        ▼               ▼
    └────────────────▶ テスト成功      ファイル更新
                                             │
                                             ▼
                                      console.log()
                                             │
                                             ▼
                                      標準出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/babel-helper-transform-fixture-test-runner/src/index.ts` | ソース | テストランナーのメインロジック、ログ出力を含む |
| helpers.ts | `packages/babel-helper-transform-fixture-test-runner/src/helpers.ts` | ソース | テストヘルパー関数 |
| source-map-visualizer.ts | `packages/babel-helper-transform-fixture-test-runner/src/source-map-visualizer.ts` | ソース | ソースマップの可視化 |
| index.ts | `packages/babel-helper-fixtures/src/index.ts` | ソース | テストフィクスチャの読み込み |
