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
• Async data sources - [TestData] accepts IAsyncEnumerable<T> and task-wrapped collection members
• Deferred data sources - opt a very large [TestData] source out of discovery-time enumeration
• 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
• Selective retry - [Retry(N)], or [Retry<TPolicy>(N)] with an async IRetryPolicy that decides per exception; the attempt number is on ITestContext and the attempt count reaches the failure output
• Deterministic culture - [Culture], [UICulture], [InvariantCulture] at assembly, class, or method level, restored after every test and isolated from tests running in parallel
• 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

New Project

dotnet new install NextUnit.Templates
dotnet new nextunit -n MyProject.Tests

The generated project references only the NextUnit package and contains one passing example test.

Existing Project

dotnet add package NextUnit

Project Configuration

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="NextUnit" Version="1.19.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

Category	Methods
Basic	Equal, NotEqual, True, False, Null, NotNull
Identity	Same, NotSame, Fail
Collections	Contains, DoesNotContain, Empty, NotEmpty, Single, All
Strings	StartsWith, EndsWith, Contains
Numeric	InRange, NotInRange, Equal(expected, actual, precision), Equal(expected, actual, tolerance), NotEqual(expected, actual, tolerance)
Exceptions	Throws<T>, ThrowsAsync<T>, DoesNotThrow, DoesNotThrowAsync
Advanced	Equivalent, Subset, Disjoint

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:

Framework	Version	Median	Median / NextUnit
NextUnit (AOT)	PR #160 checkout (1.15.1 assembly)	21.51ms	0.07x
TUnit (AOT)	1.61.15	27.45ms	0.09x
NextUnit	PR #160 checkout (1.15.1 assembly)	311.43ms	1.00x
MSTest	4.3.2	438.73ms	1.41x
NUnit	4.6.1	512.90ms	1.65x
xUnit	3.2.2	551.40ms	1.77x
TUnit	1.61.15	555.00ms	1.78x

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
• Migration from NUnit
• Migration from MSTest
• 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.