This skill shows an agent how to run GDScript tests from a terminal or CI and get a process exit code that means something. Its central rule is that Godot’s exit code reflects only what the runner passes to quit(), because script errors, push_error() and failed assert() calls leave it at zero.
It gives a SceneTree test runner that counts failures itself and ends with quit(1) on any failure, a variant for tests that wait on frames, timers or signals, and a GitHub Actions job with an import step and a timeout. It also tells the agent to break one assertion on purpose and confirm the exit code changes before trusting a green run.
What You Get
- A seven-step workflow from checking the binary to verifying that the runner can fail
- A minimal SceneTree runner that counts failures and exits non-zero
- A runner pattern for tests that wait on a frame, a timer or a signal
- A GitHub Actions job with an import step, a step timeout and log output on failure
Common Use Cases
- Adding GDScript unit tests to a GitHub Actions workflow
- Fixing a CI job that hangs after a failed assert
- Finding why a test run exits 0 even though the log shows SCRIPT ERROR lines
- Smoke-running a scene for a few hundred frames and scanning the log
What Makes It Unique
The skill is built around one fact that most test setups miss: Godot errors do not change the exit code. It therefore uses a counter helper, a loop that treats a test that died halfway as a failure, and a final check that a deliberately broken assertion produces exit code 1. It also records hang causes such as a bare assert before quit() and an await on a freed signal source.
Under The Hood
The agent loads the SKILL.md only; the skill ships no scripts or reference files. It tells the agent to run commands in your project: the Godot binary headless to print its version, import the project and run the runner script or a scene, with stdout and stderr redirected to log files that are searched with grep. It also has the agent write a test runner file and, if asked, a GitHub Actions workflow step. It reads and writes project files; it makes no network calls.