# 画面設計書 7-v2テストスイート

## 概要

本ドキュメントは、CoffeeScript 2.x系のブラウザベーステスト画面（docs/v2/test.html）の画面設計書です。v2系コンパイラの各種機能をブラウザ上でテストし、結果を表示します。

### 本画面の処理概要

**業務上の目的・背景**：
CoffeeScript 2.x系コンパイラの品質を保証するため、ブラウザ環境でのテスト実行機能を提供します。ES2015+機能のサポート確認、新機能のテスト、リグレッション検証に使用されます。Promise対応の非同期テストやAST生成機能のテストもサポートします。

**画面へのアクセス方法**：
v2ドキュメントページからのリンク、または直接 /v2/test.html にアクセスすることで表示されます。

**主要な操作・処理内容**：
1. ページ読み込み時に自動的にテストを開始
2. ES Module版またはレガシー版コンパイラでテストコードを実行
3. 同期・非同期テストケースの実行と結果表示
4. AST生成機能のテスト
5. テスト完了後にサマリーとGoogle Analytics送信

**画面遷移**：
- このページに遷移してくる画面: v2ドキュメントページ
- このページから遷移できる画面: なし

**権限による表示制御**：
特になし。全ユーザーがアクセス可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 51 | ブラウザコンパイラ | 主機能 | v2コンパイラでテストコードをブラウザ上で実行 |
| 53 | scriptタグ実行 | 主機能 | text/coffeescriptタイプのscriptタグを自動コンパイル・実行 |
| 1 | CoffeeScript コンパイル | 主機能 | テストコードのコンパイルと実行 |

## 画面種別

テスト実行 / 結果表示画面

## URL/ルーティング

- パス: `/v2/test.html`
- ファイル: `docs/v2/test.html`（ビルド済み静的HTML）

## 入出力項目

本画面は自動実行されるため、ユーザー入力項目はありません。

| 項目名 | 種別 | データ型 | 必須 | 説明 |
|--------|------|---------|------|------|
| テストコード | 入力（自動） | CoffeeScript | - | scriptタグ内のテストコード |
| テスト結果 | 出力 | HTML | - | 各テストケースの成功/失敗表示 |
| サマリー | 出力 | テキスト | - | テスト結果の集計情報 |

## 表示項目

