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

## 概要

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

### 本画面の処理概要

**業務上の目的・背景**：
CoffeeScriptコンパイラの品質を保証するため、ブラウザ環境でのテスト実行機能を提供します。Node.js環境でのテストに加え、ブラウザ特有の動作確認が必要なため、このテストスイート画面が用意されています。開発者やコントリビューターがコンパイラの動作を検証する際に使用します。

**画面へのアクセス方法**：
トップページのサイドバーにある「Browser-Based Tests」リンクをクリック、または直接 test.html にアクセスすることで表示されます。

**主要な操作・処理内容**：
1. ページ読み込み時に自動的にテストを開始
2. `text/coffeescript` および `text/x-literate-coffeescript` タイプのscriptタグを順次コンパイル・実行
3. 各テストケースの成功/失敗を画面に表示
4. 非同期テスト（Promise）のサポート
5. テスト完了後に結果サマリーを表示
6. Google Analyticsへのテスト結果送信

**画面遷移**：
- このページに遷移してくる画面: トップページのサイドバー
- このページから遷移できる画面: なし（単独のテスト実行ページ）

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

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 51 | ブラウザコンパイラ | 主機能 | テストコードをブラウザ上でコンパイルして実行 |
| 53 | scriptタグ実行 | 主機能 | text/coffeescriptタイプのscriptタグを自動でコンパイル・実行 |
| 1 | CoffeeScript コンパイル | 主機能 | CoffeeScript.runによるテストコードのコンパイルと実行 |
| 8 | Literate CoffeeScript対応 | 補助機能 | text/x-literate-coffeescriptタイプのテストコードに対応 |

## 画面種別

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

## URL/ルーティング

- パス: `/test.html`
- テンプレートファイル: `documentation/site/test.html`

## 入出力項目

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

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

## 表示項目

| 表示項目 | データソース | 表示形式 | 説明 |
|---------|-------------|---------|------|
| タイトル | 固定 | H1 | "CoffeeScript Test Suite" |
| テスト結果エリア | 動的生成 | pre#stdout | テスト結果を順次表示 |
| テストファイル名 | scriptタグID | div | チェックマーク付きでファイル名表示 |
| 成功結果 | 動的生成 | div.good | 緑色で成功メッセージ表示 |
| 失敗結果 | 動的生成 | div.bad | 赤色でエラー詳細表示 |
| サブタイトル | 動的生成 | div.subtle | グレーでソースコード表示 |

## イベント仕様

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

ページ読み込み時にCoffeeScript.runScripts()が自動実行され、テストが開始されます。

- トリガー: DOMContentLoaded イベント
- 処理:
  1. ブラウザコンパイラの読み込み（ES Module版またはレガシー版）
  2. window.addEventListener('DOMContentLoaded', CoffeeScript.runScripts, false)
  3. テストセットアップスクリプトの実行
  4. 各テストスクリプトの順次実行

### 2-テストケース実行

各テストスクリプトタグの内容をコンパイル・実行します。

- トリガー: class="test" のscriptタグの検出
- 処理:
  1. scriptタグのIDからテストファイル名を取得
  2. type属性からLiterateモードかどうかを判定
  3. CoffeeScript.run(innerHTML, options) でコンパイル・実行
  4. test()関数でラップされた各テストケースを実行
- エラー時: failures.push()でエラー情報を蓄積

### 3-テスト結果表示

各テストケースの結果を画面に動的に追加します。

- トリガー: test()関数の実行完了
- 処理:
  1. 成功時: passedTests++
  2. 失敗時: failedTests++、エラー詳細を表示
  3. div要素を生成してstdoutに追加
- 表示クラス: good（成功）、bad（失敗）、subtle（詳細）

### 4-非同期テスト対応

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

- トリガー: test()関数がPromiseを返した場合
- 処理:
  1. asyncTests配列にPromiseを追加
  2. Promise.all(asyncTests).then(done).catch(done)で全完了を待機
  3. 完了後にサマリーを表示

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

全テスト完了後に結果サマリーを表示します。

- トリガー: Promise.all()の完了
- 処理:
  1. 実行時間を計算
  2. 成功/失敗件数を集計
  3. "passed X tests in Y seconds" または "failed X tests and passed Y tests..." を表示
  4. Google Analyticsにテスト結果を送信

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

本画面はクライアントサイドのみで動作するため、データベースへの更新処理はありません。

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

該当なし

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| TEST_PASSED | 成功 | passed X tests in Y.ZZ seconds | 全テスト成功時 |
| TEST_FAILED | 失敗 | failed X tests and passed Y tests in Z.ZZ seconds | テスト失敗がある場合 |
| ASSERTION_ERROR | エラー | エラーメッセージ詳細 | アサーション失敗時 |

## 例外処理

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

## 備考

