Godot Headless Testing
/godot-gdscript-headless-testing
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.
- GitHub stars
- 2,085 (repository stars as of 2026-10-21)
- License
- Apache-2.0
- Last commit
- 2026/10/09
- By
- gamedev-skills
Part of
Awesome Gamedev Agent Skills
74 portable SKILL.md skills for Godot, Unity, Unreal, Phaser, PixiJS, three.js, Bevy, pygame, LÖVE and Roblox, with a router.
Listed from the author's README. GameSkill has not run this end to end yet. Agent support and install steps are as documented by the author.
Install
npx skills add gamedev-skills/awesome-gamedev-agent-skills --skill godot-gdscript-headless-testingInstalls only this skill. Add -a claude-code (puts it in .claude/skills/), -a codex or -a cursor (.agents/skills/) to choose the agent, and -g to install it for your user instead of the project.
Commands are copied from the project's README. Check the repository before running anything on your machine.
Install for a specific agent
| Agents | -a | Folder |
|---|---|---|
| Claude Code | claude-code | .claude/skills/ |
| Codex | codex | .agents/skills/ |
| Cursor | cursor | .agents/skills/ |
| Gemini CLI | gemini-cli | .agents/skills/ |
| GitHub Copilot | github-copilot | .agents/skills/ |
| OpenCode | opencode | .agents/skills/ |
| Windsurf | windsurf | .windsurf/skills/ |
Add -a <flag> to the command. These are project folders; add -g to install for your user account instead.
What you get
- Worked steps: Minimal SceneTree test runner with a real exit code; Testing something that needs a frame, a timer, or a signal; CI step (GitHub Actions) that gates on the exit code
- A pitfalls section with the mistakes to avoid
Good fit
- 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
- When a `godot --headless` invocation hangs, opens a window, or exits 0 despite failed assertions
Try this prompt
Run my GDScript tests headless in GitHub Actions and fail the build when one fails.About this skill
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.
From the godot-gdscript-headless-testing SKILL.md in gamedev-skills/awesome-gamedev-agent-skills.
What's inside
- Minimal SceneTree test runner with a real exit code
- Testing something that needs a frame, a timer, or a signal
- CI step (GitHub Actions) that gates on the exit code
FAQ
Works well with
Skills the author points to as related or as the better fit for neighbouring tasks.
GDScript for Godot 4
Write idiomatic GDScript for Godot 4.7: static typing, the node lifecycle (_ready/_process/_physics_process), @export/@onready/@tool annotations, signals, and await for asynchronous flow.
Godot Export
Export Godot 4.7 games for desktop, web and mobile: export presets, headless CLI builds for CI, web COOP/COEP and server builds.
More from Awesome Gamedev Agent Skills
See all 432D Platformer
Build a 2D platformer: run/jump control with coyote time, jump buffering, and variable jump height, plus tiled levels and hazards.
Behavior Trees & Utility AI
Build a behavior-tree runtime and a Utility AI system with response curves, plus hybrid agents where the behavior tree drives utility scoring.
Bevy ECS
Structure a Bevy app around ECS: plugins, components and resources, systems with Query and Commands, system ordering and Time.
Card Game
Build a card game: card data, deck/hand/discard zones, draw/shuffle/reshuffle, a turn structure, costs, and effect resolution.
Similar skills
Claude Code Game Studios
Turns Claude Code into a full game studio: 49 agents and 72 workflow skills arranged like a real studio hierarchy.
Balance Check (Claude Code Game Studios)
Find balance outliers, broken progressions, degenerate strategies, economy imbalances in formulas and data.
Launch Checklist (Claude Code Game Studios)
Launch readiness across every department: code, content, store, marketing, community, infrastructure, legal, go/no-go sign-offs.
Godot MCP (Coding-Solo)
MCP server for Godot: launch the editor, run projects, capture debug output and edit scenes.