TUnit.Assertions.Should

TUnit

A modern .NET testing framework. Tests are source-generated at compile time, run in parallel by default, and support Native AOT — all built on Microsoft.Testing.Platform.

Features

• Compile-time test discovery — tests are generated at build time rather than discovered via reflection at runtime, which means faster startup and better IDE integration
• Parallel by default — tests run concurrently; use [DependsOn] to express ordering and [ParallelLimiter] to cap concurrency
• Data-driven testing — [Arguments], [Matrix], [ClassData], and custom DataSourceGenerator<T> sources
• Async assertions with detailed failure messages
• Built-in Roslyn analyzers — catch mistakes at compile time, such as missing async, incorrect method signatures, and invalid attribute combinations
• Extensible — write your own skip conditions, retry logic, and attributes
• Native AOT & trimming support
• Lifecycle hooks — [Before] / [After] at method, class, assembly, or test session scope

Getting Started

Using the Project Template (Recommended)

dotnet new install TUnit.Templates
dotnet new TUnit -n "MyTestProject"
cd MyTestProject
dotnet run

Manual Installation

dotnet add package TUnit

Getting Started Guide · Migration Guides

Examples

Basic test with assertions

[Test]
public async Task Parsing_A_Valid_Date_Succeeds()
{
    var date = DateTime.Parse("2025-01-01");

    await Assert.That(date.Year).IsEqualTo(2025);
    await Assert.That(date.Month).IsEqualTo(1);
}

Data-driven tests

[Test]
[Arguments("[email protected]", "ValidPassword123")]
[Arguments("[email protected]", "AnotherPassword456")]
[Arguments("[email protected]", "AdminPass789")]
public async Task User_Login_Should_Succeed(string email, string password)
{
    var result = await authService.LoginAsync(email, password);
    await Assert.That(result.IsSuccess).IsTrue();
}

// Matrix — generates a test for every combination (9 total here)
[Test]
[MatrixDataSource]
public async Task Database_Operations_Work(
    [Matrix("Create", "Update", "Delete")] string operation,
    [Matrix("User", "Product", "Order")] string entity)
{
    await Assert.That(await ExecuteOperation(operation, entity))
        .IsTrue();
}

Hooks, dependencies, and retry

[Before(Class)]
public static async Task SetupDatabase(ClassHookContext context)
{
    await DatabaseHelper.InitializeAsync();
}

[Test]
[MethodDataSource(nameof(GetTestUsers))]
public async Task Register_User(string username, string password) { ... }

[Test, DependsOn(nameof(Register_User))]
[Retry(3)]
public async Task Login_With_Registered_User(string username, string password)
{
    // Guaranteed to run after Register_User passes
}

Custom attributes

Extend built-in base classes to create your own skip conditions, retry logic, and more:

public class WindowsOnlyAttribute : SkipAttribute
{
    public WindowsOnlyAttribute() : base("Windows only") { }

    public override Task<bool> ShouldSkip(TestContext testContext)
        => Task.FromResult(!OperatingSystem.IsWindows());
}

[Test, WindowsOnly]
public async Task Windows_Specific_Feature() { ... }

See the documentation for more examples, including custom retry logic and data sources.

IDE Support

Packages

Migrating from xUnit, NUnit, or MSTest?

The syntax will feel familiar. For example, xUnit's [Fact] becomes [Test], and [Theory] + [InlineData] becomes [Test] + [Arguments]. See the migration guides for full details: xUnit · NUnit · MSTest.

Community

• Documentation — guides, tutorials, and API reference
• GitHub Discussions — questions and ideas welcome
• Issues — bug reports and feature requests
• Changelog