godot-testing-patterns

判定ツリー → スクリプト

必要なもの	選択肢	スクリプト（選択した場合は必須）
純粋なロジック／ツリーなし	ユニット	basic_unit_test.gd、mock_dependency_test.gd、test_data_factory.gd
インスタンス化後のノード操作	シーン統合	scene_integration_test.gd、integration_test_base.gd
シグナルの契約	ユニットまたはシーン	signal_emission_test.gd
複数フレーム／物理ステップ	非同期シーン	wait_for_frame_test.gd、physics_collision_test.gd
不安定な物理挙動／タイミング競合	フレームステップゲート	必須 wait_for_frame_test.gd — 実時間でのスリープは使用しないでください
CI／ディスプレイなし	ヘッドレスゲート	必須 headless_test_runner.gd
保存／UI のリグレッション	スナップショット	必須 snapshot_tester.gd
稼働中のピアなしでの RPC	モックネットワーク	必須 mock_network_provider.gd
CI でのパフォーマンス予算	ベンチマークゲート	performance_benchmark_runner.gd
スイート実行後の孤立ノード	リーク検出	memory_leak_detector.gd
エッジ入力空間	ファズテスト	parameter_fuzz_tester.gd

読み込まないでください：assert カタログのチュートリアルや手動のゲームプレイチェックリストをコンテキストに読み込まないでください。行を選び、スクリプトを読み、実装してください。

必須のトリガー

• CI／--headless：必ず最初に headless_test_runner.gd を読んでください（OS.exit_code、GdUnit4 CLI：godot --headless -s addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://test）。
• 状態またはビジュアルのゴールデンファイル：JSON／画像のゴールデンファイルを書き込む前に snapshot_tester.gd を読んでください。承認ワークフロー： 最初の実行で参照を保存します。意図的に UI を変更した場合は、res://tests/snapshots/<name>.png を削除または上書きして再実行し、新しいゴールデンファイルを生成してコミットしてください。PNG のバイト列を手動で編集しないでください。
• RPC／MultiplayerSynchronizer のテスト：実際のピアを立ち上げる前に、必ず mock_network_provider.gd を読んでください。

利用可能なスクリプト

basic_unit_test.gd

純粋なロジック向けの最小限の GdUnit4（GdUnitTestSuite）構成です。

signal_emission_test.gd

疎結合アーキテクチャ向けのシグナル発行監視です。

mock_dependency_test.gd

外部サービスを分離するためのモック／テストダブルです。

scene_integration_test.gd / integration_test_base.gd

シーンのライフサイクルとノード操作のフィクスチャです。

headless_test_runner.gd

CI のヘッドレス実行のオーケストレーションと終了コードです。

snapshot_tester.gd

Dictionary／UI のゴールデンスナップショット比較です。

mock_network_provider.gd

RPC テスト用のループバック／オフラインマルチプレイヤーピアです。

performance_benchmark_runner.gd

マイクロ秒タイマーと Performance モニターのゲートです。

memory_leak_detector.gd

長時間のスイート実行における孤立ノード検出です。

parameter_fuzz_tester.gd

エッジケースのクラッシュを検出するためのランダム化範囲です。

wait_for_frame_test.gd / physics_collision_test.gd

フレーム／物理ステップの非同期検証です。

test_data_factory.gd

スキーマに準拠したフィクスチャビルダーです。

GdUnit4 のテストで絶対にしてはいけないこと

• プライベートな実装詳細を絶対にテストしない — 公開されている振る舞いだけを検証してください。
• テスト間で変更可能な状態を絶対に共有しない — テストごとに新しくセットアップしてください（before_test／同等の処理）。
• 実時間の sleep や、根拠のないタイマーを絶対に使わない — wait_for_frame パターンで使われるフレームステッパーを優先してください。
• クリーンアップを絶対に省略しない — 各テストの後にインスタンス化したノードを解放してください。
• 乱数をシードせずにテストしない。
• signal_emission_test.gd の GdUnit シグナルアサート／モニターヘルパーを使わずに、シグナルを絶対に検証しない。
• 1 つのテストスイートで GUT と GdUnit4 の API を絶対に混在させない。
• CI でエディター専用機能に絶対に依存しない — ヘッドレスで実行できるテストのみを使用してください。
• 最初からフルレベルの統合テストを行わない — 単体テストと小規模なシーンテストを優先し、判断ツリーで必要とされた場合にのみ規模を拡大してください。
• 壊れやすい絶対ファイルパスをフィクスチャにハードコードしない。
• サードパーティ製プラグインの内部をテストしない — 自分の統合部分だけをテストしてください。

エキスパート向けの要点

