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-testingInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
Development & EngineeringSupported Platforms
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.
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 foundOur 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.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| godot-gdscript-headless-testing (this skill)by gamedev-skills | 94 | 8.9k | 4d ago | SKILL.md |
| taste-skillby Leonxlnx | 100 | 116.8k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| ai-job-searchby ai-job-search-dev | 100 | 72.1k | today | CLAUDE.md |
| claude-howtoby luongnv89 | 100 | 47.3k | 2d ago | CLAUDE.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.
Skill content
View source on GitHubname: 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
.gdtest fails. - Use when debugging why a
godot --headlessinvocation 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
--headlessbuilt in (no export template needed); rungodot --headless --versionand 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_nametypes fail to resolve (Identifier "X" not declared in the current scope) and imported assets fail to load (No loader found for resource: res://...). Rungodot --headless --path <project_dir> --importonce first, in CI and locally. - Write the runner as a
SceneTreescript, not aNodescene. ASceneTreescript's_initialize()runs once before any frame β enough for pure-logic tests and no.tscnrequired to launch. - Track pass/fail counts yourself and call
quit(<code>)explicitly. Do not use bareassert()to fail a test. Godot does not turn the process exit code non-zero onpush_error()by itself β the runner must count failures and callquit(1). Worse, a failedassert()inside_initialize()(official/debug build) printsSCRIPT ERROR: Assertion failedand stops execution beforequit()runs, so the process never exits and CI hangs until its own timeout. Use anassert_eq()-style helper that records the failure and keeps going. - Invoke with
godot --headless --path <project_dir> --script res://<runner>.gdand read the process exit code, not just stdout, from the shell or CI step.--scriptaccepts both ares://-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, anawaitthat never resolves (Pattern #2) hangs the runner forever; atimeout-minuteson the CI step is a backstop CI-side, not a substitute for backing everyawaitwith 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.--scriptaccepts ares://-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, soclass_nametypes and imported assets aren't resolved yet. Rungodot --headless --path <project_dir> --importonce before the test step.- A failed
assert()hangs instead of failing the test β in an official/debug build, a failedassert()inside_initialize()printsSCRIPT ERROR: Assertion failedand stops that function before it reachesquit()β the process never exits and CI waits until its own timeout. Use anassert_eq()counter (Pattern #1) instead of bareassert()in test runners. - Exit code stays 0 despite failed assertions β the runner never called
quit(1), or (Pattern #2) it always callsquit(0)regardless of failures. Track failures yourself and callquit()explicitly with a code that reflects them; do not rely onassert()orpush_error()alone to change the exit code. _initialize()runs before nodes, timers, or signals exist β logic that needs a frame to have processed mustawaita signal or a timer before asserting; see Pattern #2.rootitself is not inside the tree yet, so aTimeradded and started there errors and itstimeoutnever fires (the runner hangs) βawait process_framefirst.- 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
SceneTreescript keeps running until something callsquit(). A test thatawaits a signal that never fires hangs the job forever β always back anawaitwith a timeout node as a fallback, and settimeout-minuteson 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--headlessuse case.
Related Skills
taste-skill
116.8kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu β one CLI, zero API fees.
ai-job-search
72.1kThe job search that runs on your machine. AI job application framework built on Claude Code: evaluate postings, tailor CVs, write cover letters, prep interviews. Fork it and own it.
claude-howto
47.3kA visual, example-driven guide to Claude Code β from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit β see the Safety scan above for what the skill file itself contains.
