Godot GDScript headless testing (4.x)
Run GDScript tests from a terminal or CI and get a process exit code that means something.
Targets the Godot 4.7 CLI; --headless is built into every 4.x editor binary.
The one rule behind most of this skill: Godot's exit code only reflects what your runner
passes to quit(). Script errors, push_error() and failed assert() calls do not make
it non-zero, so the runner counts failures itself.
Workflow
- Check the binary:
godot --headless --versionprints a version and opens no window. - Import on every fresh checkout:
godot --headless --path <project> --import..godot/is normally not committed, so without itclass_nametypes do not resolve (Identifier "X" not declared in the current scope) and imported assets fail to load. - Write the runner as a
SceneTreescript (Pattern 1)._initialize()runs before the first frame and needs no.tscn. - Count failures with a helper and end with
quit(1 if failed > 0 else 0). Do not fail tests with bareassert(): in a debug build a failed assert stops_initialize()beforequit(), and the process never exits. - Run it:
godot --headless --path <project> --script res://tests/test_runner.gd(an absolute path to a runner outside the project also works) and read the exit code. - In CI, add the import step, a step timeout, and capture stdout and stderr to files (Pattern 3).
- Verify the runner itself before trusting a green run: break one assertion on purpose and confirm the exit code becomes 1, then put it back. A runner that always exits 0 passes CI forever.
For quick smoke checks without a test file, run a scene for a few hundred frames and scan
the log, since the exit code stays 0 after runtime errors:
godot --headless --path <project> --quit-after 300 res://main.tscn > run.log 2>&1, then
grep -nE "SCRIPT ERROR|^ERROR:" run.log (no match means clean).
Patterns
1. Minimal SceneTree test runner with a real exit code
# res://tests/test_runner.gd
# godot --headless --path . --script res://tests/test_runner.gd
extends SceneTree
var passed := 0
var failed := 0
func _initialize() -> void:
for t: String in ["test_add", "test_load"]:
if call(t) != true: # a runtime error returns null, not true
failed += 1
push_error("FAIL %s: did not finish (runtime error?)" % t)
print("Results: %d passed, %d failed" % [passed, failed])
quit(1 if failed > 0 else 0)
func assert_eq(actual, expected, label: String) -> void:
if actual == expected:
passed += 1
else:
failed += 1
push_error("FAIL %s: expected %s, got %s" % [label, expected, actual])
func test_add() -> bool:
assert_eq(2 + 2, 4, "add")
return true
func test_load() -> bool:
assert_eq(load("res://icon.svg") != null, true, "icon loads")
return trueTests return true on their last line so a test that dies halfway is still counted:
a runtime error such as calling a method on null aborts only that function, which hands
its caller null. For tests that await, use await call(t) in the loop.
2. Tests that need a frame, a timer or a signal
extends SceneTree
var failed := 0
func _initialize() -> void:
await run_tests()
print("Results: %d failed" % failed)
quit(1 if failed > 0 else 0)
func run_tests() -> void:
await process_frame # root joins the tree on the first frame
var timer := Timer.new()
timer.one_shot = true
root.add_child(timer)
timer.start(0.1)
await timer.timeout
if not timer.is_stopped():
failed += 1
push_error("FAIL timer_fires_once")
timer.queue_free()_initialize() may await. Before the first process_frame, root is not inside the tree,
so a Timer started there errors ("not inside the tree") and its timeout never fires.
3. CI step (GitHub Actions)
- name: Import project (fresh checkout has no .godot/)
run: godot --headless --path . --import
- name: Run GDScript tests
timeout-minutes: 5
run: godot --headless --path . --script res://tests/test_runner.gd > test.log 2> test.err
- name: Show test output
if: always()
run: cat test.log test.errThe run: step fails on a non-zero exit code by itself; the discipline lives in the runner's
quit(). timeout-minutes is a backstop for a hung await.
Gotchas
- The job hangs until the CI timeout → a failed bare
assert()stopped_initialize()beforequit()(printsSCRIPT ERROR: Assertion failed); or anawaitwaits on a signal that never fires. Use the counter helper, and race long awaits against a timer. - An
awaitnever returns and nothing errors → the object that emits the signal, or the node running the coroutine, was freed while waiting; Godot drops the coroutine silently. AwaitSceneTreeTimers (create_timer()), which the tree owns, for delays. - Exit code 0 although checks failed → the runner never calls
quit(1), or a test died on a runtime error and was never counted (see Pattern 1'scall(t) != trueloop). - Exit code 0 although the log shows
SCRIPT ERROR→ expected: errors never change the exit code. Scan logs of smoke runs withgrep, as in the workflow. --check-onlyfails withIdentifier not found: SomeAutoload→--check-onlyparses a single script without registering autoloads. Load scripts from a runner instead (godot-gdscriptships a compile check that does).- The log grep flags
... still in use at exitor... leaked at exit→ shutdown leak reports for objects the test created and never freed. Free them (orqueue_free()and wait a frame beforequit()); they are not test failures, so filter them if you must. Identifier "X" not declaredor "No loader found" only in CI → the import step is missing.- Nothing happens or the editor opens →
--headlessis missing or the--scriptpath is wrong;res://paths resolve against--path. The InputMap action "x" doesn't existin a test → the action is not inproject.godot; tests that press inputs can add missing actions withInputMap.add_action(), but the game needs the real Input Map entry.- Output missing or out of order in PowerShell or some CI shells → redirect stdout and stderr to files and read them after the process exits, as in Pattern 3.
Related skills
godot-gdscript: language rules, plus a compile check for every script in the project.godot-2d-movement,godot-animation: ready-made headless tests for controllers and animation states that plug into this runner.godot-export: exporting builds in CI, a different--headlessuse.
Version notes
Last verified: 2026-11-11 with a Godot 4.7.2 headless binary (every behaviour above was reproduced) and the 4.7.2 CLI help.
- Godot 4.7.2 (August 2026) is the current stable release; 4.8 is in beta.
- Sources: Godot releases, Command line tutorial, main.cpp @ 4.7.2.