# バッチ設計書 1-minitest.sh

## 概要

本ドキュメントは、HHVMテスト実行用シェルスクリプト `minitest.sh` の設計仕様を記載する。このスクリプトはHSL（Hack Standard Library）プロジェクトの単体テストを実行するためのエントリポイントである。

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

`minitest.sh` は、HHVM環境でHackTestフレームワークを使用した単体テストを実行するシェルスクリプトである。

**業務上の目的・背景**：HSL（Hack Standard Library）の品質保証を目的として、コード変更時やCI/CDパイプライン上で自動的にテストを実行し、リグレッションを検出する。開発者がローカル環境でもテストを簡単に実行できるようにするため、環境変数によるカスタマイズ機能を提供している。

**バッチの実行タイミング**：開発者による手動実行（随時）、およびGitHub Actions CI/CDパイプラインによる自動実行（push時、pull_request時、日次スケジュール）。

**主要な処理内容**：
1. 環境変数 `AUTOLOAD_DB_DIR` の設定（デフォルト: `.var`、`!mkdtemp` 指定時は一時ディレクトリを作成）
2. 環境変数 `HHVM_BIN` の設定（デフォルト: `hhvm`）
3. 作業ディレクトリの調整（`hphp/hsl/.hhconfig` が存在する場合はそのディレクトリに移動）
4. AUTOLOAD_DB_DIR ディレクトリの作成
5. HHVMによる `minitest/main.hack` の実行（コマンドライン引数をそのまま渡す）

**前後の処理との関連**：本スクリプトは `minitest/main.hack` を呼び出すラッパースクリプトである。CI/CDワークフロー（build-and-test.yml）では、hh_client による型チェック後に本スクリプトが実行される。

**影響範囲**：AUTOLOAD_DB_DIR で指定されたディレクトリにautoload.dbファイルが作成される。テスト実行結果は標準出力・標準エラー出力に出力される。

## バッチ種別

テスト実行（シェルスクリプトラッパー）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 / CI/CDパイプラインによる自動実行 |
| 実行時刻 | 随時（CI/CDでは15:42 UTC 日次スケジュール） |
| 実行曜日 | 全曜日（CI/CD日次スケジュール） |
| 実行日 | 毎日（CI/CD日次スケジュール） |
| トリガー | 手動 / push / pull_request / cron |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| HHVM環境 | HHVMがインストールされていること |
| ext_facts拡張 | HHVM ext_facts拡張が有効であること |
| Nativeオートローダー | HHVMネイティブオートローダーが設定されていること |
| HSLソースコード | HSLのソースコードがチェックアウトされていること |

### 実行可否判定

シェルスクリプトとして実行可能であり、HHVM環境が利用可能であれば実行可能。テスト対象クラスが存在しない場合は、`minitest/main.hack` 内でエラー終了する。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| AUTOLOAD_DB_DIR | 環境変数 | No | .var | autoload.dbファイルの格納ディレクトリ。`!mkdtemp` を指定すると一時ディレクトリを作成 |
| HHVM_BIN | 環境変数 | No | hhvm | HHVMバイナリのパス |
| $@ | コマンドライン引数 | No | なし | テストクラス名またはファイルパスによるフィルタリング指定 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| minitest/main.hack | Hackソースファイル | テストランナーのエントリポイント |
| HackTestを継承したテストクラス | Hackソースファイル | テスト対象クラス群 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| 標準出力 | テキスト | テスト実行結果（テストクラス名、メソッド名、OK/SKIPPED表示） |
| 標準エラー出力 | テキスト | エラーメッセージ |
| AUTOLOAD_DB_DIR/autoload.db | バイナリ | HHVMオートローダーキャッシュファイル |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | autoload.db |
| 出力先 | AUTOLOAD_DB_DIR（デフォルト: .var） |
| 文字コード | バイナリ |
| 区切り文字 | N/A |

## 処理フロー

### 処理シーケンス

```
1. 環境変数初期化
   └─ AUTOLOAD_DB_DIRの設定（デフォルト: .var、!mkdtempの場合は一時ディレクトリ作成）
2. HHVMバイナリパス設定
   └─ HHVM_BINの設定（デフォルト: hhvm）
3. 作業ディレクトリ調整
   └─ hphp/hsl/.hhconfigが存在する場合はそのディレクトリに移動
4. ディレクトリ作成
   └─ AUTOLOAD_DB_DIRディレクトリを作成（mkdir -p）
5. テスト実行
   └─ HHVMでminitest/main.hackを実行（exec）
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B{AUTOLOAD_DB_DIR設定済み?}
    B -->|Yes| C{AUTOLOAD_DB_DIR == !mkdtemp?}
    B -->|No| D[AUTOLOAD_DB_DIR = .var]
    C -->|Yes| E[一時ディレクトリ作成]
    C -->|No| F{HHVM_BIN設定済み?}
    D --> F
    E --> F
    F -->|Yes| G{hphp/hsl/.hhconfig存在?}
    F -->|No| H[HHVM_BIN = hhvm]
    G -->|Yes| I[cd hphp/hsl]
    G -->|No| J[mkdir -p AUTOLOAD_DB_DIR]
    H --> G
    I --> J
    J --> K[exec HHVM minitest/main.hack]
    K --> L[スクリプト終了]
```

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

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

本バッチはデータベース操作を行わない。

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| N/A | N/A | N/A | データベース操作なし |

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

N/A（データベース操作なし）

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | ディレクトリ移動失敗 | hphp/hslへのcd失敗 | パスの存在確認 |
| 1 | ext_facts無効 | HH\Facts\enabled()がfalse | HHVMの設定確認 |
| 1 | HSL Systemlib有効 | hhvm.hsl_systemlib_enabled が有効 | HHVMの設定変更 |
| 1 | オートローダー未設定 | HSL関数が見つからない | ネイティブオートローダーの設定 |
| 1 | テストクラスなし | フィルタリング結果が空 | フィルタ条件の確認 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A |

### 障害時対応

スクリプト失敗時はエラーメッセージを確認し、前提条件（HHVM環境、オートローダー設定）を確認する。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | N/A（データベース操作なし） |
| コミットタイミング | N/A |
| ロールバック条件 | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | テストクラス数に依存（数十〜数百クラス） |
| 目標処理時間 | CI/CD環境で数分以内 |
| メモリ使用量上限 | HHVMデフォルト設定に依存 |

## 排他制御

同一ディレクトリでの同時実行は、autoload.dbファイルの競合が発生する可能性がある。異なるAUTOLOAD_DB_DIRを指定することで並列実行可能。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | テストクラス開始時 | "Starting {クラス名}..." |
| 進捗ログ | テストメソッド実行時 | "--- {クラス名}::{メソッド名}()" |
| 終了ログ | テストクラス完了時 | "OK: {クラス名}" |
| スキップログ | テストスキップ時 | "------- SKIPPED: {メッセージ}" |
| エラーログ | エラー発生時 | 標準エラー出力にエラーメッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | GitHub Actions（CI/CD） |
| 処理時間 | CI/CDタイムアウト設定に依存 | GitHub Actions |

## 備考

- プロジェクトルートに配置されるシェルスクリプト
- HHVM固有のオプション（`Eval.HSLSystemlibEnabled=false`, `Autoload.DB.Path`, `Eval.CoeffectEnforcementLevels.zoned=0`）を設定してminitest/main.hackを実行
- `exec` を使用しているため、スクリプト自体はHHVMプロセスに置き換わる
