Communityコーディング&開発github.com

godot-testing-debug

Godot 4.7プロジェクトのテストとデバッグを行います。GdUnit4(GDScript)およびgdUnit4Net(C#)を使用したユニットテスト、シーンランナー、モック、シグナルアサート、入力シミュレーション、ヘッドレス実行、デバッガー、ブレークポイント、カスタムLogger、バックトレース、エラー読み取りをサポートします。テストの作成・実行やバグ・クラッシュの追跡に最適です。

godot-testing-debug とは?

このスキルは、Godot 4.7プロジェクトにおけるテスト駆動開発とデバッグ作業を効率化するための包括的なツールセットです。GDScript向けのGdUnit4(v6.2.2)とC#向けのgdUnit4Net(v5.1.0-rc5)の両方をサポートし、ユニットテスト、シーンランナーを使った統合テスト、モック・スパイによるテストダブル、シグナルアサート、入力シミュレーション、ヘッドレス実行(JSON形式の結果出力)などを実現します。 主な機能として、`test_run.py`スクリプトによるテストの自動実行(テスト前にGDScriptのチェックとC#のビルドを自動実行)、テスト結果のJUnit/JSONパース、アサーションAPI(assert_int/str/vector/signalなど)、auto_freeによるメモリリーク防止、`[RequireGodotRuntime]`属性によるC#テストの高速化、カスタムLoggerによるファイルログやバックトレース取得、デバッガ(F5起動、ブレークポイント、ステップ実行、Remoteシーンツリー、プロファイラなど)が含まれます。 CLIから`-d`(デバッグ出力)、`--verbose`、`--remote-debug`によるエディタ連携も可能で、C#ではIDEデバッガのアタッチにも対応しています。エラー解析では、`res://file.gd:LINE`形式の行番号や「null instance」「previously freed」などの典型的なエラーパターンを迅速に特定するためのガイドも提供しています。 ワークフローとしては、まず`python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr]`でテストを実行し、JSON形式の結果を取得。バグ修正時には必ずリグレッションテストを追加し、純粋なロジックは高速なユニットテスト、シーン操作はシーンランナーでテストするという使い分けを推奨しています。デバッグ時はエディタのF5起動からブレークポイント設定、ステップ実行、Remoteシーンツリーによるノード監視が行え、さらにカスタムLoggerを導入すればゲーム内でもスタックトレース付きのバグレポートを収集できます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/EL4CTEO/godot-skills/tree/main/skills/godot-testing-debug

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

テストとデバッグ (4.7)

テストの実行: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] は {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}} を返します。最初にインポートし、ヘッドレスで実行し、JUnit/コンソールの結果を解析します。 テストの前にコンパイル: ../godot-gdscript/scripts/gd_check.py と ../godot-csharp/scripts/cs_build.py。../godot-core/scripts/run_godot.py smoke でゲームをスモーク実行します。

GDScript: GdUnit4 (4.7.2 上で 6.2.2 を確認済み)

  • インストール: GitHub リリース (github.com/godot-gdunit-labs/gdUnit4、タグ v6.2.x) から addons/gdUnit4 をコピーし、プラグインを有効にします。テストは res://test/ に配置し、名前は _test.gd で終わるようにします。
  • スイートは extends GdUnitTestSuite です。テストは func test_*() です。フック: before()、after() (スイートごと)、before_test()、after_test()。
  • アサーション: assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...)、assert_that(x)、assert_signal(obj).is_emitted("died") (monitor_signals(obj) の後)、assert_error(func() -> void: ...)、および await assert_func(obj, "is_ready").is_true()。
  • メモリ: 作成したオブジェクトを auto_free(...) でラップします。レポートは孤立ノードをフラグするので、それらをバグとして扱います。
  • ダブル: mock(Class) + do_return(v).on(m).method()、spy(instance)、verify(m, times).method(args)、any_int() など。
  • 統合: var runner := scene_runner("res://player.tscn")、次に runner.simulate_action_pressed("jump")、await runner.simulate_frames(30)、runner.simulate_key_pressed(KEY_SPACE)、await runner.await_signal("landed")、runner.invoke("method") と runner.scene()。
  • CLI (test_run.py が呼び出すもの): godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test。終了コード 0 は成功、100 は失敗を意味します。レポートは -rd ディレクトリの下の JUnit XML です。

