godot-gdscript-headless-testing

1# Godot GDScript headless testing (4.x)
2 
3Run GDScript tests from the command line, without the editor GUI, and get a real
4process exit code CI can act on. Targets **Godot 4.7** headless CLI.
5 
6## When to use
7 
8- Use when a Godot project has no testing addon installed and needs a fast way to
9  verify GDScript logic (pure functions, resource loading, autoload state) from a
10  terminal or CI pipeline.
11- Use when wiring a CI job that must fail the build when a `.gd` test fails.
12- Use when debugging why a `godot --headless` invocation hangs, opens a window, or
13  exits 0 despite failing assertions.
14 
15**When *not* to use:** GDScript syntax or language features themselves →
16`godot-gdscript`; export/build pipeline and platform templates → `godot-export`
17(its own `--headless` use case, producing a binary, not running tests).
18 
19## Workflow
20 
211. **Confirm the binary resolves headless.** Godot 4.x ships `--headless` built in
22   (no export template needed); run `godot --headless --version` and confirm it
23   prints a version string, not a GUI window.
242. **On a fresh checkout, import before running tests.** `.godot/` is normally not
25   committed, so a clean checkout has no import cache: `class_name` types fail to
26   resolve (`Identifier "X" not declared in the current scope`) and imported
27   assets fail to load (`No loader found for resource: res://...`). Run
28   `godot --headless --path <project_dir> --import` once first, in CI and locally.
29…