# バッチ設計書 3-test

## 概要

本ドキュメントは、npm scriptとして定義された `test` コマンドの設計仕様を記述したものです。CoffeeScript言語のテストスイートを実行します。

### 本バッチの処理概要

`npm test` コマンドは、CoffeeScriptコンパイラの品質を保証するためのテストスイートを実行します。内部的には `node ./bin/cake test` を呼び出し、Cakefileに定義された `test` タスクを実行します。

**業務上の目的・背景**：CoffeeScriptコンパイラは、多数の言語機能をサポートする複雑なソフトウェアです。新機能の追加やバグ修正を行う際に、既存の機能が壊れていないことを確認する必要があります。テストスイートは、コンパイラの正確性を自動的に検証し、リグレッションを防止します。また、CIパイプラインで自動実行され、プルリクエストのマージ前に品質を担保します。

**バッチの実行タイミング**：随時（手動実行）およびCI/CD時。開発者がコード変更後に実行するほか、GitHub Actionsなどで自動実行されます。

**主要な処理内容**：
1. Nodeプロセスを起動し、cake testを実行
2. CoffeeScript.register()でCoffeeScriptファイルの動的読み込みを有効化
3. test/ディレクトリ配下のテストファイルを順次実行
4. 各テストファイルをCoffeeScriptとしてコンパイル・実行
5. 非同期テストの完了を待機
6. テスト結果（成功数、失敗数）を集計・出力
7. 失敗時はスタックトレースを表示し、exit code 1で終了

**前後の処理との関連**：`build` タスクでコンパイラをビルドした後に実行されることが多いです。`build:full` タスクはビルドとテストを連続して実行します。CI/CDパイプラインでは、テスト成功がマージ条件となります。

**影響範囲**：テスト結果はプロセスのexit codeに反映され、CI/CDの成否を決定します。ファイルシステムへの永続的な変更は行いません。

## バッチ種別

テスト実行 / 品質検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 / CI時 |
| 実行時刻 | なし（手動/イベント駆動） |
| 実行曜日 | なし |
| 実行日 | なし |
| トリガー | 手動 / CI/CD / プルリクエスト |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js 6以上 | テスト実行に必要なランタイム |
| CoffeeScriptモジュール | lib/coffeescript配下のコンパイラモジュール |
| テストファイル | test/ディレクトリ配下の.coffee/.litcoffeeファイル |
| テストヘルパー | test/support/helpers.coffee |

### 実行可否判定

1. Node.jsランタイムの存在確認
2. bin/cakeの存在確認
3. Cakefileの存在確認
4. test/ディレクトリの存在確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | npm testは引数を受け付けません |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| test/*.coffee | CoffeeScript | テストスクリプト |
| test/*.litcoffee | Literate CoffeeScript | リテレートスタイルのテストスクリプト |
| test/support/helpers.coffee | CoffeeScript | テストヘルパー関数 |
| lib/coffeescript/*.js | JavaScript | テスト対象のコンパイラモジュール |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト結果サマリー（成功数、実行時間） |
| 標準出力 | テキスト | 失敗時のエラー詳細 |
| プロセスexit code | 数値 | 0=成功、1=失敗 |

### 出力ファイル仕様

ファイル出力はありません。

## 処理フロー

### 処理シーケンス

```
1. npm testコマンド実行
   └─ package.jsonのscripts.testを参照
2. node ./bin/cake testを実行
   └─ cake.run()でCakefileをロード
3. Cakefileのtestタスクを実行
   └─ runTests(CoffeeScript)を呼び出し
4. CoffeeScript.register()でモジュール登録
   └─ require()で.coffeeファイルを読み込み可能に
5. グローバル変数のセットアップ
   └─ test(), assert関数等をglobalに登録
6. Node.jsバージョンによるテストスキップ判定
   └─ async/await、BigInt等の機能チェック
7. test/配下のファイルを順次実行
   └─ CoffeeScript.run()で各テストを実行
8. 非同期テストの完了待機
   └─ Promise.all(asyncTests)
9. 結果出力
   └─ process.on('exit')で最終結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[npm test] --> B[node ./bin/cake test]
    B --> C[cake.run: Cakefileロード]
    C --> D[testタスク実行]
    D --> E[runTests関数呼び出し]
    E --> F[CoffeeScript.register]
    F --> G[グローバル変数セットアップ]
    G --> H[スキップ対象テスト判定]
    H --> I[test/ファイル読み込み]
    I --> J{各テスト実行}
    J --> K[同期テスト]
    J --> L[非同期テスト]
    K --> M[結果記録]
    L --> N[Promise追加]
    M --> O{次のテスト?}
    N --> O
    O -->|Yes| J
    O -->|No| P[Promise.all待機]
    P --> Q[結果集計・出力]
    Q --> R{失敗あり?}
    R -->|Yes| S[exit 1]
    R -->|No| T[exit 0]
```

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

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

本バッチはデータベース操作を行いません。

### テーブル別操作詳細

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | テスト失敗 | 1つ以上のテストが失敗 | 失敗したテストのエラー内容を確認して修正 |
| 1 | 構文エラー | テストファイルのCoffeeScript構文が不正 | テストファイルの構文を修正 |
| 1 | 実行時エラー | テスト実行中に例外発生 | スタックトレースを確認して修正 |

### リトライ仕様

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

### 障害時対応

- テスト失敗時：失敗したテストのファイル名、説明、スタックトレースを出力
- ソースコードがある場合：コンパイル済み関数のソースを表示
- process.exit(1)でCIパイプラインに失敗を通知

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし |
| コミットタイミング | なし |
| ロールバック条件 | なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 数百〜数千のテストケース |
| 目標処理時間 | 数秒〜数十秒 |
| メモリ使用量上限 | Node.jsデフォルト制限に従う |

## 排他制御

- 同時実行可能
- テスト間の状態共有はglobal変数経由（passedTests, failures等）

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 成功ログ | 全テスト成功時 | "passed X tests in Y seconds" |
| 失敗ログ | テスト失敗時 | "failed X and passed Y tests in Z seconds" |
| エラー詳細 | 各失敗時 | テスト説明、エラースタック、ソースコード |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| exit code | 0以外 | CI/CDシステム（GitHub Actions等） |

## 備考

- Node.jsバージョンによって一部のテストはスキップされます
  - async/await: Node.js 7.6+
  - async iterators: Node.js 10+
  - exponentiation: Node.js 7+
  - object rest/spread: Node.js 8.3+
  - regex dotall: Node.js 9+
  - numeric separators: Node.js 12.5+
  - BigInt: Node.js 10.4+
  - import assertions: Node.js 17.1+
- テスト関数 `test()` はグローバルに登録され、各テストファイルから呼び出されます
- 非同期テストはPromiseを返すことで識別され、`Promise.all()` で待機されます
