# テスト方針書

## 概要

本ドキュメントは、CoffeeScript（バージョン2.7.0）プロジェクトにおけるテスト方針を定義します。CoffeeScriptはJavaScriptにコンパイルされるプログラミング言語であり、コンパイラの品質保証のために包括的なテストスイートが実装されています。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | CoffeeScriptの各言語機能（配列、クラス、関数など）が正しくコンパイル・実行されることを検証 | 開発者 |
| 結合テスト | コンパイラコンポーネント（Lexer、Parser、Rewriter、Nodes）の連携動作を検証 | 開発者 |
| ブラウザテスト | ブラウザ環境でのCoffeeScriptコンパイラの動作を検証（Puppeteerによるヘッドレステスト） | CI/CD |
| 統合テスト | Webpackなど外部ツールとの統合動作を検証（test:integrations） | CI/CD |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | 51個のテストファイルで言語機能（配列、クラス、関数、制御フロー、AST等）を網羅的にテスト | コミット時、プルリクエスト時 |
| 互換性テスト | 複数のNode.jsバージョン（12.x〜20.x）および複数OS（Ubuntu、macOS、Windows）での動作確認 | CI/CDパイプライン |
| ブラウザ互換性テスト | レガシーブラウザコンパイラとモダンブラウザコンパイラの両方をテスト | CI/CDパイプライン |
| リグレッションテスト | セルフホスティング検証（コンパイラが自身をコンパイルできることを確認） | ビルド時 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発時のテスト実行 | Node.js 6以上、npm |
| GitHub Actions Ubuntu | Linux環境でのCI/CDテスト | ubuntu-latest、Node.js 12.x〜20.x |
| GitHub Actions macOS | macOS環境でのCI/CDテスト | macos-latest、Node.js 12.x〜20.x |
| GitHub Actions Windows | Windows環境でのCI/CDテスト | windows-latest、Node.js 12.x〜20.x |
| ヘッドレスブラウザ | ブラウザコンパイラのテスト | Puppeteer（Chromium） |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Cake（カスタムビルドツール） | テストランナー、ビルド自動化 | CoffeeScript内蔵 |
| Node.js assert | アサーション | Node.js組み込み |
| Puppeteer | ブラウザテスト自動化 | ~13.6.0 |
| Webpack | 統合テスト（ブラウザ向けビルド検証） | ~5.72.0 |
| Jison | パーサー生成（テスト対象） | ~0.4.18 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 言語機能カバレッジ | 全51テストファイルによる包括的なカバレッジ |
| クロスプラットフォーム | 3 OS x 5 Node.jsバージョン = 15マトリクス |
| ブラウザ互換性 | レガシー（ES5）およびモダン（ESモジュール）の両方 |

注: 本プロジェクトでは行カバレッジ・分岐カバレッジの数値目標は明示的に設定されていません。代わりに、言語機能ごとのテストファイルによる機能カバレッジを重視しています。

## テストデータ

テストデータは各テストファイル内にインラインで記述されています。主なパターン：

- **インラインCoffeeScriptコード**: 各言語機能のコードスニペット
- **期待されるAST構造**: abstract_syntax_tree.coffee、abstract_syntax_tree_location_data.coffeeで定義
- **エラーメッセージパターン**: error_messages.coffeeで期待されるエラー出力を検証
- **インポートテスト用ファイル**: test/importingディレクトリに各種拡張子のテストファイル

テストヘルパー（test/support/helpers.coffee）が提供するユーティリティ：
- `eq`: 値の等価性チェック（egal関数ベース）
- `arrayEq`: 配列の深い等価性チェック
- `eqJS`: CoffeeScriptコードとコンパイル後のJavaScriptの比較
- `getAstExpression` / `getAstStatement`: AST取得ヘルパー
- `throwsCompileError` / `doesNotThrowCompileError`: コンパイルエラーの検証

## 不具合管理

- **バグトラッカー**: GitHub Issues（https://github.com/jashkenas/coffeescript/issues）
- **プルリクエスト**: GitHub Pull Requests
- **回帰テスト**: 新しいバグ修正時はテストケースを追加

## CI/CD連携

### GitHub Actions ワークフロー

ワークフロー名: **Build and Test**

**トリガー**: push、pull_request

**マトリクス戦略**:
- OS: ubuntu-latest、macos-latest、windows-latest
- Node.js: 12.x、14.x、16.x、18.x、20.x

**実行ステップ**:
1. チェックアウト
2. Node.jsセットアップ（npmキャッシュ有効）
3. `npm ci`による依存関係インストール
4. `cake build:except-parser` - パーサー以外のビルド
5. `cake build:parser` - パーサービルド
6. セルフホスティング検証（再度build:except-parser、build:parser）
7. `cake build:browser` - ブラウザコンパイラビルド
8. `cake doc:test` - テストページ生成
9. `git diff --exit-code` - ビルド成果物の変更確認
10. `cake test` - メインテストスイート実行
11. `cake test:browser` - ブラウザテスト（リトライ3回まで）
12. `cake test:browser:node` - Node.js上でのブラウザコンパイラテスト
13. `cake test:integrations` - Webpack統合テスト

### ローカルテスト実行コマンド

```bash
# メインテスト
npm test                    # または node ./bin/cake test

# Harmonyフラグ付きテスト
npm run test-harmony        # または node --harmony ./bin/cake test

# ブラウザテスト
node ./bin/cake test:browser

# 統合テスト
node ./bin/cake test:integrations
```

## 備考

### テストファイル構成

51個の.coffeeファイルと2個の.litcoffeeファイルで約33,000行のテストコードが実装されています。主なテストカテゴリ：

| カテゴリ | テストファイル |
| --- | --- |
| 基本構文 | arrays.coffee、objects.coffee、strings.coffee、numbers.coffee |
| 制御構造 | control_flow.coffee、comprehensions.coffee、exception_handling.coffee |
| 関数 | functions.coffee、function_invocation.coffee、generators.coffee |
| クラス | classes.coffee |
| ES6+機能 | async.coffee、async_iterators.coffee、modules.coffee、jsx.coffee |
| コンパイラ | compilation.coffee、parser.coffee、lexer関連 |
| AST | abstract_syntax_tree.coffee、abstract_syntax_tree_location_data.coffee |
| エラー処理 | error_messages.coffee |

### Node.jsバージョン別スキップ機能

一部のテストはNode.jsのバージョンによってスキップされます：
- async/await機能: async.coffee、async_iterators.coffee
- 指数演算子: exponentiation.coffee
- オブジェクトスプレッド: object_rest_spread.coffee
- 正規表現dotAll: regex_dotall.coffee
- 数値リテラルセパレータ: numeric_literal_separators.coffee
- BigInt: numbers_bigint.coffee
- Import Assertions: import_assertions.coffee

### セルフホスティング

CoffeeScriptコンパイラは自身でコンパイルされています。ビルドプロセスでは、コンパイラが2回ビルドされ、最新のコンパイラが自身をコンパイルできることを検証しています。
