<h2 align="center">The Unit Testing Framework in C# for Godot</h2> <p align="center"> <a href="https://www.patreon.com/cw/GodotGdUnitLabs"> <img src="assets/patreon-banner.svg" alt="Stay Connected & Updated — Follow on Patreon" width="100%"/> </a> </p> <p align="center">This version of GdUnit4.api is based on Godot <strong>v4.4.stable.mono.official [4c311cbee]</strong> (master branch)</p> <h1 align="center">Supported Godot Versions</h1> <p align="center"> <img src="https://img.shields.io/badge/Godot-v4.3.0-%23478cbf?logo=godot-engine&logoColor=cyian&color=green"> <img src="https://img.shields.io/badge/Godot-v4.4.0-%23478cbf?logo=godot-engine&logoColor=cyian&color=green"> <img src="https://img.shields.io/badge/Godot-v4.4.1-%23478cbf?logo=godot-engine&logoColor=cyian&color=green"> </p> <h1 align="center">Supported .NET Versions</h1> <p align="center"> <img src="https://img.shields.io/badge/.NET-8.0-blue?logo=dotnet&logoColor=white"> <img src="https://img.shields.io/badge/.NET-9.0-blue?logo=dotnet&logoColor=white"> <img src="https://img.shields.io/badge/C%23-12.0-239120?logo=csharp&logoColor=white"> <img src="https://img.shields.io/badge/VSTest-Compatible-green?logo=visualstudio&logoColor=white"> </p>

What is gdUnit4Net

GdUnit4Net is a feature-complete unit testing framework for Godot C# projects that is fully compatible with the VSTest standard. It provides an API and VS test adapter to
run your Godot C# tests seamlessly in Visual Studio (Code), JetBrains Rider, and any VSTest-compatible environment.

Key Highlights

🚀 High Performance: Up to 10x faster test execution for logic-only tests
🎯 VSTest Compatible: Full integration with Visual Studio Test Platform
⚡ Smart Runtime: Tests run without Godot runtime by default, with opt-in Godot features
🔧 Feature Complete: All standard testing features you expect from modern frameworks

Main Features

Writing, executing and debugging tests with full IDE integration
Wide range of assertion methods for verifying the behavior and output of your code
Parameterized Tests (Test Cases and DataPoints) for testing functions with multiple sets of inputs and expected outputs
Advanced Test Filtering with VSTest filter support, test categories, and traits
Scene runner for simulating different kinds of inputs and actions, such as mouse clicks and keyboard inputs
For example, you can simulate mouse clicks and keyboard inputs by calling the appropriate methods on the runner instance. Additionally, you can wait for a specific signal to be
emitted by the scene, or you can wait for a specific function to return a certain value.
VSTest Adapter to run and debug your tests with full VSTest compatibility
Powerful test filtering capabilities to selectively run tests based on various criteria
Exception monitoring with automatic capture of Godot exceptions and runtime errors
Test output capture including stdout and Godot log integration
Roslyn Analyzers for compile-time validation of test attributes and combinations
Flexible test execution - tests run without Godot runtime by default for maximum performance, with [RequireGodotRuntime] for Godot-specific features

Architecture Redesign (v5.0+)

GdUnit4Net v5.0 introduces a major architecture overhaul that revolutionizes test performance and compatibility:

Smart Runtime Detection: Tests run in lightweight mode by default, only spinning up Godot runtime when explicitly needed
Performance Boost: Logic-only tests execute up to 10x faster than previous versions
VSTest Standard Compliance: Full compatibility with Visual Studio Test Platform and all VSTest features
Selective Godot Integration: Use [RequireGodotRuntime] attribute only for tests that actually need Godot features

⚠️ Please read the release notes about breaking changes. ⚠️

There are three packages available in this project:

gdUnit4.api - The core package to enable writing and running unit tests in C#.
gdUnit4.test.adapter - The test adapter to integrate GdUnit4 with Visual Studio Test Platform.
gdUnit4.analyzers - A Roslyn-based analyzer that provides compile-time validation for GdUnit4 test attributes.

gdunit4.api

Checkout the gdUnit4.api README to install and use the core testing framework.

gdUnit4.test.adapter

Checkout the gdUnit4.test.adapter README to install and use the test adapter. This adapter now supports
powerful test filtering capabilities for selectively running tests based on specific criteria.

gdUnit4.analyzers

For compile-time validation of your test code, check out the gdUnit4.analyzers README.

Examples

The gdUnit4NetExamples repository provides comprehensive example projects
demonstrating both basic and advanced GdUnit4Net usage patterns. It includes foundational examples for newcomers learning unit testing fundamentals,
as well as sophisticated examples covering professional configurations, complex testing scenarios, input simulation, signal testing,
and exception handling. These working examples showcase GdUnit4Net v5.0 features including selective Godot runtime usage, advanced scene testing,
and production-ready test setups.

