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] [ParallelLimiter<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] [ParallelLimiter<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 `[ParallelLimiter]` 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)] [ParallelLimiter<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"