IronHSP テストランタイム & 自動テストガイド

IronHSP は HSP3 スクリプトの自動テストを書くための専用ランタイムとユーティリティを提供します。 エラー時にモーダルダイアログが出てプロセスが固まる、画面表示をテストで取り出せないといった 従来の HSP の課題を、以下のコンポーネントを組み合わせて解決します。

1. 全体像

自動テストは次の 4 コンポーネントを組み合わせて行います:

ワークフロー

┌─────────────┐           ┌─────────────────────┐
│ test_*.hsp    │           │ iron_test_runner.exe  │
│ (テストスクリプト)  │──────────→│                       │
└─────────────┘           │ (hspcmp64 → .ax →     │
                            │  hsp3cl_net_test_64)   │
                            │  × N 本                │
                            │                       │
                            │ stderr NDJSON 集計      │
                            └──────────┬────────────┘
                                       │
                          ┌────────────┴───────────┐
                          │                          │
                          ▼                          ▼
                ターミナル色付きサマリ          --json=file で機械可読出力

2. テストランタイム (hsp3*_net_test.exe)

hsp3net 系の 4 つのランタイム (GUI / CL × Win32 / x64) を HSP_TEST_MODE プリプロセッサ付きでビルドした版です。ソースコードは本体と完全に共有しており、 #ifdef HSP_TEST_MODE ガードだけで以下の振る舞いが変わります:

• HSP ランタイムエラー発生時にモーダルダイアログを出さず、stderr に JSON で構造化出力する
• dialog 命令を抑止し、OK 応答を自動で返す (テストがブロックされない)
• Alert() / Alertf() などの内部アラートも stderr へ
• CL 版で stop 命令による Press any key 待ちをスキップ
• プロセス終了時に end イベントを出力し、exit code にエラー件数を反映

出力される 4 つの実行ファイル

単体での使い方

rem 通常のコンパイル (デバッグ情報付きが必須)
hspcmp64 -i -u -d -o test.ax test.hsp

rem テストランタイムで実行
hsp3cl_net_test_64 test.ax 2> events.log
echo exit=%errorlevel%

エラーが起きた場合、events.log に以下のようなイベントが残ります:

{"time":"2026-04-18T17:31:50","type":"start","exe":"...hsp3cl_net_test_64.exe","cmdline":"test.ax"}
{"time":"2026-04-18T17:31:50","type":"error","code":19,"line":5,"file":"test.hsp","message":"0で除算しました"}
{"time":"2026-04-18T17:31:50","type":"end","exit":1}

3. hsptestrt.dll — テスト支援プラグイン

テストスクリプトから呼び出す primitive のセットです。 各関数は stderr に直接 WriteFile(STD_ERROR_HANDLE, ...) で JSON を書き込むので、 テストランタイム以外 (通常の hsp3.exe など) でも動作します。 ただし stderr が繋がっていない場合は黙って no-op になります。

読み込み

#include "hsp3cl_net_64.as"    ; 64bit 用プリプロセッサ識別子 _HSP64 を定義
#include "hsptestrt.as"        ; hsptestrt.dll を #uselib

テストケース制御

アサーション / 期待値

型拡張アサーション (Phase 4b)

#func var で変数アドレスを渡すので、int64 変数や配列を直接比較できます。

画像比較 (Phase 4d)

stb_image.h で PNG を読み、ピクセル単位で baseline と current を比較します。 testrt_image_cmp / testrt_image_diff は値を返す #cfunc、 testrt_expect_image_eq は pass/fail を記録する #func です。

ログ / トレース

GUI 自動操作 (hsp3_net_test GUI 向け)

4. iron_test_ex.hsp DSL

hsptestrt の API を毎回フルに書くと冗長なので、薄いマクロ層を用意しています。 マクロのみで関数呼び出しを挟まないため、失敗時の行番号が呼び出し元の ソース位置を指します。

例

