自動テストと検証

自動テストは、明示的で機械可読な根拠を使って Defold のコードとコンテンツを検証します。このマニュアルを使って、ローカルスクリプト、継続的インテグレーション（CI、Continuous Integration）のランナー、コーディングエージェントのいずれでも利用できるテストを設計します。モジュールのテスト、実行中のコレクション（collection）、ブラウザーテスト、実行時の自動化、視覚的な確認、画面表示を伴わないヘッドレスビルドを取り上げ、役立つ実践方法を紹介します。

検証のレベル

適切な自動テストのレベル分けは、テストを単体テスト、統合テスト、エンドツーエンド（E2E）テストの3つの主な層に分ける、テストピラミッドの枠組みに従います。Defold では、起動時に読み込める個別のコレクションにテストを分けることができます。通常は、問題を検出できる範囲で最も対象が絞られた、高速な確認から始め、必要に応じて実行時やプラットフォーム別のテストを追加するとよいでしょう。

コンパイルの成功は、プロジェクトをビルドできることを示しますが、ゲームプレイの動作が正しいことまでは示しません。スクリーンショットは、複雑な遷移、アニメーション、操作への反応、ゲームプレイの流れを証明するものではありませんが、現在のマルチモーダルなソリューションを使い、1フレームがどのように見えるか、シェーダーや見た目のレイアウトが正しいかを調べるために利用できます。ただし、自動テストでは、条件を直接表現できる場合は決定論的なアサーションを優先してください。

再利用可能でテストしやすい Lua コード

再利用可能なロジックは、エンジンへの依存を最小限にした Lua モジュールに保持します。そうすると、純粋なデータ変換、ルール、ステートマシン、計算を、完全なゲームワールドを構築せずにテストできます。

エンジンとやり取りするコードを、そのコードが呼び出すロジックから分離します。スクリプトでメッセージやコンポーネントの状態をモジュールへの呼び出しに変換し、テストでは制御された入力を使ってモジュールを直接呼び出せます。

詳細は、コードの記述マニュアルを参照してください。

実行中のコレクションでのテスト

動作がゲームオブジェクト（game object）、コンポーネント、メッセージ、入力、物理、またはその他のエンジンシステムに依存する場合は、専用のテスト用コレクションを使います。

各テストでは、次の手順を実行することをお勧めします。

1. 既知の状態を確立します。
2. 1つの動作を実行します。
3. 期待する結果をアサーションで確認し、評価します。
4. 作成したリソースを後片付けします。
5. 構造化された結果の記述を出力します。

テストには、他から分離したテスト用コレクションを優先してください。プロジェクトでは、game.project の一時的なプロジェクト設定を使って、起動時に読み込まれるテスト用のブートストラップコレクション（bootstrap collection）を選択できます。

[bootstrap]
main_collection = /test/test.collectionc

一時的なテスト用ブートストラップの設定を、プロジェクトの通常の設定に残さないでください。CI では、専用の設定ファイルを Bob に渡す方法を優先してください。CI はリポジトリの状態を変更できません。必要な場合に限り、一時的な変更だけを行うことをお勧めします。

複雑なゲームでは、事前に定義したシナリオと簡単な仮配置を備えた、小さな「開発ルーム」用コレクションを作成できます。これにより、ゲームの仕組みを再現可能にし、無関係なゲームの状態やセクションを通過せずにテストできるため、開発が容易になります。

テストフレームワーク

プロジェクトでは、小さなランナーを実装するか、コミュニティのテストライブラリを使えます。

たとえば、DefTest は Telescope を基にした単体テストライブラリです。テストスイート、セットアップと後片付けの関数、アサーション、名前によるフィルタリング、一部の Defold API のモック、オプションの LuaCov カバレッジをサポートします。テストは専用のブートストラップコレクションから実行でき、Bob で作成したヘッドレスバンドルでも実行できます。

構造化されたテスト結果

フレームワークがコンソールやログに出力する概要は、開発者にとって有用な場合がありますが、無人で動作する自動制御ツールには、それでも明示的な完了結果が必要です。制御ツールがテスト結果を処理しやすいように、必要に応じてフレームワークのコールバックや概要出力を包む小さなアダプターを追加します。

簡単な結果の記述には、一意なプレフィックスの後に JSON オブジェクトを1つ続け、コンソールの物理的な1行ごとに出力する形式を使えます。

TEST {"run":"8f13","event":"suite_start","tests":2}
TEST {"run":"8f13","event":"case","name":"player_moves","status":"pass","duration_ms":3}
TEST {"run":"8f13","event":"case","name":"player_stops","status":"pass","duration_ms":2}
TEST {"run":"8f13","event":"suite_end","status":"pass","passed":2,"failed":0}

収集ツールでは、各行を個別に処理し、TEST プレフィックスを見つけ、その後に続く JSON を解析して、無関係なエンジン出力を無視することをお勧めします。

過去のプロセスや同時に動作しているプロセスの出力によって現在の実行が完了と扱われないように、一意な実行識別子を含めます。各テストスイートでは、曖昧さのない最終イベントを1つ出力することをお勧めします（Pass、Failure、Crash、Timeout など）。

コンソール出力の収集

ゲームをエディターから実行すると、現在のコンソール履歴と継続的なストリームの両方を利用できます。対応するテストスイートの完了イベント、プロセスの終了、エラー、または設定したタイムアウトや行数の上限に達した後に、ストリームを閉じます。

詳細は、エディター HTTP API マニュアルを参照してください。

永続化されたログ

Defold では、game.project の Write Log File を有効にすると、ゲームのログをファイルに保存することもできます。ゲームログとシステムログを参照してください。ファイルへのログ記録は、パッケージ化されたアプリケーションや、エディターのコンソールを利用できない対象デバイスでのテストに役立ちます。