• スナップショット：シリアライズ → ゴールデンと比較（snapshot_tester.gd）；承認されたビジュアル変更では、参照 PNG を再生成してください。
• CI：--headless を使用し、失敗時には OS.exit_code をゼロ以外に設定します（headless_test_runner.gd）。
• ネットワーク：実際の ENet の前に、ピアをモックします（mock_network_provider.gd）。
• パフォーマンス：ベンチマークランナーで Performance モニター／描画コール数の上限を使用します。

詳細なレシピ（必要に応じて）

LLM の知識前提ルール：一般的なエージェントが読む前には知らない情報は、ここか scripts/ に記載します。削除せず、移動してください。

トピック	リファレンス
スナップショット／CI／ファジング／パフォーマンス	expert-testing-patterns.md
リリース時のスモークテストチェックリスト	manual-testing-checklist.md

リファレンス

段階的な情報開示：特定の API を調査する場合にのみ公式ドキュメントへのリンクを開き、関連するドメインへ引き継ぐ場合にのみ関連スキルを読み込んでください。全体を事前に読み込まないでください。

公式ドキュメント

• コマンドラインのチュートリアル — CI テストランナー向けの --headless、-s、終了コードのパターンです。
• デバッグツールの概要 — テスト失敗の原因をエンジン側で診断する必要がある場合のデバッガー、プロファイラー、リモートインスペクトについて説明しています。
• カスタムパフォーマンスモニター — ベンチマークのゲートや孤立オブジェクトの検出に使う Performance モニターとカスタムメトリクスについて説明しています。
• アイドル処理と物理処理 — wait_frames／yield ヘルパーが考慮する必要があるフレーム／_physics_process のタイミングについて説明しています。
• SceneTree の使用 — ヘッドレスオーケストレーターで使うツリーのライフサイクル、quit()、プロセスモードについて説明しています。
• ノードとシーンインスタンス — シーン統合テストにおけるインスタンス化、add_child、free の適切な扱いについて説明しています。
• シグナルを使ったインスタンス化 — シグナル発行テストで検証するシグナル接続のパターンについて説明しています。
• ハイレベルマルチプレイヤー — OfflineMultiplayerPeer またはレイテンシーシミュレーターを使ってモック化する RPC／ピア API について説明しています。
• InputEvent の使用 — ファズテストや UI 操作テスト向けの合成 InputEvent* の注入について説明しています。
• 乱数生成 — 決定論的なファズテストやモンテカルロハーネスに使うシード設定について説明しています。
• ゲームの保存 — ゴールデン JSON やセーブ／ロード統合テストの基盤となるシリアライズ／デシリアライズのパターンについて説明しています。
• 物理入門 — 衝突統合テスト向けのレイヤー／マスクとステップのタイミングについて説明しています。

関連スキル

前提条件

• godot-project-foundations — res://test/ テストスイートを構築する前に確認する、プロジェクトのレイアウト、シーン、リソースについて説明しています。
• godot-gdscript-mastery — すべての単体テスト／統合テストで使う、型付き GDScript、await、assert の慣用句について説明しています。
• godot-signal-architecture — watch_signals／シグナルモニターで検証する emit／connect の契約について説明しています。

補完

• godot-debugging-profiling — 赤くなったテストで、assertを追加するのではなく実行時の証拠が必要な場合に使う、プロファイラーとObjectDBのツールです。
• godot-scene-management — シーン統合フィクスチャで再現される、シーンのパック／読み込みパターンです。
• godot-input-handling — ファズテストとUIの押下テストで検証される、アクションマップとイベント解析です。
• godot-2d-physics — 物理衝突テストで正常に保つ必要がある、レイヤーマトリクスとボディAPIです。
• godot-resource-data-patterns — テストデータファクトリーとスナップショット辞書がシリアライズするResourceスキーマです。
• godot-save-load-systems — セーブ／ロードの統合テストとゴールデン状態テストで対象となる、永続化パイプラインです。

下流／利用者

• godot-monte-carlo-balancer — Phase 7のゴールデンセルでこれらのハーネスを再利用する、シード付きヘッドレスゲームプレイシミュレーションです。
• godot-performance-optimization — CIのパフォーマンスゲート（Performanceモニター、ドローコール上限）で適用される予算です。
• godot-multiplayer-networking — モックピアと遅延の注入を通じて検証される、RPC／レプリケーションロジックです。
• godot-export-builds — 同じ--headlessテストエントリーポイントを呼び出す、ヘッドレスエクスポート／CIパイプラインです。

マスター

• godot-master — スキルを横断した探索に使う、ライブラリルーターおよびミラーされたモジュールエントリーです。