dotnet-testing-advanced-tunit-fundamentals

name	dotnet-testing-advanced-tunit-fundamentals
category	testing
subcategory	frameworks
description	Complete guide for TUnit new-generation testing framework. Use when creating test projects with TUnit or migrating from xUnit to TUnit. Covers Source Generator driven test discovery, AOT compilation support, fluent async assertions. Includes project creation, [Test] attribute, lifecycle management, parallel control, and xUnit syntax comparison. Keywords: TUnit, tunit testing, source generator testing, AOT testing, new generation testing framework, [Test], [Arguments], TUnit.Assertions, Assert.That, Before(Test), After(Test), NotInParallel, TUnit.Templates, Microsoft.Testing.Platform, TUnit vs xUnit, parallel execution
targets	["*"]
license	MIT
metadata	{"author":"Kevin Tseng","version":"1.0.0","tags":"tunit, testing-framework, source-generator, aot, modern-testing, performance","related_skills":"advanced-tunit-advanced, xunit-project-setup, unit-test-fundamentals"}
claudecode	{}
opencode	{}
codexcli	{"short-description":".NET skill guidance for dotnet-testing-advanced-tunit-fundamentals"}
copilot	{}
geminicli	{}
antigravity	{}

Source: kevintsengtw/dotnet-testing-agent-skills (MIT). Ported into dotnet-agent-harness.

TUnit New Generation Testing Framework Introduction

Applicable Scenarios

This skill covers TUnit new-generation .NET testing framework introduction basics, from framework features to actual project creation and test writing.

Core Topics

• TUnit framework features and design philosophy
• Source Generator driven test discovery
• AOT (Ahead-of-Time) compilation support
• Fluent async assertion system
• Project creation and package configuration
• Syntax differences compared to xUnit

---

TUnit Framework Core Features

1. Source Generator Driven Test Discovery

TUnit's biggest difference from traditional testing frameworks is using Source Generator to complete test discovery at compile time:

Traditional Framework Approach (xUnit)

// xUnit discovers all methods through reflection at runtime
public class TraditionalTests
{
    [Fact] // Only discovered at runtime
    public void TestMethod() { }
}
```text

### TUnit's Innovative Approach

```csharp
// TUnit generates test registration code at compile time through Source Generator
public class ModernTests
{
    [Test] // Processed and optimized at compile time
    public async Task TestMethod()
    {
        await Assert.That(true).IsTrue();
    }
}
```text

### Advantages

1. Avoid reflection cost: All test discovery completed at compile time
2. AOT compatible: Fully supports Native AOT compilation
3. Faster startup time: Especially in large test projects





```text
Traditional JIT: C
AOT:           C
```text



- Ultra- { }

[]
 { }


[]
[]
 { }
```text

---





```bash

mkdir TUnitDemo
cd TUnitDemo


dotnet  sln -n MyApp


dotnet  classlib -n MyApp.Core -o src/MyApp.Core


dotnet  console -n MyApp.Tests -o tests/MyApp.Tests


dotnet sln  src/MyApp.Core/MyApp.Core.csproj
dotnet sln  tests/MyApp.Tests/MyApp.Tests.csproj


dotnet  tests/MyApp.Tests/MyApp.Tests.csproj reference src/MyApp.Core/MyApp.Core.csproj
```text



```bash

dotnet  install TUnit.Templates


dotnet  tunit -n MyApp.Tests -o tests/MyApp.Tests
```text



```xml
<Project Sdk=>

  <PropertyGroup>
    <TargetFramework>net9</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsPackable></IsPackable>
    <IsTestProject></IsTestProject>
  </PropertyGroup>

  <ItemGroup>
    <!-- TUnit core packages -->
    <PackageReference Include= Version= />
    <!-- Code coverage support -->
    <PackageReference Include= Version= />
    <!-- TRX report support -->
    <PackageReference Include= Version= />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include= />
  </ItemGroup>

</Project>
```text



```csharp

  TUnit.Core;
  TUnit.Assertions;
  MyApp.Core;
```text

---



TUnit **requires all test methods to be **,   a framework technical requirement:

```csharp

[]

{
    Assert.That( + ).IsEqualTo();
}


[]

{
     Assert.That( + ).IsEqualTo();
}
```text

