Godot GDScript headless testing (4.x)
Run GDScript tests from the command line, without the editor GUI, and get a real
process exit code CI can act on. Targets Godot 4.7 headless CLI.
When to use
- Use when a Godot project has no testing addon installed and needs a fast way to
verify GDScript logic (pure functions, resource loading, autoload state) from a
terminal or CI pipeline.
- Use when wiring a CI job that must fail the build when a
.gd test fails.
- Use when debugging why a
godot --headless invocation hangs, opens a window, or
exits 0 despite failing assertions.
When not to use: GDScript syntax or language features themselves →
godot-gdscript; export/build pipeline and platform templates → godot-export
(its own --headless use case, producing a binary, not running tests).
Workflow
- Confirm the binary resolves headless. Godot 4.x ships
--headless built in
(no export template needed); run godot --headless --version and confirm it
prints a version string, not a GUI window.
- On a fresh checkout, import before running tests.
.godot/ is normally not
committed, so a clean checkout has no import cache: class_name types fail to
resolve (Identifier "X" not declared in the current scope) and imported
assets fail to load (No loader found for resource: res://...). Run
godot --headless --path <project_dir> --import once first, in CI and locally.
- Write the runner as a
SceneTree script, not a Node scene. A SceneTree
script's _initialize() runs once before any frame — enough for pure-logic
tests and no .tscn required to launch.
- Track pass/fail counts yourself and call
quit(<code>) explicitly. Do not use
bare assert() to fail a test. Godot does not turn the process exit code
non-zero on push_error() by itself — the runner must count failures and call
quit(1). Worse, a failed assert() inside _initialize() (official/debug
build) prints SCRIPT ERROR: Assertion failed and stops execution before
quit() runs, so the process never exits and CI hangs until its own timeout.
Use an assert_eq()-style helper that records the failure and keeps going.
- Invoke with
godot --headless --path <project_dir> --script res://<runner>.gd
and read the process exit code, not just stdout, from the shell or CI step.
--script accepts both a res://-relative path and an absolute filesystem
path (e.g. a runner outside the project folder); either works.
- Redirect stdout and stderr to files when scripting the invocation from a
wrapper shell (PowerShell, some CI runners).
push_error() output goes to
stderr and can be dropped or reordered when only stdout is captured live.
- Add a step timeout in CI. Even with the
assert() pitfall avoided, an
await that never resolves (Pattern #2) hangs the runner forever; a
timeout-minutes on the CI step is a backstop CI-side, not a substitute for
backing every await with a timeout node.
Patterns
1. Minimal SceneTree test runner with a real exit code
# res://test_runner.gd — run with:
# godot --headless --path . --script res://test_runner.gd
extends SceneTree
var passed := 0
var failed := 0
func _initialize() -> void:
test_add()
print("Results: %d passed, %d failed" % [passed, failed])
quit(1 if failed > 0 else 0) # non-zero exit fails the CI step
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() -> void:
assert_eq(2 + 2, 4, "test_add")
Verified against Godot 4.7.2: godot --headless --path . --script res://test_runner.gd prints Results: N passed, M failed to stdout, routes
push_error lines to stderr, and returns process exit code 0 when
failed == 0, 1 otherwise.
2. Testing something that needs a frame, a timer, or a signal
extends SceneTree
var passed := 0
var failed := 0
func _initialize() -> void:
await run_tests()
print("Results: %d passed, %d failed" % [passed, failed])
quit(1 if failed > 0 else 0) # track and report failures here too
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 run_tests() -> void:
# `root` is not inside the tree yet during _initialize(): a Timer started now
# errors ("not inside the tree") and its `timeout` never fires. Wait one frame.
await process_frame
var timer_node := Timer.new()
timer_node.one_shot = true # default Timer restarts after timeout
root.add_child(timer_node)
timer_node.start(0.1)
await timer_node.timeout
# assertions here can rely on the node having been in the tree for a frame
assert_eq(timer_node.is_stopped(), true, "timer_fires_once")
timer_node.queue_free()
_initialize() may await, which is what makes this pattern work for anything
that needs a node to actually enter the tree, a timer to fire, or a signal to
emit — none of which happen before the engine has processed at least one frame.
Use the same passed/failed counter and assert_eq() helper as Pattern #1;
a version of this pattern that always calls quit(0) can never fail a build.
3. CI step (GitHub Actions) that gates on the exit code
- name: Import project (populates .godot/ on a fresh checkout)
run: godot --headless --path . --import
- name: Run GDScript tests
timeout-minutes: 5
run: godot --headless --path . --script res://test_runner.gd
The import step is required on a clean checkout — without it, class_name types
and imported resources fail to resolve. No extra flag is needed for the test
step itself: the runner already fails the job on a non-zero exit code from
run:; the discipline lives in the runner script's quit() call, not in the CI
configuration. timeout-minutes is a backstop against a hung await (see
Pitfalls), not a substitute for backing every await with a timeout node.
Pitfalls
Script "does nothing" or opens the editor window → missing --headless, or
the script path is wrong. --script accepts a res://-relative path resolved
against --path <project_dir>, and also an absolute filesystem path — both work.
Identifier "X" not declared in the current scope, or a resource fails to
load, only on a fresh checkout → .godot/ (the import cache) is normally not
committed, so class_name types and imported assets aren't resolved yet. Run
godot --headless --path <project_dir> --import once before the test step.
A failed assert() hangs instead of failing the test → in an official/debug
build, a failed assert() inside _initialize() prints SCRIPT ERROR: Assertion failed and stops that function before it reaches quit() — the
process never exits and CI waits until its own timeout. Use an assert_eq()
counter (Pattern #1) instead of bare assert() in test runners.
Exit code stays 0 despite failed assertions → the runner never called
quit(1), or (Pattern #2) it always calls quit(0) regardless of failures.
Track failures yourself and call quit() explicitly with a code that reflects
them; do not rely on assert() or push_error() alone to change the exit code.
A test that hits a runtime error is silently skipped and the run still exits 0 →
an error such as calling a method on null prints SCRIPT ERROR and aborts only that
test function; the runner carries on, nothing was counted as failed, and quit(0) runs.
Declare tests -> bool, end each with return true, and count anything else as a
failure — an aborted function hands its caller a default value instead (await call(t)
works the same for tests that await):
for t: String in ["test_add", "test_load"]:
if call(t) != true:
failed += 1
push_error("FAIL %s: did not finish (runtime error?)" % t)
_initialize() runs before nodes, timers, or signals exist → logic that
needs a frame to have processed must await a signal or a timer before
asserting; see Pattern #2. root itself is not inside the tree yet, so a
Timer added and started there errors and its timeout never fires (the
runner hangs) — await process_frame first.
Output looks empty or out of order from a wrapper shell → some shells
(PowerShell in particular) can reorder or drop a native process's live
stdout/stderr. Redirect both streams to files and read the files after the
process exits, instead of trusting the live console.
Runner never terminates → a SceneTree script keeps running until
something calls quit(). A test that awaits a signal that never fires hangs
the job forever — always back an await with a timeout node as a fallback, and
set timeout-minutes on the CI step as a backstop.
Related skills
godot-gdscript — the language syntax and node lifecycle this pattern's
runner script itself uses.
godot-export — headless CLI export/build, a different --headless use case.
1---2name: godot-gdscript-headless-testing3description: >4 Run GDScript test suites from the command line with `godot --headless`, using a5 SceneTree/MainLoop runner script that exits non-zero on failure so CI can gate6 merges. Use when a Godot project needs unit tests without opening the editor,7 when wiring a CI job (GitHub Actions or similar) that must fail the build on a8 failing `.gd` test, or when a `godot --headless` invocation hangs, opens a9 window, or exits 0 despite failed assertions.10metadata:11 source: https://skillmd.com/skills/junmystery/godot-gdscript-headless-testing12---1314# Godot GDScript headless testing (4.x)1516Run GDScript tests from the command line, without the editor GUI, and get a real17process exit code CI can act on. Targets **Godot 4.7** headless CLI.1819## When to use2021- Use when a Godot project has no testing addon installed and needs a fast way to22 verify GDScript logic (pure functions, resource loading, autoload state) from a23 terminal or CI pipeline.24- Use when wiring a CI job that must fail the build when a `.gd` test fails.25- Use when debugging why a `godot --headless` invocation hangs, opens a window, or26 exits 0 despite failing assertions.2728**When *not* to use:** GDScript syntax or language features themselves →29`godot-gdscript`; export/build pipeline and platform templates → `godot-export`30(its own `--headless` use case, producing a binary, not running tests).3132## Workflow33341. **Confirm the binary resolves headless.** Godot 4.x ships `--headless` built in35 (no export template needed); run `godot --headless --version` and confirm it36 prints a version string, not a GUI window.372. **On a fresh checkout, import before running tests.** `.godot/` is normally not38 committed, so a clean checkout has no import cache: `class_name` types fail to39 resolve (`Identifier "X" not declared in the current scope`) and imported40 assets fail to load (`No loader found for resource: res://...`). Run41 `godot --headless --path <project_dir> --import` once first, in CI and locally.423. **Write the runner as a `SceneTree` script, not a `Node` scene.** A `SceneTree`43 script's `_initialize()` runs once before any frame — enough for pure-logic44 tests and no `.tscn` required to launch.454. **Track pass/fail counts yourself and call `quit(<code>)` explicitly. Do not use46 bare `assert()` to fail a test.** Godot does not turn the process exit code47 non-zero on `push_error()` by itself — the runner must count failures and call48 `quit(1)`. Worse, a failed `assert()` inside `_initialize()` (official/debug49 build) prints `SCRIPT ERROR: Assertion failed` and **stops execution before50 `quit()` runs**, so the process never exits and CI hangs until its own timeout.51 Use an `assert_eq()`-style helper that records the failure and keeps going.525. **Invoke with `godot --headless --path <project_dir> --script res://<runner>.gd`**53 and read the **process exit code**, not just stdout, from the shell or CI step.54 `--script` accepts both a `res://`-relative path and an absolute filesystem55 path (e.g. a runner outside the project folder); either works.566. **Redirect stdout and stderr to files when scripting the invocation from a57 wrapper shell** (PowerShell, some CI runners). `push_error()` output goes to58 stderr and can be dropped or reordered when only stdout is captured live.597. **Add a step timeout in CI.** Even with the `assert()` pitfall avoided, an60 `await` that never resolves (Pattern #2) hangs the runner forever; a61 `timeout-minutes` on the CI step is a backstop CI-side, not a substitute for62 backing every `await` with a timeout node.6364## Patterns6566### 1. Minimal SceneTree test runner with a real exit code6768```gdscript69# res://test_runner.gd — run with:70# godot --headless --path . --script res://test_runner.gd71extends SceneTree7273var passed := 074var failed := 07576func _initialize() -> void:77 test_add()78 print("Results: %d passed, %d failed" % [passed, failed])79 quit(1 if failed > 0 else 0) # non-zero exit fails the CI step8081func assert_eq(actual, expected, label: String) -> void:82 if actual == expected:83 passed += 184 else:85 failed += 186 push_error("FAIL %s: expected %s, got %s" % [label, expected, actual])8788func test_add() -> void:89 assert_eq(2 + 2, 4, "test_add")90```9192Verified against Godot 4.7.2: `godot --headless --path . --script93res://test_runner.gd` prints `Results: N passed, M failed` to stdout, routes94`push_error` lines to stderr, and returns process exit code `0` when95`failed == 0`, `1` otherwise.9697### 2. Testing something that needs a frame, a timer, or a signal9899```gdscript100extends SceneTree101102var passed := 0103var failed := 0104105func _initialize() -> void:106 await run_tests()107 print("Results: %d passed, %d failed" % [passed, failed])108 quit(1 if failed > 0 else 0) # track and report failures here too109110func assert_eq(actual, expected, label: String) -> void:111 if actual == expected:112 passed += 1113 else:114 failed += 1115 push_error("FAIL %s: expected %s, got %s" % [label, expected, actual])116117func run_tests() -> void:118 # `root` is not inside the tree yet during _initialize(): a Timer started now119 # errors ("not inside the tree") and its `timeout` never fires. Wait one frame.120 await process_frame121 var timer_node := Timer.new()122 timer_node.one_shot = true # default Timer restarts after timeout123 root.add_child(timer_node)124 timer_node.start(0.1)125 await timer_node.timeout126 # assertions here can rely on the node having been in the tree for a frame127 assert_eq(timer_node.is_stopped(), true, "timer_fires_once")128 timer_node.queue_free()129```130131`_initialize()` may `await`, which is what makes this pattern work for anything132that needs a node to actually enter the tree, a timer to fire, or a signal to133emit — none of which happen before the engine has processed at least one frame.134Use the same `passed`/`failed` counter and `assert_eq()` helper as Pattern #1;135a version of this pattern that always calls `quit(0)` can never fail a build.136137### 3. CI step (GitHub Actions) that gates on the exit code138139```yaml140- name: Import project (populates .godot/ on a fresh checkout)141 run: godot --headless --path . --import142- name: Run GDScript tests143 timeout-minutes: 5144 run: godot --headless --path . --script res://test_runner.gd145```146147The import step is required on a clean checkout — without it, `class_name` types148and imported resources fail to resolve. No extra flag is needed for the test149step itself: the runner already fails the job on a non-zero exit code from150`run:`; the discipline lives in the runner script's `quit()` call, not in the CI151configuration. `timeout-minutes` is a backstop against a hung `await` (see152Pitfalls), not a substitute for backing every `await` with a timeout node.153154## Pitfalls155156- **Script "does nothing" or opens the editor window** → missing `--headless`, or157 the script path is wrong. `--script` accepts a `res://`-relative path resolved158 against `--path <project_dir>`, and also an absolute filesystem path — both work.159- **`Identifier "X" not declared in the current scope`, or a resource fails to160 load, only on a fresh checkout** → `.godot/` (the import cache) is normally not161 committed, so `class_name` types and imported assets aren't resolved yet. Run162 `godot --headless --path <project_dir> --import` once before the test step.163- **A failed `assert()` hangs instead of failing the test** → in an official/debug164 build, a failed `assert()` inside `_initialize()` prints `SCRIPT ERROR:165 Assertion failed` and stops that function before it reaches `quit()` — the166 process never exits and CI waits until its own timeout. Use an `assert_eq()`167 counter (Pattern #1) instead of bare `assert()` in test runners.168- **Exit code stays 0 despite failed assertions** → the runner never called169 `quit(1)`, or (Pattern #2) it always calls `quit(0)` regardless of failures.170 Track failures yourself and call `quit()` explicitly with a code that reflects171 them; do not rely on `assert()` or `push_error()` alone to change the exit code.172- **A test that hits a runtime error is silently skipped and the run still exits 0** →173 an error such as calling a method on `null` prints `SCRIPT ERROR` and aborts only that174 test function; the runner carries on, nothing was counted as failed, and `quit(0)` runs.175 Declare tests `-> bool`, end each with `return true`, and count anything else as a176 failure — an aborted function hands its caller a default value instead (`await call(t)`177 works the same for tests that `await`):178179 ```gdscript180 for t: String in ["test_add", "test_load"]:181 if call(t) != true:182 failed += 1183 push_error("FAIL %s: did not finish (runtime error?)" % t)184 ```185- **`_initialize()` runs before nodes, timers, or signals exist** → logic that186 needs a frame to have processed must `await` a signal or a timer before187 asserting; see Pattern #2. `root` itself is not inside the tree yet, so a188 `Timer` added and started there errors and its `timeout` never fires (the189 runner hangs) — `await process_frame` first.190- **Output looks empty or out of order from a wrapper shell** → some shells191 (PowerShell in particular) can reorder or drop a native process's live192 stdout/stderr. Redirect both streams to files and read the files after the193 process exits, instead of trusting the live console.194- **Runner never terminates** → a `SceneTree` script keeps running until195 something calls `quit()`. A test that `await`s a signal that never fires hangs196 the job forever — always back an `await` with a timeout node as a fallback, and197 set `timeout-minutes` on the CI step as a backstop.198199## Related skills200201- `godot-gdscript` — the language syntax and node lifecycle this pattern's202 runner script itself uses.203- `godot-export` — headless CLI export/build, a different `--headless` use case.