- ブラウザコンパイラはES Module版（modern）とnomodule属性でレガシー版を使い分け
- Underscore.jsを使用してdeepEqual比較を実装
- グローバル変数（window.test, window.ok, window.eq等）を定義してテストヘルパーを提供
- テスト結果はGoogle Analyticsに送信される（event_category: 'tests'）
- ビルド時にtest.htmlテンプレートが展開され、各テストスクリプトが埋め込まれる

---

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

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

### 推奨読解順序

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

テストフレームワークのグローバル変数と構造を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | test.html | `documentation/site/test.html` | グローバル変数の定義（test, ok, eq, deepEqual等） |

**読解のコツ**: @記法（@test, @ok等）はCoffeeScriptでwindowオブジェクトへの代入を意味します。

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

テストページの初期化と実行開始の流れを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | test.html | `documentation/site/test.html` | scriptタグの読み込み順序とDOMContentLoadedイベント |

**主要処理フロー**:
1. **行6-7**: ES Module版コンパイラをnomodule/module属性で切り替え
2. **行8-11**: ES Module版ではCoffeeScriptをimportしてwindowに設定
3. **行12**: Underscore.jsの読み込み
4. **行44-54**: グローバル変数の初期設定（testingBrowser, global, stdout等）
5. **行68-81**: test()関数の定義（Promise対応）
6. **行128-133**: テストスクリプトの順次実行

#### Step 3: テストヘルパー関数を理解する

アサーション関数の実装を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | test.html | `documentation/site/test.html` | ok, eq, arrayEq, deepEqual, throws, doesNotThrowの実装 |

**主要処理フロー**:
- **行91-92**: ok関数 - 条件がtrueでなければエラーをthrow
- **行99-100**: deepEqual関数 - Underscore.jsのisEqualを使用
- **行104-106**: doesNotThrow関数 - 関数が例外を投げないことを確認
- **行108-124**: throws関数 - 関数が期待通りの例外を投げることを確認

#### Step 4: 結果表示とレポートを理解する

テスト結果の表示とGoogle Analytics連携を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | test.html | `documentation/site/test.html` | say関数、done関数、gtag連携 |

**主要処理フロー**:
- **行53-59**: say関数 - DOM要素を生成してstdoutに追加
- **行136-153**: done関数 - テスト結果サマリーの計算と表示
- **行143-152**: gtag呼び出しでGoogle Analyticsにテスト結果を送信

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

```
test.html ページ読み込み
    |
    +-- [ES Module版]
    |       +-- import CoffeeScript from './browser-compiler-modern/coffeescript.js'
    |       +-- window.CoffeeScript = CoffeeScript
    |       +-- window.addEventListener('DOMContentLoaded', CoffeeScript.runScripts)
    |
    +-- [レガシー版]
    |       +-- <script nomodule src="browser-compiler-legacy/coffeescript.js">
    |       +-- 自動的にrunScriptsが呼ばれる
    |
    +-- DOMContentLoaded
            |
            +-- CoffeeScript.runScripts()
                    |
                    +-- text/coffeescript scriptタグを検出
                    |
                    +-- メインテストセットアップスクリプト実行
                    |       |
                    |       +-- グローバル変数初期化
                    |       +-- test(), ok(), eq() 等定義
                    |
                    +-- 各テストスクリプト（class="test"）実行
                    |       |
                    |       +-- CoffeeScript.run(innerHTML, {filename, literate})
                    |       +-- test(description, fn) 呼び出し
                    |               |
                    |               +-- fn() 実行
                    |               +-- 成功: passedTests++
                    |               +-- 失敗: failures.push()
                    |
                    +-- Promise.all(asyncTests).then(done)
                            |
                            +-- サマリー表示
                            +-- gtag イベント送信
```

### データフロー図

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

テストスクリプト          CoffeeScript                    コンパイル済み
(scriptタグ)    -------> .run()           ------------>  JavaScript実行
                              |
                              v
                         test(desc, fn)
                              |
                              +----> 成功 -----> passedTests++ -----> div.good表示
                              |
                              +----> 失敗 -----> failures.push() ----> div.bad表示
                              |
                              +----> Promise --> asyncTests[] -----> Promise.all待機
                                                                          |
                                                                          v
                                                                     done()実行
                                                                          |
                                                                          v
                                                                     サマリー表示
                                                                     gtag送信
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| test.html | `documentation/site/test.html` | テンプレート | テストスイートページのHTML/テストフレームワーク |
| browser.coffee | `src/browser.coffee` | ソース | CoffeeScript.runScripts()の実装 |
| coffeescript.coffee | `src/coffeescript.coffee` | ソース | CoffeeScript.run()の実装 |
| coffeescript.js | `browser-compiler-modern/` | 生成コード | ES Module版ブラウザコンパイラ |
| coffeescript.js | `browser-compiler-legacy/` | 生成コード | レガシー版ブラウザコンパイラ |
| underscore-min.js | CDN | 外部ライブラリ | deepEqual比較用 |
| test/*.coffee | `test/` | テストコード | 各種テストスクリプト |