---





TUnit uniformly uses `[Test]` attribute, unlike xUnit which distinguishes `[Fact]`  `[Theory]`:

```csharp

[]

{
     calculator =  Calculator();
     result = calculator.Add(, );
     Assert.That(result).IsEqualTo();
}
```text



```csharp

[]
[]
[]
[]
[]

{
     calculator =  Calculator();
     result = calculator.Add(a, b);
     Assert.That(result).IsEqualTo(expected);
}
```text

---



TUnit adopts fluent assertion design, all assertions are . Supports equality, boolean, numeric comparison, , collection, exception,  other assertions,  can combine conditions through `And` / `Or`.

```csharp

 Assert.That(actual).IsEqualTo(expected);
 Assert.That(email).Contains().And.EndsWith();
 Assert.That(() => action()).Throws<InvalidOperationException>();
```text

> 📖 Complete assertion types  examples please refer to [TUnit Assertion System Detailed Description](references/tunit-assertions-detail.md)

---



TUnit supports constructor / `Dispose` pattern,  `[Before(Test)]`, `[Before(Class)]`, `[After(Test)]`, `[After(Class)]`  other attributes, providing more refined lifecycle control than xUnit.

```text
Execution order: Before(Class) → Constructor → Before(Test) → Test Method → After(Test) → Dispose → After(Class)
```text

> 📖 Complete lifecycle examples  attribute comparison table please refer to [Lifecycle Management Detailed Description](references/lifecycle-management.md)

---





```csharp

[]
 { }

[]
 { }


[]
[]

{
    
}

[]
[]

{
    
}
```text

---



| Feature | xUnit | TUnit |
| ------- | ----- | ----- |
| **Basic Test** | `[Fact]` | `[Test]` |
| **Parameterized Test** | `[Theory]` + `[InlineData]` | `[Test]` + `[Arguments]` |
| **Basic Assertion** | `Assert.Equal(expected, actual)` | ` Assert.That(actual).IsEqualTo(expected)` |
| **Boolean Assertion** | `Assert.True(condition)` | ` Assert.That(condition).IsTrue()` |
| **Exception Test** | `Assert.Throws<T>(() => action())` | ` Assert.That(() => action()).Throws<T>()` |
| **Null Check** | `Assert.Null()` | ` Assert.That().IsNull()` |
| **String Check** | `Assert.Contains(, fullString)` | ` Assert.That(fullString).Contains()` |





```csharp
[]
[]
[]

{
     result = _validator.IsValidEmail(email);
    Assert.Equal(expected, result);
}
```text



```csharp
[]
[]
[]

{
     result = _validator.IsValidEmail(email);
     Assert.That(result).IsEqualTo(expected);
}
```text



 `[Theory]` → `[Test]`
 `[InlineData]` → `[Arguments]`
 Method changed to ` Task`
 All assertions prefixed  ``
 Fluent assertion syntax

---





```bash

dotnet build


dotnet test


dotnet test --verbosity normal


dotnet test --coverage


dotnet test --filter 
dotnet test --filter 
```text



```bash

dotnet publish -c Release -p:PublishAot=


.\bin\Release\net9\publish\MyApp.Tests.exe
```text





- Version + 
- Enable 



- Install C
- Enable 



- Enable 

---



| Scenario | xUnit | TUnit | TUnit AOT | Performance Gain |
| -------- | ----- | ----- | --------- | ---------------- |
| **Simple Test Execution** | ,ms | ,ms | ms | x (AOT) |
| **Async Test** | ,ms | ms | ms | x (AOT) |
| **Parallel Test** | ,ms | ms | ms | x (AOT) |

---





**Error:** Installed `Microsoft.NET.Test.Sdk` causing tests  discoverable

**Solution:** Remove `Microsoft.NET.Test.Sdk`, TUnit uses  testing platform



**Symptom:** Tests  displaying  executing  IDE



 Confirm IDE version supports Microsoft.Testing.Platform
 Enable relevant preview features
 Reload project  restart IDE



**Symptom:** Compilation errors  assertions  executing properly

**Solution:** All assertions need ``, test methods must be ` Task`

---





 **New Projects**: No legacy baggage
 **High Performance Requirements**: