gdUnit4Net Unit Testing Framework

gdUnit4Net is a feature-complete unit testing framework for Godot C# projects. It is designed to be fully compatible with the VSTest standard, allowing you to run and debug tests within Visual Studio (Code), JetBrains Rider, and other VSTest-compatible environments.

Key architectural features include:

• Smart Runtime Detection: Tests run in a lightweight mode by default without the Godot runtime, significantly increasing performance for logic-only tests.
• Selective Godot Integration: You can opt-in to the Godot runtime for specific tests using the [RequireGodotRuntime] attribute.
• VSTest Compatibility: Supports standard VSTest features like test filtering, categories, and traits.

The project is divided into three distinct packages depending on your needs:

1. gdUnit4.api: The core package required to write and run unit tests in C#.
2. gdUnit4.test.adapter: The test adapter used to integrate gdUnit4 with the Visual Studio Test Platform (VSTest).
3. gdUnit4.analyzers: A Roslyn-based analyzer that provides compile-time validation for your gdUnit4 test attributes.

GdUnit4 treats TestCategory and Trait attributes with the name "Category" as the same thing. If you use both, the test will possess all categories assigned via either method.

Additionally, categories and traits defined at the class level are inherited by all test methods in that class. If a method defines its own, they are combined with the class-level ones.

[TestSuite]
[TestCategory("Integration")]
public class DatabaseTests 
{
    [TestCase]
    // Inherits "Integration" category from the class
    public void TestConnection() { }
    
    [TestCase]
    [TestCategory("Slow")]
    // Has both "Integration" and "Slow" categories
    public void TestBulkInsert() { }
}

You can selectively run tests by providing filter strings using the PropertyName=Value syntax. This allows you to target specific classes, categories, or custom traits.

Common filter properties include:

• Class: Filter by class name.
• TestCategory: Filter by category.
• Trait.<Name>: Filter by custom traits.

Filters can be combined using logical operators like & (AND).

# Run only tests in a specific class
Class=CalculatorTests

# Run tests with a specific category
TestCategory=UnitTest

# Run tests with specific traits
Trait.Priority=High

# Combine filters with logical operators
TestCategory=UnitTest&Trait.Owner=TeamA

Use the --filter option with the dotnet test command to run specific subsets of tests. Always wrap your filter expression in quotes to prevent shell interference with special characters like | or &.

# Run tests by category
dotnet test --filter "TestCategory=UnitTest"

# Run complex combined filters
dotnet test --filter "(TestCategory=UnitTest|TestCategory=Fast)&Namespace=MyProject.Tests"

The GdUnit4.Analyzer is a Roslyn-based tool that provides compile-time validation for GdUnit4 test attributes. It helps catch configuration errors, such as invalid combinations of attributes, during development rather than at runtime.

One key feature is validating the combination of [DataPoint] and [TestCase] attributes. For example, if a method uses a [DataPoint] attribute, it must not have multiple [TestCase] attributes.

// ✅ Valid: Single TestCase with DataPoint
[TestCase]
[DataPoint(nameof(TestData))]
public void ValidTest(int a, int b) { }

// ❌ Invalid: Multiple TestCase with DataPoint
[TestCase]
[TestCase] // Triggers GdUnit0201 error
[DataPoint(nameof(TestData))]
public void InvalidTest(int a, int b) { }

To enable compile-time validation for GdUnit4 test attributes, add the gdUnit4.analyzers package to your project. It is recommended to include gdUnit4.api and gdUnit4.test.adapter as well. When adding the analyzer, use the <PrivateAssets>all</PrivateAssets> and specific <IncludeAssets> configuration to ensure it functions correctly as a Roslyn analyzer without being a runtime dependency.

<PackageReference Include="gdUnit4.api" Version="5.0.0"/>
<PackageReference Include="gdUnit4.test.adapter" Version="3.0.0"/>
<PackageReference Include="gdUnit4.analyzers" Version="1.0.0">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
</PackageReference>

To integrate GdUnit4 with test frameworks supporting the Visual Studio Test Platform (VSTest), add the gdUnit4.test.adapter package to your test project via NuGet.

This enables test discovery, execution, debugging, and error navigation in supported IDEs like Visual Studio, VS Code, and JetBrains Rider.

<PackageReference Include="gdUnit4.test.adapter" Version="3.0.0" />

Because gdUnit4Net is VSTest compatible, you can use the dotnet test --filter command to selectively run tests based on their names, categories, or traits. This is useful for separating fast logic tests from slow integration tests in CI/CD pipelines.

# 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)"