# gdUnit4: an embedded unit testing framework for Godot > GdUnit4 brings unit testing into the Godot editor, with a test inspector, fluent assertions, mocking and spying, a scene runner that can simulate mouse and keyboard input, and command line output for CI. It suits a Godot developer who wants tests to run inside the same tool they build the game in, and its version support is tied closely to the Godot release you are on. **godot-gdunit-labs/gdUnit4** — Embedded unit testing framework for Godot 4 supporting GDScript and C#. Features test-driven development, embedded test inspector, extensive assertions, mocking, scene testing. - Repository: https://github.com/godot-gdunit-labs/gdUnit4 - Website: https://godot-gdunit-labs.github.io/gdUnit4/latest/ - Stars: 1,296 · Forks: 82 - Language: GDScript - License: MIT - Published: 2026-10-19 · Updated: 2026-10-19 · Language: en - Canonical page: https://hysenlabs.com/projects/godot-gdunit-labs-gdunit4 ## Testing inside the editor, not beside it GdUnit4 is an embedded unit testing framework for Godot 4, and the name spells out the three parts, Godot, Unit Testing and Godot 4.x. It is designed for testing GDScript, C# scripts and scenes in the Godot editor, and the whole point of the embedded design is that the test suite lives in the same project as the game and runs in the same process. The main feature list starts with the editor integration. There is an Embedded Test Inspector for navigating your test suites directly within the Godot editor, and test discovery that automatically searches for tests at runtime and adds them to the inspector. You run test suites from Godot using the context menu, from the FileSystem panel, the ScriptEditor or the GdUnit Inspector, and there is a generation path, right-clicking any function in the ScriptEditor and selecting Create TestCase to generate tests automatically. That last feature is what makes the framework usable under a real deadline, because writing a test skeleton by hand for every new function is the chore that stops people testing. ## Assertions, matchers and the fluent style The test writing features are the part that has to feel good or the framework goes unused. The syntax is fluent, with an easy-to-read interface, and there is a wide range of assertion methods for verifying behaviour and output. Argument matchers let you verify function calls with expected arguments rather than checking a result after the fact, which is what you need when the function under test is a collaborator. Two details that are easy to miss in feature lists but bite in practice are supported here. Unicode text support is full, in test strings and in assertions, which matters for a game that renders any text. And variadic arguments support means you can test functions that accept a variable number of arguments, which in GDScript and C# both show up regularly in utility code. The comparison of what a test asserts is a script API rather than a string comparison, so the failure messages come from the framework. ## Mocking, spying and the scene runner The advanced capabilities are where GdUnit4 goes past unit testing into something closer to integration testing of a game. Test fuzzing generates random inputs to test edge cases and boundary conditions, and parameterized tests run a function with multiple sets of inputs and expected outputs. Test session hooks set up and tear down test resources at the session level, which is where a shared expensive resource belongs rather than in every test. Mocking and spying work in three ways. You can mock classes to simulate behaviour and define output for specific functions, spy on functions to verify they were called with expected parameters, and mock or spy on scenes. The Scene Runner is the most interesting piece, because it simulates different kinds of inputs and actions: mouse clicks and movements, keyboard inputs, touch screen interactions, custom input actions, and waiting for specific signals or function return values. For a game, that is the difference between testing a controller class in isolation and testing whether clicking a button actually does something in a running scene. ## Flaky test handling and orphan node detection Two features exist because games are not well-behaved test subjects. Flaky test handling detects and handles flaky tests by rerunning failed tests, with a configurable retry count and non-deterministic failures marked in the test results. That is a real design decision rather than a convenience, since a test framework that reports a failure the third time it passes has taught you to ignore the output. The marking is the important part, because a non-deterministic failure that is only hidden is worse than a visible one. Orphan node detection is the other. Godot scenes routinely leak nodes, and the framework detects orphan nodes and lists them with stack traces and detailed info. In a long-running game process that quietly accumulates freed objects, this is the kind of leak that turns into a frame rate problem three hours into a play session, and a stack trace pointing at the test that caused it is what makes it findable. Configurable templates let you customise the templates used for generating new test suites. ## Getting test results into a CI pipeline The continuous integration support is a command line tool that runs tests outside the Godot editor for CI/CD pipelines, and the reporting formats are the standard ones. There is HTML report generation for comprehensive test reports, and JUnit XML report export for CI integration, which is the format most CI systems already parse. There is also a GitHub Action integration, a public marketplace action named gdunit4-action for integrating GdUnit4 into your CI workflow. The command line tool matters more than it sounds, because the editor-based path cannot run on a headless CI runner, and a test framework that only runs inside a GUI is a framework that only runs on your machine. The repository also has separate run settings files at the root, a `.runsettings` and a `.runsettings-ci`, which is the .NET convention for switching between an editor configuration and a CI one. ## Version compatibility, and picking a release line The compatibility table is the most decision-relevant part of the README, and it is worth reading line by line because the framework version and the engine version are not interchangeable. The master branch, which is v7.0.0 in development, requires v4.7, v4.7.1 or v4.8.dev7. The v6.2.x line supports v4.5, v4.5.1, v4.5.2, v4.6, v4.6.1, v4.6.2, v4.6.3, v4.7 and v4.7.1, which is the widest useful range. The v6.1.x line drops the 4.7 entries and covers v4.5 through v4.6.3. The v6.0.x and later covers v4.5, v4.5.1 and v4.5.2, and the older lines go back to v5.x and v4.4.0 for v4.3 and v4.4. The badges at the top of the README list the currently supported engine versions from v4.3 up to v4.7.1. The published releases are v6.2.2 on 2026-10-07, v6.2.1 on 2026-08-20 and v6.2.0 on 2026-07-28, and the last push was on 2026-10-14. The practical rule is to pick the release line that matches your engine, not the newest one. ## The C# side, and the repository layout The GDScript and C# support are not the same thing, and the documentation treats them as separate products. The C# side lives in the GdUnit4Net repository, with the C# API in the gdUnit4.api package, and the section is headed GdUnit4Net, C# Support. That means a project that mixes the two languages is using two frameworks with a shared idea and a shared command line, and the C# side brings its own .NET machinery into the picture. The repository root shows that clearly. There is a `gdUnit4.csproj` and a `gdUnit4.sln`, a `Directory.Build.props`, a `global.json`, a `nuget.config` and a `stylecop.ruleset` alongside `stylecop.json`, which is the C# linting setup, and a `.runsettings` for the test runner configuration. The GDScript side lives in `addons/`, which is where a Godot addon has to sit to be loaded by the engine, and there is a `project.godot` and a `default_env.tres`. The repository also carries `llms.txt` and `llms-full.txt` at the root, a machine-readable summary intended for language models. ## Conclusion Adopt gdUnit4 if you write Godot 4 projects and want tests that run inside the editor with a scene runner, or if you need JUnit XML output for a CI pipeline. Skip it if your Godot version is outside the supported range for the release you pick, since the compatibility table is strict, and note that a GDScript project and a C# project use different parts of the framework. Before installing, match the GdUnit4 version to your Godot version using the compatibility table rather than taking master, since master targets v4.7, v4.7.1 and v4.8.dev7 while the v6.2.x line covers a wider range. ## FAQ ### Which Godot versions does gdUnit4 support? The master branch, which is v7.0.0 in development, requires v4.7, v4.7.1 or v4.8.dev7. The v6.2.x line covers v4.5 through v4.7.1, v6.1.x covers v4.5 through v4.6.3, and older lines go back to v4.0. ### How do I run gdUnit4 tests in CI? Use the command line tool, which runs tests outside the Godot editor for CI/CD pipelines, and export results in JUnit XML format. There is also a public marketplace GitHub Action, gdunit4-action, for integrating GdUnit4 into a CI workflow, and HTML reports are available for detailed breakdowns. ### What can the gdUnit4 Scene Runner simulate? Mouse clicks and movements, keyboard inputs, touch screen interactions and custom input actions, and it can wait for specific signals or function return values. Scenes themselves can also be mocked or spied on. ### Does gdUnit4 handle flaky tests? Yes. It detects and handles flaky tests by rerunning failed tests, with a configurable retry count, and non-deterministic failures are marked in the test results. It also detects orphan nodes, listing them with stack traces and detailed info. ### Can I write gdUnit4 tests in C#? Yes, though the C# side is a separate project. The C# API lives in the GdUnit4Net repository under the gdUnit4.api package, and the GDScript and C# frameworks share the project but not the implementation. ## Sources - [godot-gdunit-labs/gdUnit4 on GitHub](https://github.com/godot-gdunit-labs/gdUnit4) - [License: MIT](https://github.com/godot-gdunit-labs/gdUnit4/blob/master/LICENSE) - [Project website](https://godot-gdunit-labs.github.io/gdUnit4/latest/) - [README](https://github.com/godot-gdunit-labs/gdUnit4/blob/master/README.md) - [Releases](https://github.com/godot-gdunit-labs/gdUnit4/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/godot-gdunit-labs-gdunit4