gamedev-skills/awesome-gamedev-agent-skills

godot-gdscript-headless-testing

Runs Godot 4.7 GDScript tests with godot --headless and a SceneTree runner that exits non-zero on failure, so CI can gate merges.

Voir la source

Mode d’emploi

  1. Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
  2. Consultez le document original pour les outils, identifiants et environnements requis.
  3. Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-gdscript-headless-testing

Avant de commencer

  • L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
  • Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Document Skill original

Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.

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

  1. Check the binary: godot --headless --version prints a version and opens no window.
  2. Import on every fresh checkout: godot --headless --path <project> --import.

.godot/ is normally not committed, so without it class_name types do not resolve (Identifier "X" not declared in the current scope) and imported assets fail to load.

  1. Write the runner as a `SceneTree` script (Pattern 1). _initialize() runs before the

first frame and needs no .tscn.

  1. Count failures with a helper and end with `quit(1 if failed > 0 else 0)`. Do not fail

tests with bare assert(): in a debug build a failed assert stops _initialize() before quit(), and the process never exits.

  1. 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.

  1. In CI, add the import step, a step timeout, and capture stdout and stderr to files

(Pattern 3).

  1. 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

gdscript
# 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 true

Tests 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

gdscript
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)

yaml
- 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.err

The 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()

before quit() (prints SCRIPT ERROR: Assertion failed); or an await waits on a signal that never fires. Use the counter helper, and race long awaits against a timer.

  • An `await` never 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. Await SceneTreeTimers (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's call(t) != true loop).

  • Exit code 0 although the log shows `SCRIPT ERROR` → expected: errors never change the

exit code. Scan logs of smoke runs with grep, as in the workflow.

  • `--check-only` fails with `Identifier not found: SomeAutoload` → --check-only parses a

single script without registering autoloads. Load scripts from a runner instead (godot-gdscript ships a compile check that does).

  • The log grep flags `... still in use at exit` or `... leaked at exit` → shutdown leak

reports for objects the test created and never freed. Free them (or queue_free() and wait a frame before quit()); they are not test failures, so filter them if you must.

  • `Identifier "X" not declared` or "No loader found" only in CI → the import step is

missing.

  • Nothing happens or the editor opens → --headless is missing or the --script path is

wrong; res:// paths resolve against --path.

  • `The InputMap action "x" doesn't exist` in a test → the action is not in

project.godot; tests that press inputs can add missing actions with InputMap.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 --headless use.

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.

du même dépôt

Autres Skills

Tous les Skills
gamedev-skills
Communauté

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

Installations / 24h
433
GitHub Stars
10 k
Mis à jour
12 nov.
gamedev-skills
Communauté

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

Installations / 24h
431
GitHub Stars
10 k
Mis à jour
12 nov.
gamedev-skills
Communauté

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

Installations / 24h
365
GitHub Stars
10 k
Mis à jour
12 nov.
gamedev-skills
Communauté

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

Installations / 24h
360
GitHub Stars
10 k
Mis à jour
12 nov.