Testing and debugging (4.7)
Run tests: python scripts/test_run.py [--gd|--cs] [-a res://test/x] [--filter expr] returns {gd: {total, failed, failures: [{test, file, line, msg}]}, cs: {...}}. It imports first, runs headless, and parses the JUnit/console results.
Before tests, compile: ../godot-gdscript/scripts/gd_check.py and ../godot-csharp/scripts/cs_build.py. Smoke-run the game with ../godot-core/scripts/run_godot.py smoke.
GDScript: GdUnit4 (verified 6.2.2 on 4.7.2)
- Install: copy
addons/gdUnit4from the GitHub release (github.com/godot-gdunit-labs/gdUnit4, tag v6.2.x) and enable the plugin. Tests go inres://test/, with names ending in_test.gd. - A suite
extends GdUnitTestSuite. Tests arefunc test_*(). Hooks:before(),after()(per suite),before_test(),after_test(). - Assertions:
assert_int/float/str/bool/vector/array/dict/object(x).is_equal(...),assert_that(x),assert_signal(obj).is_emitted("died")(aftermonitor_signals(obj)),assert_error(func() -> void: ...), andawait assert_func(obj, "is_ready").is_true(). - Memory: wrap created objects in
auto_free(...). The report flags orphan nodes, so treat them as bugs. - Doubles:
mock(Class)+do_return(v).on(m).method(),spy(instance),verify(m, times).method(args),any_int()and friends. - Integration:
var runner := scene_runner("res://player.tscn"), thenrunner.simulate_action_pressed("jump"),await runner.simulate_frames(30),runner.simulate_key_pressed(KEY_SPACE),await runner.await_signal("landed"),runner.invoke("method")andrunner.scene(). - CLI (what
test_run.pycalls):godot --headless --path . -s -d res://addons/gdUnit4/bin/GdUnitCmdTool.gd --ignoreHeadlessMode -c -a res://test. Exit code 0 means pass and 100 means failures. Reports are JUnit XML under the-rddirectory.
C#: gdUnit4Net (verified with Godot.NET.Sdk 4.7.2, .NET 10 SDK)
- Add to the game csproj:
Microsoft.NET.Test.Sdk18.x,gdUnit4.api5.1.0-rc5 (adapter 3.1.1 requires ≥5.1.0-rc5; 5.0.0 fails restore with NU1605),gdUnit4.test.adapter3.1.1,gdUnit4.analyzers1.0.0, plus<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>. - Add a
.runsettingswith<GdUnit4><Parameters>--headless</Parameters><GodotConnectTimeout>60000</GodotConnectTimeout></GdUnit4>. Without it, Godot-runtime tests time out connecting. Run withGODOT_BIN=<godot exe> dotnet test --settings .runsettings. [TestSuite]classes,[TestCase]methods,[Before]/[After]/[BeforeTest]/[AfterTest],[DataPoint(nameof(Cases))]for parameterized tests. Useusing static GdUnit4.Assertions;→AssertThat(x).IsEqual(y),AutoFree(node).[RequireGodotRuntime]is required on any test that touches Godot types, includingMathf, nodes and resources. The analyzer reportsGdUnit0501otherwise. Pure C# tests run without the engine and much faster.- Scenes:
ISceneRunner.Load("res://x.tscn")→SimulateFrames,SimulateActionPressed,AwaitSignal,Invoke.
What to test
Pure logic (damage, inventory, save migration) as fast unit tests. Scenes through scene runners for controller feel, UI flows and signal wiring. Every bug fix gets a regression test. Keep suites fast, because slow suites stop getting run.
Debugging
- Run from the editor (F5) for the full debugger: errors with stack traces, breakpoints (or a
breakpointstatement), step in/out (Step Out arrived in 4.6), the Remote scene tree (live node and property inspection while playing), Profiler, Monitors and ObjectDB snapshots (4.6). - Logging:
print,print_rich("[color=yellow]..."),print_debug(adds file and line),push_warning/push_error(shown in the debugger with a stack, and non-fatal),printerr.assert(cond, "msg")only runs in debug builds, so never put side effects inside it. - File logs:
debug/file_logging/enable_file_logging(on by default for desktop,user://logs/godot.log). Finduser://withOS.get_user_data_dir(). - Custom
Logger(4.5+): subclass it, override_log_error/_log_message, and register withOS.add_logger(). Use it for in-game bug reports withscript_backtraces. Turn ondebug/settings/gdscript/always_track_call_stacksfor release-build backtraces.Engine.capture_script_backtraces()captures one on demand. - CLI:
-d(stdout debugger),--verbose,--debug-collisions/--debug-navigation, and--remote-debug tcp://host:6007to attach a running build to the editor. - C#: attach an IDE debugger to the game process (Rider and VS Code C# Dev Kit can launch Godot with
--path). Exceptions are logged, not fatal, so watch the Output panel.
Reading errors fast
res://file.gd:LINE points at the line. "null instance" means a bad node path or something used before _ready. "previously freed" means an await or callback outlived its node. A "Parse Error" or "Compile Error" stops the script from loading, so everything using it fails, and you fix the first error first. "Condition "!is_inside_tree()" is true" means a tree API was called on a node that isn't in the tree yet. Engine C++ file references (scene/main/node.cpp:123) still mean your call was wrong, so read the stack.
GdUnit suites (unit, mocks, signals, scene runner), C# tests, in-game Logger (compiled by the tests): references/patterns.md