Skip to content

Testing ​

Load scenes, click buttons, and check signals from a normal .NET test runner. 2dog starts a real Godot engine for your tests, so they use your game's scripts and resources.

Illus. Moritz Voss: a white anthro dog in a hacker hoodie and their robot dog sniffing the ground"Find those bugs, wherever they hide."

2dog supports several popular test frameworks. It also provides generic fixtures if you need a different setup.

Choose your framework ​

Test hosts are opt-in. To add one, choose --xunit, --gdunit or --nunit.

xUnit

  • Headless and rendering collections
  • One engine shared across several test classes
  • Custom engine arguments
  • Combinatorial and pairwise rows through TestMatrix
  • Windowed tests on macOS through the main-thread runner

NUnit

  • Headless fixtures on all desktop platforms
  • Rendering fixtures on Windows and Linux
  • One engine per test class or parameterized fixture
  • Async setup and teardown hooks
  • Built-in combinatorial and pairwise test cases

Both integrations provide frame waits, signal expectations, input simulation, async lifecycle support, and automatic checks for Godot errors and warnings.

Minor differences
CapabilityxUnitNUnit
Engine shared across test classesCollection fixtureOne engine per fixture; no cross-class sharing
Rendering on macOSMain-thread runner includedNeeds a dedicated runner; use headless tests for now
Class-wide configuration matrixSeparate fixture types and collections[TestFixture(...)]
Method input combinationsTestMatrix with [MemberData][Combinatorial] and [Pairwise]

Test runners ​

All three hosts that 2dog sets up run on Microsoft.Testing.Platform (MTP):

HostMTP integrationSetup
GdUnit2dog's framework drives the embedded GDScript runnerConfiguration
NUnitOfficial NUnit adapter bridgeConfiguration
xUnitUpstream xUnit runner with 2dog's owner-thread entry pointConfiguration

When you set up a test host, 2dog creates a root global.json that selects MTP. If the project already has a global.json, 2dog does not change it. Run dotnet test from the project root to run every test host. To select MTP in your own global.json, add:

json
{ "test": { "runner": "Microsoft.Testing.Platform" } }

If a host or a global.json still uses VSTest, 2dog doctor reports it with the check layout.test-runner. See Microsoft's dotnet test guide for runner selection and options such as --coverage.

Find a guide ​

TaskGuide
Set up a test projectxUnit or NUnit
Run GDScript suites through dotnet testGdUnit
Wait for frames, check signals, or verify deletionWriting engine tests
Click controls or send keyboard eventsSimulating input
Change packages, build variants, or import settingsxUnit configuration or NUnit configuration

Keep simple tests simple

Code that does not use Godot can stay in ordinary unit tests. Use an engine fixture when the behavior depends on scenes, resources, or Godot's main loop.

2dog is Free and Libre Open Source under the MIT License.
2dog is not affiliated with or endorsed by the Godot Foundation.
Godot is licensed under the MIT License; the Godot logo is by Andrea Calabró under CC BY 4.0. @icons made by Voxy under the MIT License.
Continuous Integration compute graciously supported by Blacksmith.