Short Example

csharp
namespace GdUnit4.Tests
{
    using static Assertions;

    [TestSuite]
    public class StringAssertTest
    {
        // Fast execution - no Godot runtime needed
        [TestCase]
        public void IsEqual()
        {
            AssertThat("This is a test message").IsEqual("This is a test message");
        }
        
        // Godot runtime required for Node operations
        [TestCase] 
        [RequireGodotRuntime]
        public void TestGodotNode()
        {
             AssertThat(new Node2D()).IsNotNull();
        }
        
        // Exception monitoring for Godot-specific errors
        [Test]
        [RequireGodotRuntime]
        [GodotExceptionMonitor]
        public void TestNodeCallback()
        {
            var node = new MyNode(); // Will catch exceptions in _Ready()
            AddChild(node);
        }
        
        // Data-driven tests with dynamic test data
        [Test]
        [DataPoint(nameof(TestData))]
        public void TestCalculations(int a, int b, int expected)
        {
            AssertThat(Calculator.Add(a, b)).IsEqual(expected);
        }
        
        // Exception validation with specific messages
        [Test]
        [ThrowsException(typeof(ArgumentNullException), "Value cannot be null")]
        public void TestValidation()
        {
            Calculator.Add(null, 5);
        }
        
        // Test categories and traits for filtering
        [Test]
        [Category("Integration")]
        [Trait("Speed", "Fast")]
        public void FastIntegrationTest()
        {
            // This test can be filtered by category or trait
        }
        
        // Data source for parameterized tests
        public static IEnumerable<object[]> TestData => new[]
        {
            new object[] { 1, 2, 3 },
            new object[] { 5, 7, 12 },
            new object[] { -1, 1, 0 }
        };
    }
}

VSTest Integration Example

Run tests with advanced filtering using VSTest standard syntax:

bash
# Run only fast tests
dotnet test --filter "Trait=Speed:Fast"

# Run integration tests
dotnet test --filter "Category=Integration"

# Run tests by name pattern
dotnet test --filter "FullyQualifiedName~Calculator"

# Combine multiple filters
dotnet test --filter "(Category=Integration)|(Trait=Speed:Fast)"

The test run looks like this:

What's New in v5.0

🚀 Performance Revolution

Up to 10x faster test execution for logic-only tests
Tests run without Godot runtime by default
Only use [RequireGodotRuntime] when you actually need Godot features

🎯 VSTest Standard Compliance

Full compatibility with Visual Studio Test Platform
Advanced test filtering with categories and traits
Seamless integration with CI/CD pipelines

📊 Enhanced Test Capabilities

DataPoint attributes for dynamic parameterized tests
Exception monitoring with automatic Godot error capture
Output capture including stdout and Godot logs
Roslyn analyzers for compile-time validation

🔧 Developer Experience

Better error reporting and diagnostics
Improved test discovery and execution
Enhanced debugging capabilities
Environment variable support from runsettings

Documentation

<p align="left" style="font-family: Bedrock; font-size:21pt; color:#7253ed; font-style:bold"> <a href="https://godot-gdunit-labs.github.io/gdUnit4/latest/csharp_project_setup/csharp-setup/">How to setup GdUnit4 for C#</a> </p> <p align="left" style="font-family: Bedrock; font-size:21pt; color:#7253ed; font-style:bold"> <a href="https://godot-gdunit-labs.github.io/gdUnit4/latest/csharp_project_setup/vstest-adapter/">Supported IDE's</a> </p> <p align="left" style="font-family: Bedrock; font-size:21pt; color:#7253ed; font-style:bold"> <a href="TestAdapter/TestFilterGuide.md">Test Filtering Guide</a> </p>

Migration from v4.x to v5.0

Important: v5.0 includes breaking changes that require minimal code updates:
⚠️ Please read the release notes about breaking changes. ⚠️

Add [RequireGodotRuntime] to tests that use Godot features (Nodes, Scenes, Resources)
Remove unnecessary Godot dependencies from pure logic tests for better performance
Update test filtering to use new VSTest-compatible syntax

You Are Welcome To

Contribution Guidelines

Thank you for your interest in contributing to GdUnit4!<br>
To ensure a smooth and collaborative contribution process, please review our contribution guidelines before
getting started. These guidelines outline the standards and expectations we uphold in this project.

Code of Conduct: We strictly adhere to the Godot code of conduct in this project. As a contributor, it is important to respect and follow this code to maintain a positive and
inclusive community.

Using GitHub Issues: We utilize GitHub issues for tracking feature requests and bug reports. If you have a general question or wish to engage in discussions, we recommend joining
the GdUnit Discord Server for specific inquiries.

We value your input and appreciate your contributions to make GdUnit4 even better!