youichi-uda/godot-qa

Godot QA is an automated playtest runner for games built in Godot 4. It plugs into a CI pipeline so that every time code is pushed, a headless copy of Godot launches the game's scenes, replays a scripted sequence of inputs, checks node values and on screen text against expected results, compares screenshots against saved baseline images, and fails the build if anything does not match. It needs no Godot editor plugin activation. It is a single script written in pure GDScript with no extra dependencies. There are two modes: a logic mode that runs fully headless without any GPU, usable on any CI runner, and a visual mode that actually renders the game so screenshots can be pixel compared against baselines. Results come out as JSON and optionally JUnit XML, so failures show up directly inside GitHub's test result view, and the tool exits with code 0 for success or 1 for failure so it works as a normal CI gate. A test scenario is written as a simple JSON file describing which scene to load and a list of steps: pressing input keys or actions, waiting a fixed time or until a node appears, asserting a node property or on screen text, and taking a named screenshot that gets diffed against a saved baseline if one exists. Notably, this scenario format matches the format used by a separate paid tool called Godot MCP Pro, which lets AI coding assistants control the Godot editor directly. That means a developer could have an AI assistant write and run a test scenario live while building a feature, then commit that same JSON file so Godot QA replays it automatically on every future push. Godot QA itself does not require that other tool and works entirely on its own, for free. It can also be run locally from the command line outside of CI, and ships as a ready made GitHub Action with configurable inputs like the Godot version, scenario path, and report locations. It requires Godot 4.4 or newer and works on Windows, macOS, and Linux. The project is released under the MIT license.