プロジェクトでは、組み込みの print() と pprint() 関数を使うことも、たとえば Asset Portal にある他のログライブラリを使うこともできます。

ランタイム API を使った実行中のゲームのテスト

実行時の自動化 API は、動作中のデバッグエンジンを調べて制御できます。テストで実行時のオブジェクトを探す、入力を注入する、表示される状態を待つ、描画結果を取得する必要がある場合に利用できます。

詳細は、エンジンサービスマニュアルを参照してください。

次の例では、Automation Bridge の Python ヘルパーの構造を使います。プロジェクトには互換性のあるバージョンのデバッグ拡張を含め、指定した自動化 ID を持つ要素を公開し、screen アプリケーション状態を公開する必要があります。

from automation_bridge import editor

project = editor.open_project(".")
game = project.build_and_run()

try:
    play = game.element(automation_id="play_button")
    game.click(play)
    game.wait_for_state("screen", "gameplay", timeout=5.0)
    screenshot = game.screenshot()
    print(screenshot.path)
finally:
    game.close_engine()

アプリケーションで定義した状態や自動化 ID は、Automation Bridge のオプションであるデバッグ専用 Lua API を使います。プロジェクトでこの API を有効にし、状態や ID を公開する必要があります。固定時間の待機は、マシンの速度やフレームのタイミングの影響を受けます。定義した状態を、待機時間の上限を設けてポーリングする方が信頼できます。

Automation Bridge は拡張機能であり、コアエンジンの一部ではありません。インストール済みバージョンでのセレクター、待機、状態、イベント、スクリーンショット、診断については、Python API リファレンスを参照してください。

HTML5 のブラウザーテスト

エディター HTTP API マニュアルで説明しているように、エディターは現在の build-html5 コマンドを使って HTML5 ビルドを作成し、配信できます。Bob でも、エディターを使わずに HTML5 バンドルを作成できます。

Playwright、Puppeteer、Selenium、WebdriverIO、Cypress などの外部ブラウザー自動化ツールでは、次のことができます。

• Defold のキャンバスとアプリケーションの準備が整うまで待機します。
• キーボード、マウス、エミュレートしたタッチの入力を送信します。
• ビューポートのサイズを変更します。
• ブラウザーのコンソール出力と JavaScript エラーを収集します。
• スクリーンショットを撮影し、成果物を比較します。

キャンバスに送った入力は、プロジェクトの通常の入力バインディング（input binding）と on_input() コールバックを通して処理されます。ゲームの応答と、ブラウザー固有の連携箇所の両方をテストします。

最も信頼できる方法は、カスタムの index.html に明示的な JavaScript テスト用ブリッジを公開することです。Defold 側では、HTML5 ビルドで html5.run() を使って JavaScript を実行できるため、このようなブラウザー側のブリッジとの通信が可能になります。JavaScript から Defold に戻るコマンドには、JavaScript からエンジンへの専用ブリッジを使います。

ブラウザーテストには上限を設けます。最終レポートでは、ページの読み込み失敗、キャンバスがない場合、JavaScript エラー、テストのタイムアウト、ゲームのアサーション失敗を区別します。

視覚的な検査のためのエディタープレビューと実行時のスクリーンショット

開いているエディターのデフォルトのシーンビューでリソースファイルのスクリーンショットを作成したり、実行中のゲームでスクリーンショットを作成したりできます。

画像の比較は、たとえば回帰テストに使えます。確認に失敗した場合は、差分画像と比較指標を保存します。

視覚的な検査では、マルチモーダルモデルを使うと、切れたテキスト、重なったコントロール、不明瞭な選択状態、セーフエリアの外にあるコンテンツなど、他の方法では表現しにくい意味上の条件を評価できます。この評価は、明示的な基準に基づく追加の判断材料として扱い、決定論的なロジックの確認や画像比較の代わりにはしないことをお勧めします。

ヘッドレステストと CI

エディターに依存しない CI には、ビルド用 CLI ツールの Bob を使います。

Bob を使うと、依存関係の解決、ゲーム、アーカイブ、スタンドアロンバンドルのビルド、および JSON レポートの生成ができます。

mkdir -p build/reports

java -jar bob.jar \
  --root . \
  --archive \
  --build-report-json build/reports/build-report.json \
  resolve build

専用の設定を使って、ヘッドレスのテスト用バンドルをビルドします。

java -jar bob.jar \
  --root . \
  --settings test/test.settings \
  --platform x86_64-linux \
  --variant headless \
  --archive \
  --bundle-output build/test-bundle \
  resolve build bundle

生成された実行ファイルを、プラットフォームに適したプロセス制御ツールで実行します。終了ステータスとログを取得し、タイムアウトを適用して、構造化されたテストスイートの完了イベントを必須にします。

Bob マニュアルでは、プラットフォーム、設定ファイル、バンドル、キャッシュ、ネイティブ拡張、ビルドレポートについて説明しています。

失敗のレポートと成果物

適切なテスト結果には、失敗を再現して診断できるだけの根拠を残すことをお勧めします。

• テスト名、実行識別子、アサーションの詳細。
• 経過時間と分類した結果。
• 完全なコンソールログまたはプロセスログ。
• Defold のバージョン、対象プラットフォーム、関連する設定。
• Bob のビルドレポートとプロセスの終了ステータス。
• 利用できる場合は、実行時の状態またはシーンのスナップショット。
• スクリーンショット、基準との差分、録画、またはブラウザーのトレース。
• 生成されたすべての成果物へのパスまたはリンク。

開発者、ローカルスクリプト、CI サービス、AI コーディングエージェントが同じ形式を利用できるようにすることをお勧めします。これにより、診断や修正を委任する場合も、検証を決定論的に保てます。