# バッチ設計書 4-test-harmony

## 概要

本ドキュメントは、npm scriptとして定義された `test-harmony` コマンドの設計仕様を記述したものです。Node.jsのharmonyモード（実験的機能有効）でCoffeeScript言語のテストスイートを実行します。

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

`npm run test-harmony` コマンドは、Node.jsの `--harmony` フラグを付与してテストスイートを実行します。これにより、ステージ段階のJavaScript機能を使用するテストを検証できます。内部的には `node --harmony ./bin/cake test` を呼び出します。

**業務上の目的・背景**：JavaScriptの新機能は、Node.jsで正式サポートされる前に `--harmony` フラグで実験的に有効化できます。CoffeeScriptコンパイラは、これらの新しいJavaScript機能にコンパイルするコードを生成することがあるため、harmonyモードでのテストにより、将来のNode.jsバージョンでの互換性を事前に検証できます。これにより、新しいES仕様への対応状況を確認し、早期に問題を発見できます。

**バッチの実行タイミング**：随時（手動実行）。主に新機能の開発時や、Node.jsの新バージョン対応時に実行されます。通常のCI/CDでは `npm test` が使用されることが多いですが、必要に応じてharmonyテストも実行されます。

**主要な処理内容**：
1. Node.jsプロセスを `--harmony` フラグ付きで起動
2. cake testを実行（通常のtestタスクと同じロジック）
3. test/ディレクトリ配下のテストファイルを順次実行
4. 実験的JavaScript機能を含むテストも実行可能
5. テスト結果（成功数、失敗数）を集計・出力
6. 失敗時はスタックトレースを表示し、exit code 1で終了

**前後の処理との関連**：`npm test` と同様の位置づけですが、より広範囲のJavaScript機能でテストを実行します。`build:watch:harmony` タスクでは継続的にharmonyテストが実行されます。

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

## バッチ種別

テスト実行 / 品質検証

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | なし（手動実行） |
| 実行曜日 | なし |
| 実行日 | なし |
| トリガー | 手動 / 特定開発フェーズ |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| Node.js 6以上 | テスト実行に必要なランタイム |
| --harmonyサポート | Node.jsが--harmonyフラグをサポートしていること |
| CoffeeScriptモジュール | lib/coffeescript配下のコンパイラモジュール |
| テストファイル | test/ディレクトリ配下の.coffee/.litcoffeeファイル |

### 実行可否判定

1. Node.jsランタイムの存在確認
2. --harmonyフラグのサポート確認
3. bin/cakeの存在確認
4. test/ディレクトリの存在確認

## 入力仕様

### 入力パラメータ

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

### 入力データソース

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

## 出力仕様

### 出力データ

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

### 出力ファイル仕様

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

## 処理フロー

### 処理シーケンス

```
1. npm run test-harmonyコマンド実行
   └─ package.jsonのscripts.test-harmonyを参照
2. node --harmony ./bin/cake testを実行
   └─ harmonyフラグによりV8の実験的機能を有効化
3. cake.run()でCakefileをロード
   └─ testタスクを実行
4. runTests(CoffeeScript)を呼び出し
   └─ 通常のテスト実行と同じロジック
5. 実験的機能を使うテストも実行可能
   └─ --harmonyにより通常スキップされるテストも実行される可能性
6. 結果出力
   └─ process.on('exit')で最終結果を出力
```

### フローチャート

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

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

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

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

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

該当なし

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | テスト失敗 | 1つ以上のテストが失敗 | 失敗したテストのエラー内容を確認して修正 |
| 1 | 構文エラー | テストファイルのCoffeeScript構文が不正 | テストファイルの構文を修正 |
| 1 | 実行時エラー | テスト実行中に例外発生 | スタックトレースを確認して修正 |
| 1 | harmony非対応 | 実験的機能がサポートされていない | Node.jsをアップグレード |

### リトライ仕様

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

### 障害時対応

- テスト失敗時：失敗したテストのファイル名、説明、スタックトレースを出力
- harmony機能エラー：Node.jsバージョンを確認し、必要に応じてアップグレード

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

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

## パフォーマンス要件

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

## 排他制御

- 同時実行可能
- 通常のtestコマンドと同時に実行しても問題なし

## ログ出力

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

## 監視・アラート

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

## 備考

- `--harmony` フラグはNode.jsのV8エンジンで実験段階の機能を有効にします
- harmonyモードで有効になる機能はNode.jsバージョンによって異なります
- 将来的に正式サポートされる予定の機能を事前にテストするために使用されます
- 通常の開発では `npm test` を使用し、新機能対応時にのみ `npm run test-harmony` を使用することが推奨されます
- `build:watch:harmony` タスクでは、ファイル変更時に継続的にharmonyテストが実行されます