| 表示項目 | データソース | 表示形式 | 説明 |
|---------|-------------|---------|------|
| タイトル | 固定 | H1 | "CoffeeScript Test Suite" |
| テスト結果エリア | 動的生成 | pre#stdout | テスト結果を順次表示 |
| 成功結果 | 動的生成 | div.good | 緑色(#22b24c)で成功メッセージ |
| 失敗結果 | 動的生成 | div.bad | 赤色(#eb6864)でエラー詳細 |
| 詳細情報 | 動的生成 | div.subtle | グレー(#999999)でソースコード等 |

## イベント仕様

### 1-ページ読み込み・テスト開始

ES Module版またはレガシー版コンパイラの読み込み後、テストが開始されます。

- トリガー: DOMContentLoaded イベント
- 処理:
  1. CoffeeScriptをwindowオブジェクトに設定
  2. CoffeeScript.runScripts()を呼び出し
  3. text/coffeescriptタイプのscriptタグを検出・実行

### 2-同期テスト実行

通常のテスト関数を即座に実行します。

- トリガー: test()関数の呼び出し
- 処理:
  1. fn.call(fn) でテスト関数を実行
  2. 成功時: passedTests++
  3. 失敗時: onFail()でエラー情報を蓄積

### 3-非同期テスト実行

Promiseを返すテスト関数を非同期で処理します。

- トリガー: test()関数がPromiseを返した場合
- 処理:
  1. asyncTests配列にPromiseを追加
  2. result.then() で成功時 passedTests++
  3. result.catch() で失敗時 onFail()を呼び出し

### 4-テスト完了・サマリー表示

Promise.all()で全テスト完了後にサマリーを表示します。

- トリガー: Promise.all(asyncTests).then(done)
- 処理:
  1. 実行時間を計算
  2. 成功/失敗件数を集計
  3. サマリーメッセージを表示
  4. Google Analyticsにテスト結果を送信

## データベース更新仕様

該当なし

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| TEST_PASSED | 成功 | passed X tests in Y.ZZ seconds | 全テスト成功時 |
| TEST_FAILED | 失敗 | failed X tests and passed Y tests... | テスト失敗時 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| コンパイルエラー | エラーメッセージをbadクラスで表示 |
| アサーション失敗 | エラー詳細とソースコードを表示 |
| 非同期テストエラー | catch()でエラーをキャプチャして表示 |

## 備考

- v1系と比較してPromise対応の非同期テストをサポート
- AST生成機能（getAstRoot, getAstExpression等）のテストヘルパーを提供
- eqJS()関数でCoffeeScript to JavaScript変換を検証
- throwsCompileError()、doesNotThrowCompileError()でコンパイルエラーのテスト
- Google Analytics（gtag）でテスト結果を送信

---

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

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

### 推奨読解順序

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

v2テストフレームワークの拡張されたヘルパー関数を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | test.html | `docs/v2/test.html` | グローバル変数とヘルパー関数の定義 |

**読解のコツ**: v2系はv1系を拡張しており、Promise対応やAST関連のヘルパーが追加されています。

#### Step 2: テスト実行フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | test.html | `docs/v2/test.html` | test()関数のPromise対応実装 |

**主要処理フロー**:
- **行68-81**: test()関数 - Promise対応の非同期テストサポート
- **行83-89**: failures オブジェクト - エラー情報の蓄積
- **行128-135**: eq(), arrayEq() - 値比較関数
- **行136-139**: eqJS() - CoffeeScript to JavaScript変換テスト
- **行152-165**: getAstRoot(), getAstExpression() - AST取得ヘルパー

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

```
docs/v2/test.html
    |
    +-- [ES Module版]
    |       +-- import CoffeeScript from './browser-compiler-modern/coffeescript.js'
    |       +-- window.CoffeeScript = CoffeeScript
    |       +-- DOMContentLoaded -> CoffeeScript.runScripts()
    |
    +-- [レガシー版]
    |       +-- <script nomodule src="browser-compiler-legacy/coffeescript.js">
    |
    +-- Underscore.js (CDN)
    |
    +-- メインテストスクリプト
    |       |
    |       +-- グローバル変数初期化
    |       +-- test(), ok(), eq(), eqJS() 定義
    |       +-- getAstRoot(), getAstExpression() 定義
    |       +-- throwsCompileError(), doesNotThrowCompileError() 定義
    |
    +-- テストスクリプト (class="test")
            |
            +-- CoffeeScript.run()
            +-- test(description, fn)
                    |
                    +-- fn() 実行
                    +-- 同期: 即時結果処理
                    +-- 非同期: asyncTests[] に追加
            |
            +-- Promise.all(asyncTests).then(done)
                    |
                    +-- サマリー表示
                    +-- gtag イベント送信
```

### データフロー図

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

テストスクリプト          v2 CoffeeScript                 JavaScript実行
(scriptタグ)    -------> .run()           ------------>
                              |
                              v
                         test(desc, fn)
                              |
                              +----> 同期成功 ----> passedTests++
                              |
                              +----> 同期失敗 ----> onFail()
                              |
                              +----> Promise ----> asyncTests[]
                                          |
                                          v
                                    Promise.all()
                                          |
                                          v
                                    done() -> サマリー表示
                                              gtag送信
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| test.html | `docs/v2/test.html` | HTML | v2テストスイートページ |
| coffeescript.js | `docs/v2/browser-compiler-modern/coffeescript.js` | 生成コード | ES Module版コンパイラ |
| coffeescript.js | `docs/v2/browser-compiler-legacy/coffeescript.js` | 生成コード | レガシー版コンパイラ |
| underscore-min.js | CDN | 外部ライブラリ | deepEqual比較用 |