#include "hsp3cl_net_64.as"
#include "iron_test_ex.hsp"

test_case "basic arithmetic"
    expect_eq 1+2, 3
    expect_eq 4*5, 20
    assert_true 1 < 2
test_end

test_case "strings"
    s = "hello"
    expect_eq strlen(s), 5
    expect_streq s, "hello"
    expect_strne s, "world"
test_end

test_case "float tolerance"
    expect_feq 0.1 + 0.2, 0.3, 1.0e-9
test_end

trace "reached final section"

end test_finish         ; 失敗件数=プロセス終了コード

マクロ一覧

5. iron_test_runner.exe — 集約ランナー

複数の .hsp をまとめて「コンパイル → テスト実行 → 結果集計」するネイティブ実行ファイルです。 HSP に依存せず Windows の CreateProcess + パイプで子プロセスの stderr を拾うため、 子側がクラッシュしても runner は止まりません。

基本形

iron_test_runner.exe [options] <file-or-glob> [...]

主要オプション

使用例

rem カレントの test_*.hsp を全部走らせる
iron_test_runner.exe --compath=. test_*.hsp

rem ランタイム / コンパイラを明示、JSON 出力
iron_test_runner.exe --compiler=.\hspcmp64.exe ^
                     --runtime=.\hsp3cl_net_test_64.exe ^
                     --compath=. ^
                     --json=results.json ^
                     tests\*.hsp

出力例

[PASS] suite_pass.hsp                   cases:2 pass:5 fail:0  (94ms)
[FAIL] suite_fail.hsp                   cases:2 pass:1 fail:2  (109ms)
       - [one passes one fails] expect_eq  (actual=2 expected=99)
       - [all fail] expect_streq  (actual="hi" expected="bye")
[ERR ] suite_error.hsp                  cases:1 pass:0 fail:0  (109ms)
       error code=19 line=6 file=iron_test_ex.hsp "0で除算しました"

----------------------------------------
files: 1 ok, 1 fail, 1 error  (total 3)
tests: 5 cases, 6 pass, 2 fail  (312ms)

終了コード

exit = failed_expects + error_files です。0 のときだけ all-green。
CI では if errorlevel 1 exit 1 でそのまま合否判定できます。

--json 出力形式

{
  "files": 3,
  "ok": 1,
  "fail": 1,
  "error": 1,
  "total_cases": 5,
  "pass": 6,
  "fail_expects": 2,
  "duration_ms": 296,
  "results": [
    {"path":"suite_pass.hsp","cases":2,"pass":5,"fail":0,"error":false,"ms":93},
    {"path":"suite_fail.hsp","cases":2,"pass":1,"fail":2,"error":false,"ms":109},
    {"path":"suite_error.hsp","cases":1,"pass":0,"fail":0,"error":true,"ms":94}
  ]
}

--junit 出力形式 (CI 連携用)

GitHub Actions / Jenkins / Azure Pipelines など多くの CI が標準対応している JUnit XML 形式で結果を吐き出します。<testsuites> / <testsuite> (ファイル単位) / <testcase> (test_case 単位) の 3 階層構造で、 失敗は <failure>、HSP ランタイムエラーは <error> として記録されます。

<?xml version="1.0" encoding="UTF-8"?>
<testsuites name="iron_test_runner" tests="5" failures="2" errors="1" time="0.298">
  <testsuite name="suite_pass" tests="2" failures="0" errors="0" time="0.125" file="suite_pass.hsp">
    <testcase classname="suite_pass" name="arithmetic"></testcase>
    <testcase classname="suite_pass" name="strings"></testcase>
  </testsuite>
  <testsuite name="suite_fail" tests="2" failures="2" errors="0" time="0.079" file="suite_fail.hsp">
    <testcase classname="suite_fail" name="one passes one fails">
      <failure type="expect_eq" message="expect_eq">actual=2 expected=99</failure>
    </testcase>
    <testcase classname="suite_fail" name="all fail">
      <failure type="expect_streq" message="expect_streq">actual="hi" expected="bye"</failure>
    </testcase>
  </testsuite>
  <testsuite name="suite_error" tests="1" failures="0" errors="1" time="0.094" file="suite_error.hsp">
    <testcase classname="suite_error" name="about to crash"></testcase>
    <testcase classname="suite_error" name="(runtime)">
      <error type="runtime_error" message="0で除算しました">code=19 line=6 file=...</error>
    </testcase>
  </testsuite>
