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