GodotUnit 0.0.0-alpha.0.69

GodotUnit

A test framework for Godot 4+ C# projects. Uses source generation for reflection-free test discovery and provides Godot-specific utilities for scene/node testing.

Components

Quick Start

Add the NuGet packages to your Godot project:

<PackageReference Include="GodotUnit.Runtime" Version="*" />
<PackageReference Include="GodotUnit.Generator" Version="*" OutputItemType="Analyzer" />

Write a test:

using GodotUnit;

public partial class PlayerTests
{
    [Before(HookType.Test)]
    public void Setup()
    {
        // runs before each test
    }

    [Test]
    public async Task Player_TakesDamage_HealthDecreases()
    {
        var player = TestContext.Current.AddNode(new Player());

        player.TakeDamage(10);
        await TestContext.Current.WaitPhysicsFrame();

        Assert.That(player.Health).IsEqualTo(90);
    }

    [Test]
    [Arguments(1, 2, 3)]
    [Arguments(5, 5, 10)]
    public void Add_ReturnsSum(int a, int b, int expected)
    {
        Assert.That(a + b).IsEqualTo(expected);
    }
}

Run tests from your game's entry point:

public override async void _Ready()
{
    await GodotUnit.GodotUnit.RunTests(this, TestRegistry.TestClasses, OS.GetCmdlineArgs());
}

Attributes

TestContext

Access via TestContext.Current during test execution:

// Scene tree access
TestContext.Current.SceneTree
TestContext.Current.TestScene

// Frame processing
await TestContext.Current.WaitPhysicsFrame();
await TestContext.Current.WaitProcessFrame();
await TestContext.Current.ProcessFrames(5);
await TestContext.Current.WaitSeconds(2.0);

// Node management (auto-cleanup after test)
var node = TestContext.Current.AddNode(new MyNode());
var scene = await TestContext.Current.LoadSceneAsync<MyScene>("res://scene.tscn");

// Test metadata
TestContext.Current.Metadata.TestName
TestContext.Current.CancellationToken

Nodes added via TestContext are automatically removed after each test.

CLI Tool

Install:

dotnet tool install -g GodotUnit.Cli

Commands:

# Run tests
godotunit run --all                      # all tests (excludes RequiresDisplay)
godotunit run @Combat                    # namespace filter (contains)
godotunit run #Integration               # category filter
godotunit run PlayerTests                # class name filter
godotunit run --rerun-failed             # rerun from failed-tests.json
godotunit run --display                  # RequiresDisplay tests only

# Parallel execution
godotunit run-parallel                   # 8 workers default
godotunit run-parallel --workers 4       # custom worker count
godotunit run-parallel --dry-run         # show partition plan

# Query test history
godotunit query runs                     # recent test runs
godotunit query history <pattern>        # history for test pattern
godotunit query flaky                    # tests below 90% pass rate
godotunit query slowest                  # slowest by avg duration

# Analyze failures
godotunit analyze                        # failure summary
godotunit analyze --show 1               # detail for failure #1
godotunit analyze --show 1 --with-logs   # include logs
godotunit analyze --exceptions           # group by exception type

# Track flakiness
godotunit track PlayerTests --runs 10    # run N times, report pass rate

Filtering

The CLI supports multiple filter types:

• @Namespace - namespace contains match
• #Category - category exact match
• !#Category - exclude category
• ClassName - class name contains match
• Class::Method - specific test method
• Method* - wildcard pattern

Configuration

Priority: CLI flags > godotunit.json > GODOT_PATH env var

{
  "godotPath": "/path/to/godot.exe",
  "projectPath": "src/godot"
}

Architecture

The source generator scans for [Test], [Before], and [After] attributes at compile time and generates:

1. ITestInvoker implementation for each test class - enables reflection-free test execution
2. TestRegistry with metadata for all discovered tests

This approach avoids runtime reflection and provides deterministic test ordering based on source line numbers.

Exception Handling

Godot swallows exceptions thrown in _Ready() callbacks. GodotUnit captures these via AppDomain.FirstChanceException and surfaces them as ReadyCallbackException, ensuring test failures are properly reported.