</testsuites>

6. 並列実行 & カバレッジ (Phase 4c / 4e)

--jobs=N で並列実行

スイート間に依存がないので、複数の .hsp を同時にコンパイル+実行できます。 runner は atomic counter によるワークスティーリング方式で N スレッドに配分します。

iron_test_runner.exe --jobs=8 --compath=. test_*.hsp

結果の出力順は入力順と同じになる (各スレッドが自分の結果 slot を書き込む形)。

--coverage でソース行カバレッジ

テストランタイム側にバイトコード dispatch ループの per-step フックがあり、 環境変数 HSPTEST_COV_FILE が設定されているときだけ (file, line) タプルを in-memory set に追加します。runner は各ファイルを走らせるたびに HSPTEST_COV_FILE=<tmp>.cov.tsv を渡し、終了後に全ファイルをマージします。

iron_test_runner.exe --coverage=coverage.tsv --compath=. test_*.hsp

出力 TSV の形式:

file                    line    hits
suite_pass.hsp          5       1
suite_pass.hsp          6       1
suite_pass.hsp          13      3
iron_test_ex.hsp        48      5
...

画面にもサマリが 1 行:

coverage: 4 files, 44 unique lines, 45 hit events  -> coverage.tsv

カバレッジ TSV の後処理例 (Python)

import csv
hits = {}  # (file, line) -> count
with open('coverage.tsv') as fp:
    for row in csv.DictReader(fp, delimiter='\t'):
        hits[(row['file'], int(row['line']))] = int(row['hits'])

# ファイルごとに hit 行数を集計
by_file = {}
for (f, _), c in hits.items():
    by_file.setdefault(f, 0)
    by_file[f] += 1
for f, n in sorted(by_file.items()):
    print(f'{f}: {n} lines')

7. stderr JSON イベント仕様

テストランタイムおよび hsptestrt.dll は、すべてのイベントを 1 行 1 JSON (NDJSON / JSON Lines) 形式で stderr に書き込みます。 改行は LF 1 つで、各行は必ず {...} の形です。

共通フィールド

イベント種別

生ログ例

{"time":"2026-04-18T17:50:33","type":"start","exe":"...hsp3cl_net_test_64.exe","cmdline":"_test_dsl.ax"}
{"time":"2026-04-18T17:50:33","type":"test_begin","case":"basic arithmetic"}
{"time":"2026-04-18T17:50:33","type":"test_end","case":"basic arithmetic","pass":3,"fail":0}
{"time":"2026-04-18T17:50:33","type":"test_begin","case":"a case that fails on purpose"}
{"time":"2026-04-18T17:50:33","type":"expect_fail","case":"a case that fails on purpose","message":"expect_eq","detail":"actual=1 expected=2"}
{"time":"2026-04-18T17:50:33","type":"expect_fail","case":"a case that fails on purpose","message":"expect_streq","detail":"actual=\"abc\" expected=\"xyz\""}
{"time":"2026-04-18T17:50:33","type":"test_end","case":"a case that fails on purpose","pass":0,"fail":2}
{"time":"2026-04-18T17:50:33","type":"test_summary","total":9,"pass":7,"fail":2}
{"time":"2026-04-18T17:50:33","type":"end","exit":2}

8. CI 連携例

GitHub Actions

