GUT: a GDScript unit testing framework for Godot 4

What GUT solves, and who it is written for

GUT exists because Godot projects written in gdscript had no in-engine way to assert that a function returns what it should. The README states the goal plainly: it allows you to write tests for your gdscript in gdscript. That single sentence rules out a lot of adjacent tools. This is not a general test runner that happens to know about scenes, and it is not a C# testing story. It is a framework that lives inside your Godot project as an addon, runs inside the engine, and speaks the same language as the code under test.

The audience follows from that. If your game logic is gdscript and you want tests to load real scenes, real nodes and real signals, GUT is aimed at you. If you are shipping a Godot 3.x project, the README points at GUT 7.x (currently 7.4.2) rather than the 9.x line. If your team writes C#, the README does not describe a C# path at all, and the related search phrase Godot unit testing C# is not answered by anything in this repository.

How GUT runs: addon, plugin, panel and CLI

The architecture is deliberately unexotic. GUT ships as `addons/gut`, a directory you place inside your Godot project. Once the plugin is enabled, GUT adds a panel to the editor from which you can run the suite. Tests themselves are scripts that extend GUT's test class and define methods the framework discovers and calls.

The feature list is where the design shows. Doubling comes in two forms, full and partial, alongside stubbing and spies. That combination matters because gdscript tests often need to isolate a node from its collaborators without rewriting the node. Partial doubles in particular let you replace selected methods on a real object rather than swapping the whole thing for a fake. Parameterized tests let one test method run against a table of inputs instead of a hand-written loop. Inner test classes group related cases inside a single file, which keeps context close to the assertions.

Two features push GUT past the editor. The CLI lets a suite run without opening the panel, and result export writes JUnit XML, the format most CI systems already parse. The README does not describe a built-in CI recipe, so wiring that XML into a pipeline is left to you. There is also a VSCode extension, listed under the name gut-extension, which can run the entire suite, a single test script, or a single test from the editor.

Installing GUT and running a first test

The README gives two install paths. The Asset Library path is listed first, and the README notes that only two versions live there, one for Godot 3 and one for Godot 4, and that GUT will not appear if your Godot version is below the required version. The zip path is more explicit and is worth following when the Asset Library entry is missing.

Download the zip for your GUT version, extract it, and place the `addons/gut` directory into your project. Then enable the GUT plugin. The README adds one step people skip: you will need to relaunch Godot.

The repository also carries a `.gutconfig.json` at its top level and a `readme_gutconfig.json`, which tells you the CLI reads configuration from a file of that name. The README does not print the contents of those files, so treat the config keys as something to read from the repository rather than something to guess. What the README does document is the shape of the workflow: install, enable, relaunch, then write tests and run them from the panel or the CLI. If you are on the main branch, the version table pairs it with Godot 4.6.x, and the 9.7.1 release is paired with 4.7.x.

The version pairing is the real constraint

The most detailed part of the README is not a feature list. It is a table mapping GUT versions to Godot versions, and the reason is that GUT is coupled to engine internals. 9.7.1 targets Godot 4.7.x. Main targets 4.6.x. 9.6.1 targets 4.6.x. 9.5.0 targets 4.5.x, 9.4.0 covers 4.3.x through 4.4.x, 9.3.0 is for 4.2.x, 9.1.1 for 4.1.x, 9.0.1 for 4.0.x, and 7.4.3 for 3.5.x.

Read that as a maintenance tax rather than a bug. Upgrading Godot can force a GUT upgrade, and a GUT upgrade can force you to re-check doubles and spies if their behaviour moved. The README offers no rollback procedure and no migration notes; CHANGES.md is the file that would carry them. The README also does not state a deprecation policy for the older branches. If you pin Godot to a specific minor version for shipping reasons, you are also pinning GUT, and the two move together. Plan for that before you write a suite that depends on partial doubles.

Where GUT is the wrong tool

GUT tests gdscript, inside Godot. It is not a browser automation layer, and the related phrase Godot end to end testing does not describe what this repository does. If your failure mode only appears when a player clicks through menus on a real build, a unit testing framework will not catch it, no matter how many doubles you configure.

The second boundary is language. Nothing in the README describes testing C# code, and the framework is written in GDScript. A mixed project that keeps gameplay in C# will not get coverage from GUT for that half of the codebase. The third boundary is engine version. If you are on Godot 3.x, the 9.x line is not for you; the README routes you to 7.x, and the 7.x documentation is hosted at a version-specific URL rather than the latest one. Finally, GUT is a framework, not a service. There is no hosted dashboard and no test result storage. JUnit XML is the handoff point, and everything after it is your problem.

GUT against gdUnit4 and the shape of the choice

The comparison people search for is GUT versus gdUnit4, and the only honest statement available here is that this repository is GUT, and the README does not benchmark or compare itself to gdUnit4 at all. What the README does let you compare is scope. GUT's advertised surface is asserts and utility methods, inner test classes, full and partial doubles, stubbing, spies, a CLI, parameterized tests, and JUnit XML export.

The difference in approach that matters is where the runner lives. GUT is an addon you drop into the project and enable as a plugin, with an editor panel as the primary interface and a CLI as the second one. That is a low-ceremony model, and it means the test code sits in the same project tree as the game code. The cost is that the framework is bound to the engine version, as the version table shows. A tool that runs tests outside the engine would not carry that coupling, but it would also not be able to double a real Godot node with the same fidelity. Pick based on whether you want tests inside the engine or beside it.

Licence, upgrades and what the README leaves open

The README states that Gut is provided under the MIT license, with the licence text in `addons/gut/LICENSE.md`. MIT is permissive and imposes no copyleft obligation on your game code, but this is a description of what the repository says, not legal advice. If your organisation has a policy on bundled dependencies, the file to hand to whoever reviews it is that LICENSE.md inside the addon directory.

The upgrade cost is the version table again. Every Godot minor bump is a potential GUT bump, and the README does not promise that a newer GUT runs on an older Godot or the reverse. The cleanest habit is the one the table implies: record the GUT version and the Godot version together, and check the pairing before you upgrade either. The README is silent on rollback, on deprecation windows for old branches, and on migration steps between GUT versions. CHANGES.md is the file to read for those, and the version-specific documentation URLs listed in the table are how you read docs that match the release you actually have.

Editorial conclusion

Adopt GUT if your project is Godot 4.x and your game logic lives in gdscript, because the framework runs inside the engine and needs no external runner. Do not adopt it if you are on Godot 3.x without checking the 7.x line, or if you expect C# test coverage, since the README describes a gdscript framework. Before committing, confirm that your Godot minor version matches the GUT version table, because the wrong pairing is the failure mode the README spends the most space warning about.

Frequently asked questions

Official sources

1. bitwes/Gut on GitHub
2. Issues
3. README
4. Releases