SkillAgentSearch 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. Owns Godot tests in CI. Use for GitHub Actions jobs or a headless run that hangs or exits 0 despite SCRIPT ERROR lines.

Install / Use

npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill godot-gdscript-headless-testing

Installs into whichever agent you are using.

About this skill
πŸ“„

SKILL.md

Installable skill definition

Quality Score

94/100

Supported Platforms

Universal

Our assessment of godot-gdscript-headless-testing

godot-gdscript-headless-testing scores 94/100 on our quality scale, 434th of 4,700 Development & Engineering skills we index (top 10%).

Its SKILL.md is 8.9 KB long, well organised into 11 sections with 3 code examples: a thorough specification that gives an agent plenty to work with.

With 8,904 GitHub stars, it is one of the more widely adopted skills in the catalogue.

Substance
29/30
Structure
18/20
Description
15/15
Adoption
17/20
Freshness
15/15

Maintenance, license and trust

  • The repository was last updated 4 days ago, so godot-gdscript-headless-testing is actively maintained.
  • Our last check on 2026-11-16 found the source still online.
  • It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
  • Its trust signals score 100/100, with no cautions. These come from repository metadata, not a code audit β€” read the skill file before letting an agent act on it.

Safety scan

No issues found

Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful.

AI review by kimi-k2.7-code on 2026-10-04. Automated pattern scan on 2026-10-04. It catches known dangerous patterns, not every risk β€” read a skill before letting an agent act on it.

godot-gdscript-headless-testing compared with similar skills

All 4 of these similar skills score higher than godot-gdscript-headless-testing; compare them before choosing.

SkillScoreStarsUpdatedFormat
godot-gdscript-headless-testing (this skill)by gamedev-skills948.9k4d agoSKILL.md
taste-skillby Leonxlnx100116.8k8d agoCLAUDE.md
Agent-Reachby Panniantong100112.3k8d agoCLAUDE.md
ai-job-searchby ai-job-search-dev10072.1ktodayCLAUDE.md
claude-howtoby luongnv8910047.3k2d agoCLAUDE.md

Frequently asked questions

How do I install godot-gdscript-headless-testing?
Run npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill godot-gdscript-headless-testing. The install tabs above show the steps for each supported agent.
Which AI agents does godot-gdscript-headless-testing work with?
It is written for Universal, as a SKILL.md file. Other agents that read the same format can often use it too.
Is godot-gdscript-headless-testing safe to use?
Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review of the same text found nothing harmful. It is Apache-2.0-licensed and scores 100/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
Is godot-gdscript-headless-testing still maintained?
The repository was last updated 4 days ago, so godot-gdscript-headless-testing is actively maintained.

name: godot-gdscript-headless-testing description: > Run GDScript test suites from the command line with godot --headless, using a SceneTree/MainLoop runner script that exits non-zero on failure so CI can gate merges. Use when a Godot project needs unit tests without opening the editor, when wiring a CI job (GitHub Actions or similar) that must fail the build on a failing .gd test, or when a godot --headless invocation hangs, opens a window, or exits 0 despite failed assertions.

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  • _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.

Related Skills

View on GitHub
GitHub Stars8.9k
CategoryDevelopment
Updated4d ago
Forks905

Languages

Python

Trust signals

100/100

From repository metadata: license, adoption, age and documentation. Not a code audit β€” see the Safety scan above for what the skill file itself contains.

No cautions
godot-gdscript-headless-testing β€” Universal Skill: Install & Safety Check | SkillAgent