NextUnit.Generator 1.17.0

NextUnit

A modern, high-performance test framework for .NET 10+ with zero-reflection execution and xUnit-style assertions.

Features

• Zero-reflection execution - Source generators produce delegate-based test registry
• Familiar assertions - Assert.Equal, Assert.True, Assert.Throws, Assert.Same, Assert.DoesNotThrow, etc.
• Async tests - Task, Task<T>, ValueTask, and ValueTask<T> return types for tests and lifecycle hooks
• Multi-scope lifecycle - [Before]/[After] at Test, Class, Assembly, or Session level
• Fine-grained parallelism - [ParallelLimit(N)], [NotInParallel("key")], [ParallelGroup]
• Execution priority - [ExecutionPriority(N)] for controlling test execution order
• Parameterized tests - [Arguments], [TestData], [Matrix], and typed per-row metadata
• Combined data sources - [Values], [ValuesFromMember], [ValuesFrom<T>] with Cartesian product
• Class data source - [ClassDataSource<T>] with shared instance support
• Category/Tag filtering - [Category], [Tag] with CLI and environment variable support
• Test dependencies - [DependsOn] for ordered execution with ProceedOnFailure option
• Explicit tests - [Explicit] to exclude from default runs
• Roslyn analyzers - Compile-time test validation
• Microsoft.Testing.Platform integration - Works with dotnet run, dotnet test, and IDE test explorers
• ASP.NET Core integration - NextUnit.AspNetCore package for web API testing
• Native AOT compatible

Quick Start

Installation

dotnet add package NextUnit

Project Configuration

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="NextUnit" Version="1.17.0" />
  </ItemGroup>
</Project>

Writing Tests

using NextUnit;

public class CalculatorTests
{
    [Test]
    public void Add_ReturnsSum()
    {
        Assert.Equal(4, 2 + 2);
    }

    [Test]
    public void Divide_ThrowsOnZero()
    {
        Assert.Throws<DivideByZeroException>(() => { var x = 1 / 0; });
    }

    [Test]
    [Arguments(2, 3, 5)]
    [Arguments(-1, 1, 0)]
    public void Add_Parameterized(int a, int b, int expected)
    {
        Assert.Equal(expected, a + b);
    }
}

Running Tests

dotnet run --project MyProject.Tests          # Run one test project
dotnet test                                   # Run all tests when MTP is selected in global.json

With the .NET 10 SDK, dotnet test selects Microsoft.Testing.Platform at repository scope:

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

NextUnit repositories can copy the checked-in global.json; dotnet run needs no repository-level configuration.

Assertions

Lifecycle Hooks

public class DatabaseTests
{
    [Before(LifecycleScope.Test)]   // Before each test
    public void Setup() { }

    [After(LifecycleScope.Test)]    // After each test
    public void Cleanup() { }

    [Before(LifecycleScope.Class)]  // Once before all tests in class
    public void ClassSetup() { }

    [Test]
    public void MyTest() { }
}

Scopes: Test, Class, Assembly, Session

Parallel Execution

[NotInParallel]      // Run tests serially
public class SlowTests { }

[ParallelLimit(2)]   // Max 2 concurrent tests
public class ModerateTests { }

Filtering

[Category("Integration")]
[Tag("Slow")]
public class MyTests { }

# Environment variables
NEXTUNIT_INCLUDE_CATEGORIES=Integration dotnet run --project MyProject.Tests
NEXTUNIT_EXCLUDE_TAGS=Slow dotnet run --project MyProject.Tests

Performance

The checked-in comparison suite runs 127 tests with shared bodies through native MTP executables. A 21-round cyclic comparison balances execution order across five major frameworks and Native AOT variants of NextUnit and TUnit. The current snapshot is from the PR #160 GitHub Actions run on Ubuntu 24.04:

The workload is startup-heavy and machine-specific, so these ratios are not universal performance claims. See the methodology and limitations, generated results, and raw timings.

Documentation

• Getting Started
• Migration from xUnit
• ASP.NET Core Testing
• Best Practices
• Performance Analysis
• CI/CD Integration
• Changelog

Sample Projects

• Class Library Testing - Business logic testing patterns
• Console App Testing - CLI argument parsing, file processing
• Framework Tests - All NextUnit features demonstrated
• Web API Testing - ASP.NET Core integration testing with WebApplicationTest<T>

Contributing

1. Open an issue to discuss your idea
2. Fork and create a feature branch
3. Write tests for your changes
4. Submit a PR

Note: English-only for code, comments, and documentation.

dotnet build --configuration Release
dotnet test --project samples/NextUnit.SampleTests/NextUnit.SampleTests.csproj

License

MIT License

Acknowledgments

Inspired by TUnit (architecture), xUnit (assertions), and NUnit/MSTest.