- name: Run IronHSP tests
  shell: cmd
  run: |
    cd test
    ..\package\win32\iron_test_runner.exe ^
      --compiler=..\package\win32\hspcmp64.exe ^
      --runtime=..\hsp3net\Release_test\hsp3cl_net_test_64.exe ^
      --compath=..\package\win32\common ^
      --junit=test-results.xml ^
      --json=test-results.json ^
      test_*.hsp

- name: Publish JUnit report
  if: always()
  uses: mikepenz/action-junit-report@v4
  with:
    report_paths: test/test-results.xml

- name: Upload test artifacts
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: test-results
    path: |
      test/test-results.xml
      test/test-results.json

ローカル ワンライナー

rem バッチファイル run_tests.bat
@echo off
iron_test_runner.exe --compath=. test_*.hsp
if errorlevel 1 (
    echo TESTS FAILED
    exit /b %errorlevel%
)
echo OK

9. 制約 & FAQ

Q. なぜ hsp3net 限定なの？ vanilla hsp3 は対応しない？

テストランタイム (hsp3*_net_test) は現状 hsp3net ツリーだけをビルド対象にしています。 IronHSP の推奨構成が hsp3net (とくに x64) であり、.NET 連携・NSTRUCT・cfuncst などを含む全機能を 使える唯一のランタイムだからです。vanilla hsp3 側に同じ #ifdef HSP_TEST_MODE ガードを足すことで同じ仕組みに拡張可能ですが、現時点ではやっていません。

Q. コード重複が気になる。本体ランタイムと何が違うの？

ソースコードは 完全に同じファイルを共有しています。vcxproj だけを別途用意し、 プリプロセッサに HSP_TEST_MODE を追加した 4 本を作っています。 #ifdef HSP_TEST_MODE の分岐で、既存のダイアログ出力経路だけ stderr JSON 出力に置換されます。 テスト専用の「フォーク」は存在しないので、本体の修正が自動的にテストランタイムにも追従します。

Q. エラー位置に line フィールドが出ないことがある

HSP の行番号情報は .ax にデバッグ情報が入っている時のみ取得できます。 hspcmp64 -d (または -d 相当) で必ずコンパイルしてください。 iron_test_runner.exe は自動的に -d を付けて呼ぶので通常は気にする必要はありません。

Q. GUI ランタイムで stderr が見えない

GUI アプリはコンソールを持たないため、そのままだと stderr が捨てられます。 テストランタイムは以下の優先順で出力先を解決します:

1. 呼び出し側が 2>file でリダイレクトしていれば、そのハンドルをそのまま使う
2. 親コンソールがあれば AttachConsole(ATTACH_PARENT_PROCESS) + CONOUT$ で出す
3. 環境変数 HSPTEST_STDERR_FILE が設定されていればそのパスに追記

iron_test_runner.exe から呼ぶ場合はパイプで拾うので常に (1) のルートが有効です。

Q. screenshot が真っ黒になる

testrt_screenshot は GetDC(hwnd) + BitBlt で取得します。 Direct3D や DirectComposition でレンダリングしているウィンドウは BitBlt で取れないため真っ黒になる場合があります。 その場合は OS の PrintWindow(PW_RENDERFULLCONTENT) を使う版を追加する必要があります (未実装)。

Q. 失敗件数が大きすぎて exit code 255 を超える

Windows の exit code は 32bit なのでオーバーフローはしませんが、 シェルによっては下位 8bit しか見ないケースがあります (bash など)。 255 件以上の失敗がある場合は --json 出力の fail_expects を参照してください。

Q. stop / end / await がどう扱われるか

CL テストランタイムでは stop 命令は Press any key 表示せず即終了します。 end 数値 のときは数値が exit code になります (テストが end test_finish パターンを使う理由)。await はそのまま動作するので、タイミング依存のテストも書けます。

最終更新: 2026-04-18 — IronHSP Test Runtime Phase 1 + Phase 2 + Phase 3
関連ドキュメント: IronHSP_specification.html / iron_modules_intro.html