C#: gdUnit4Net (Godot.NET.Sdk 4.7.2、.NET 10 SDK で確認済み)

  • ゲームの csproj に追加: Microsoft.NET.Test.Sdk 18.x、gdUnit4.api 5.1.0-rc5 (アダプター 3.1.1 には ≥5.1.0-rc5 が必要; 5.0.0 は NU1605 で復元に失敗)、gdUnit4.test.adapter 3.1.1、gdUnit4.analyzers 1.0.0、および <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>。
  • <GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4> を含む .runsettings を追加します。これがないと、Godot ランタイムテストの接続がタイムアウトします。GODOT_BIN=<godot exe> dotnet test --settings .runsettings で実行します。
  • [TestSuite] クラス、[TestCase] メソッド、[Before]/[After]/[BeforeTest]/[AfterTest]、パラメータ化テスト用の [DataPoint(nameof(Cases))]。using static GdUnit4.Assertions; → AssertThat(x).IsEqual(y)、AutoFree(node) を使用します。
  • [RequireGodotRuntime] は、Mathf、ノード、リソースを含む Godot 型に触れるすべてのテストで必要です。そうしないと、アナライザーは GdUnit0501 を報告します。純粋な C# テストはエンジンなしで実行され、はるかに高速です。
  • シーン: ISceneRunner.Load("res://x.tscn") → SimulateFrames、SimulateActionPressed、AwaitSignal、Invoke。

何をテストするか

純粋なロジック(ダメージ、インベントリ、セーブマイグレーション)は高速な単体テストとして。シーンはシーンランナーを通じて、コントローラーのフィーリング、UI フロー、シグナル配線をテストします。すべてのバグ修正には回帰テストを追加します。スイートは高速に保ちます。低速なスイートは実行されなくなります。

デバッグ

  • エディタから実行 (F5) してフルデバッガーを使用: スタックトレース付きエラー、ブレークポイント(または breakpoint ステートメント)、ステップイン/アウト(Step Out は 4.6 で追加)、Remote シーンツリー(再生中のライブノードとプロパティの検査)、プロファイラー、モニター、ObjectDB スナップショット (4.6)。
  • ロギング: print、print_rich("[color=yellow]...")、print_debug(ファイルと行を追加)、push_warning/push_error(スタックと共にデバッガーに表示され、致命的ではない)、printerr。assert(cond, "msg") はデバッグビルドでのみ実行されるため、その中に副作用を決して入れないでください。
  • ファイルログ: debug/file_logging/enable_file_logging(デスクトップではデフォルトでオン、user://logs/godot.log)。user:// は OS.get_user_data_dir() で見つけます。
  • カスタム Logger (4.5+): サブクラス化し、_log_error/_log_message をオーバーライドし、OS.add_logger() で登録します。script_backtraces を使用してゲーム内バグレポートに使用します。リリースビルドのバックトレースのために debug/settings/gdscript/always_track_call_stacks をオンにします。Engine.capture_script_backtraces() はオンデマンドで 1 つをキャプチャします。
  • CLI: -d(標準出力デバッガー)、--verbose、--debug-collisions/--debug-navigation、そして --remote-debug tcp://host:6007(実行中のビルドをエディタにアタッチするため)。
  • C#: IDE デバッガーをゲームプロセスにアタッチします(Rider と VS Code C# Dev Kit は --path で Godot を起動できます)。例外はログに記録されますが、致命的ではないため、出力パネルを確認します。

エラーの高速な読み方

res://file.gd:LINE は行を指します。「null instance」は、不正なノードパス、または _ready の前に使用された何かを意味します。「previously freed」は、await またはコールバックがノードよりも長生きしたことを意味します。「Parse Error」または「Compile Error」はスクリプトのロードを停止させるため、それを使用するすべてが失敗し、最初のエラーを最初に修正します。「Condition "!is_inside_tree()" is true」は、まだツリーにないノードに対してツリー API が呼び出されたことを意味します。エンジンの C++ ファイル参照 (scene/main/node.cpp:123) は、それでも あなたの 呼び出しが間違っていたことを意味するため、スタックを読みます。

GdUnit スイート(ユニット、モック、シグナル、シーンランナー)、C# テスト、ゲーム内 Logger(テストによってコンパイル済み): references/patterns.md

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

関連スキル