base on A modern, fast and flexible .NET testing framework 
# š The Modern Testing Framework for .NET
**TUnit** is a modern testing framework for .NET that uses **source-generated tests**, **parallel execution by default**, and **Native AOT support**. Built on Microsoft.Testing.Platform, it's faster than traditional reflection-based frameworks and gives you more control over how your tests run.
<div align="center">
[](https://trendshift.io/repositories/11781)
[](https://app.codacy.com/gh/thomhurst/TUnit?utm_source=github.com&utm_medium=referral&utm_content=thomhurst/TUnit&utm_campaign=Badge_Grade) 
[](https://github.com/sponsors/thomhurst) [](https://www.nuget.org/packages/TUnit/) [](https://www.nuget.org/packages/TUnit/)   
</div>
## Why TUnit?
| Feature | Traditional Frameworks | **TUnit** |
|---------|----------------------|-----------|
| Test Discovery | ā Runtime reflection | ā
**Compile-time generation** |
| Execution Speed | ā Sequential by default | ā
**Parallel by default** |
| Modern .NET | ā ļø Limited AOT support | ā
**Native AOT & trimming** |
| Test Dependencies | ā Not supported | ā
**`[DependsOn]` chains** |
| Resource Management | ā Manual lifecycle | ā
**Automatic cleanup** |
**Parallel by Default** - Tests run concurrently with dependency management
**Compile-Time Discovery** - Test structure is known before runtime
**Modern .NET Ready** - Native AOT, trimming, and latest .NET features
**Extensible** - Customize data sources, attributes, and test behavior
---
<div align="center">
## **[Documentation](https://tunit.dev)**
**New to TUnit?** Start with the **[Getting Started Guide](https://tunit.dev/docs/getting-started/installation)**
**Migrating?** See the **[Migration Guides](https://tunit.dev/docs/migration/xunit)**
**Learn more:** **[Data-Driven Testing](https://tunit.dev/docs/test-authoring/arguments)**, **[Test Dependencies](https://tunit.dev/docs/test-authoring/depends-on)**, **[Parallelism Control](https://tunit.dev/docs/parallelism/not-in-parallel)**
</div>
---
## Quick Start
### Using the Project Template (Recommended)
```bash
dotnet new install TUnit.Templates
dotnet new TUnit -n "MyTestProject"
```
### Manual Installation
```bash
dotnet add package TUnit --prerelease
```
š **[Complete Documentation & Guides](https://tunit.dev)**
## Key Features
<table>
<tr>
<td width="50%">
**Performance**
- Source-generated tests (no reflection)
- Parallel execution by default
- Native AOT & trimming support
- Optimized for speed
</td>
<td width="50%">
**Test Control**
- Test dependencies with `[DependsOn]`
- Parallel limits & custom scheduling
- Built-in analyzers & compile-time checks
- Custom attributes & extensible conditions
</td>
</tr>
<tr>
<td>
**Data & Assertions**
- Multiple data sources (`[Arguments]`, `[Matrix]`, `[ClassData]`)
- Fluent async assertions
- Retry logic & conditional execution
- Test metadata & context
</td>
<td>
**Developer Tools**
- Full dependency injection support
- Lifecycle hooks
- IDE integration (VS, Rider, VS Code)
- Documentation & examples
</td>
</tr>
</table>
## Simple Test Example
```csharp
[Test]
public async Task User_Creation_Should_Set_Timestamp()
{
// Arrange
var userService = new UserService();
// Act
var user = await userService.CreateUserAsync("
[email protected]");
// Assert - TUnit's fluent assertions
await Assert.That(user.CreatedAt)
.IsEqualTo(DateTime.Now)
.Within(TimeSpan.FromMinutes(1));
await Assert.That(user.Email)
.IsEqualTo("
[email protected]");
}
```
## Data-Driven Testing
```csharp
[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 testing - tests all combinations
[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();
}
```
## Advanced Test Orchestration
```csharp
[Before(Class)]
public static async Task SetupDatabase(ClassHookContext context)
{
await DatabaseHelper.InitializeAsync();
}
[Test, DisplayName("Register a new account")]
[MethodDataSource(nameof(GetTestUsers))]
public async Task Register_User(string username, string password)
{
// Test implementation
}
[Test, DependsOn(nameof(Register_User))]
[Retry(3)] // Retry on failure
public async Task Login_With_Registered_User(string username, string password)
{
// This test runs after Register_User completes
}
[Test]
[ParallelLimit<LoadTestParallelLimit>] // Custom parallel control
[Repeat(100)] // Run 100 times
public async Task Load_Test_Homepage()
{
// Performance testing
}
// Custom attributes
[Test, WindowsOnly, RetryOnHttpError(5)]
public async Task Windows_Specific_Feature()
{
// Platform-specific test with custom retry logic
}
public class LoadTestParallelLimit : IParallelLimit
{
public int Limit => 10; // Limit to 10 concurrent executions
}
```
## Custom Test Control
```csharp
// Custom conditional execution
public class WindowsOnlyAttribute : SkipAttribute
{
public WindowsOnlyAttribute() : base("Windows only test") { }
public override Task<bool> ShouldSkip(TestContext testContext)
=> Task.FromResult(!OperatingSystem.IsWindows());
}
// Custom retry logic
public class RetryOnHttpErrorAttribute : RetryAttribute
{
public RetryOnHttpErrorAttribute(int times) : base(times) { }
public override Task<bool> ShouldRetry(TestInformation testInformation,
Exception exception, int currentRetryCount)
=> Task.FromResult(exception is HttpRequestException { StatusCode: HttpStatusCode.ServiceUnavailable });
}
```
## Common Use Cases
<table>
<tr>
<td width="33%">
### **Unit Testing**
```csharp
[Test]
[Arguments(1, 2, 3)]
[Arguments(5, 10, 15)]
public async Task Calculate_Sum(int a, int b, int expected)
{
await Assert.That(Calculator.Add(a, b))
.IsEqualTo(expected);
}
```
</td>
<td width="33%">
### **Integration Testing**
```csharp
[Test, DependsOn(nameof(CreateUser))]
public async Task Login_After_Registration()
{
// Runs after CreateUser completes
var result = await authService.Login(user);
await Assert.That(result.IsSuccess).IsTrue();
}
```
</td>
<td width="33%">
### **Load Testing**
```csharp
[Test]
[ParallelLimit<LoadTestLimit>]
[Repeat(1000)]
public async Task API_Handles_Concurrent_Requests()
{
await Assert.That(await httpClient.GetAsync("/api/health"))
.HasStatusCode(HttpStatusCode.OK);
}
```
</td>
</tr>
</table>
## What Makes TUnit Different?
### **Compile-Time Test Discovery**
Tests are discovered at build time, not runtime. This means faster discovery, better IDE integration, and more predictable resource management.
### **Parallel by Default**
Tests run in parallel by default. Use `[DependsOn]` to chain tests together, and `[ParallelLimit]` to control resource usage.
### **Extensible**
The `DataSourceGenerator<T>` pattern and custom attribute system let you extend TUnit without modifying the framework.
## Community & Ecosystem
<div align="center">
[](https://www.nuget.org/packages/TUnit/)
[](https://github.com/thomhurst/TUnit/graphs/contributors)
[](https://github.com/thomhurst/TUnit/discussions)
</div>
### **Resources**
- **[Official Documentation](https://tunit.dev)** - Guides, tutorials, and API reference
- **[GitHub Discussions](https://github.com/thomhurst/TUnit/discussions)** - Get help and share ideas
- **[Issue Tracking](https://github.com/thomhurst/TUnit/issues)** - Report bugs and request features
- **[Release Notes](https://github.com/thomhurst/TUnit/releases)** - Latest updates and changes
## IDE Support
TUnit works with all major .NET IDEs:
### Visual Studio (2022 17.13+)
ā
**Fully supported** - No additional configuration needed for latest versions
āļø **Earlier versions**: Enable "Use testing platform server mode" in Tools > Manage Preview Features
### JetBrains Rider
ā
**Fully supported**
āļø **Setup**: Enable "Testing Platform support" in Settings > Build, Execution, Deployment > Unit Testing > Testing Platform
### Visual Studio Code
ā
**Fully supported**
āļø **Setup**: Install [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) and enable "Use Testing Platform Protocol"
### Command Line
ā
**Full CLI support** - Works with `dotnet test`, `dotnet run`, and direct executable execution
## Package Options
| Package | Use Case |
|---------|----------|
| **`TUnit`** | **Start here** - Complete testing framework (includes Core + Engine + Assertions) |
| **`TUnit.Core`** | Test libraries and shared components (no execution engine) |
| **`TUnit.Engine`** | Test execution engine and adapter (for test projects) |
| **`TUnit.Assertions`** | Standalone assertions (works with any test framework) |
| **`TUnit.Playwright`** | Playwright integration with automatic lifecycle management |
## Migration from Other Frameworks
**Coming from NUnit or xUnit?** TUnit uses familiar syntax with some additions:
```csharp
// TUnit test with dependency management and retries
[Test]
[Arguments("value1")]
[Arguments("value2")]
[Retry(3)]
[ParallelLimit<CustomLimit>]
public async Task Modern_TUnit_Test(string value) { }
```
š **Need help migrating?** Check our **[Migration Guides](https://tunit.dev/docs/migration/xunit)** for xUnit, NUnit, and MSTest.
---
<div align="center">
## Getting Started
```bash
# Create a new test project
dotnet new install TUnit.Templates && dotnet new TUnit -n "MyTestProject"
# Or add to existing project
dotnet add package TUnit --prerelease
```
**Learn More**: [tunit.dev](https://tunit.dev) | **Get Help**: [GitHub Discussions](https://github.com/thomhurst/TUnit/discussions) | **Star on GitHub**: [github.com/thomhurst/TUnit](https://github.com/thomhurst/TUnit)
</div>
## Performance Benchmark
### Scenario: Building the test project
```
BenchmarkDotNet v0.15.6, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.100-rc.2.25502.107
[Host] : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Job-GVKUBM : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Runtime=.NET 10.0
```
| Method | Version | Mean | Error | StdDev | Median |
|------------- |-------- |--------:|---------:|---------:|--------:|
| Build_TUnit | 1.0.48 | 1.798 s | 0.0345 s | 0.0424 s | 1.785 s |
| Build_NUnit | 4.4.0 | 1.575 s | 0.0169 s | 0.0158 s | 1.573 s |
| Build_MSTest | 4.0.1 | 1.659 s | 0.0150 s | 0.0140 s | 1.658 s |
| Build_xUnit3 | 3.2.0 | 1.579 s | 0.0182 s | 0.0170 s | 1.575 s |
### Scenario: Tests running asynchronous operations and async/await patterns
```
BenchmarkDotNet v0.15.6, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.100-rc.2.25502.107
[Host] : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Job-GVKUBM : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Runtime=.NET 10.0
```
| Method | Version | Mean | Error | StdDev | Median |
|---------- |-------- |---------:|---------:|---------:|---------:|
| TUnit | 1.0.48 | 562.4 ms | 4.18 ms | 3.91 ms | 561.0 ms |
| NUnit | 4.4.0 | 679.2 ms | 7.24 ms | 6.41 ms | 679.6 ms |
| MSTest | 4.0.1 | 647.7 ms | 8.63 ms | 7.65 ms | 647.8 ms |
| xUnit3 | 3.2.0 | 744.4 ms | 11.90 ms | 10.55 ms | 741.5 ms |
| TUnit_AOT | 1.0.48 | 127.6 ms | 0.45 ms | 0.42 ms | 127.6 ms |
### Scenario: Parameterized tests with multiple test cases using data attributes
```
BenchmarkDotNet v0.15.6, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.100-rc.2.25502.107
[Host] : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Job-GVKUBM : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Runtime=.NET 10.0
```
| Method | Version | Mean | Error | StdDev | Median |
|---------- |-------- |----------:|----------:|----------:|----------:|
| TUnit | 1.0.48 | 476.97 ms | 5.430 ms | 5.080 ms | 478.26 ms |
| NUnit | 4.4.0 | 537.80 ms | 6.692 ms | 6.260 ms | 537.55 ms |
| MSTest | 4.0.1 | 496.84 ms | 9.188 ms | 8.145 ms | 496.37 ms |
| xUnit3 | 3.2.0 | 584.15 ms | 10.733 ms | 10.039 ms | 582.13 ms |
| TUnit_AOT | 1.0.48 | 24.65 ms | 0.177 ms | 0.157 ms | 24.68 ms |
### Scenario: Tests executing massively parallel workloads with CPU-bound, I/O-bound, and mixed operations
```
BenchmarkDotNet v0.15.6, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.100-rc.2.25502.107
[Host] : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Job-GVKUBM : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Runtime=.NET 10.0
```
| Method | Version | Mean | Error | StdDev | Median |
|---------- |-------- |-----------:|---------:|---------:|-----------:|
| TUnit | 1.0.48 | 578.1 ms | 5.79 ms | 5.13 ms | 577.3 ms |
| NUnit | 4.4.0 | 1,220.5 ms | 7.43 ms | 6.20 ms | 1,220.9 ms |
| MSTest | 4.0.1 | 3,005.3 ms | 13.91 ms | 12.33 ms | 3,003.4 ms |
| xUnit3 | 3.2.0 | 3,096.0 ms | 11.11 ms | 10.40 ms | 3,094.6 ms |
| TUnit_AOT | 1.0.48 | 130.6 ms | 0.39 ms | 0.36 ms | 130.7 ms |
### Scenario: Tests with complex parameter combinations creating 25-125 test variations
```
BenchmarkDotNet v0.15.6, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.100-rc.2.25502.107
[Host] : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Job-GVKUBM : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Runtime=.NET 10.0
```
| Method | Version | Mean | Error | StdDev | Median |
|---------- |-------- |------------:|---------:|---------:|------------:|
| TUnit | 1.0.48 | 544.97 ms | 5.561 ms | 4.930 ms | 544.99 ms |
| NUnit | 4.4.0 | 1,540.60 ms | 5.644 ms | 4.713 ms | 1,540.91 ms |
| MSTest | 4.0.1 | 1,499.17 ms | 4.590 ms | 3.833 ms | 1,499.42 ms |
| xUnit3 | 3.2.0 | 1,591.72 ms | 6.560 ms | 6.136 ms | 1,592.55 ms |
| TUnit_AOT | 1.0.48 | 79.41 ms | 0.252 ms | 0.236 ms | 79.48 ms |
### Scenario: Large-scale parameterized tests with 100+ test cases testing framework scalability
```
BenchmarkDotNet v0.15.6, Linux Ubuntu 24.04.3 LTS (Noble Numbat)
AMD EPYC 7763 2.45GHz, 1 CPU, 4 logical and 2 physical cores
.NET SDK 10.0.100-rc.2.25502.107
[Host] : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Job-GVKUBM : .NET 10.0.0 (10.0.0-rc.2.25502.107, 10.0.25.50307), X64 RyuJIT x86-64-v3
Runtime=.NET 10.0
```
| Method | Version | Mean | Error | StdDev | Median |
|---------- |-------- |----------:|----------:|----------:|----------:|
| TUnit | 1.0.48 | 498.22 ms | 7.188 ms | 6.723 ms | 496.45 ms |
| NUnit | 4.4.0 | 584.65 ms | 11.669 ms | 11.461 ms | 582.38 ms |
| MSTest | 4.0.1 | 580.53 ms | 11.233 ms | 15.747 ms | 583.58 ms |
| xUnit3 | 3.2.0 | 587.89 ms | 8.750 ms | 7.757 ms | 586.15 ms |
| TUnit_AOT | 1.0.48 | 46.75 ms | 1.442 ms | 4.253 ms | 47.33 ms |
", Assign "at most 3 tags" to the expected json: {"id":"11781","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"