{"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 runtimepublicclassTraditionalTests
{
[Fact] // Only discovered at runtimepublicvoidTestMethod() { }
}
```text
### TUnit's Innovative Approach
```csharp
// TUnit generates test registration code at compile time through Source GeneratorpublicclassModernTests
{
[Test] // Processed and optimized at compile timepublicasync Task TestMethod()
{
await Assert.That(true).IsTrue();
}
}
```text
### Advantages1. 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**:
### 2. AOT (Ahead-of-Time) Compilation Support
### JIT vs AOT Compilation Flow
# source → IL bytecode → JIT compile at runtime → machine code → execute
# source → directly generate at compile time → machine code → execute directly
### AOT Compilation Advantages
fast startup time (no waiting for JIT compilation)
- Smaller memory footprint
- Predictable performance
- More suitable for containerized deployment
### Enable AOT Support
```xml
<PropertyGroup>
<PublishAot>true</PublishAot>
<InvariantGlobalization>true</InvariantGlobalization>
</PropertyGroup>
```text
### Actual Performance Differences
```text
Traditional JIT compilation test startup time: ~1-2 seconds
TUnit AOT compilation test startup time: ~50-100 milliseconds
(Large projects can achieve 10-30x startup time improvement)
```text
### 3. Microsoft.Testing.Platform Adoption
TUnit is built on Microsoft's latest Microsoft.Testing.Platform, not the traditional VSTest platform:
- Lighter test runner
- Better parallel control mechanism
- Native support for latest IDE integration
### Important Notes
TUnit projects **donot need** and **should not** install `Microsoft.NET.Test.Sdk` package.
### 4. Default Parallel Execution
TUnit sets parallel execution asdefaultand provides fine-grained control:
```csharp
// Default all tests execute in parallel
[Test]
publicasync Task ParallelTest1()
Large test suites (1000+ tests)
3. **Advanced Tech Stack**: Using .NET 8+, planning AOT adoption
4. **Heavy CI/CD Usage**: Test execution time directly impacts deployment frequency
5. **Containerized Deployment**: Fast startup time is important
### Not Recommended for Now
1. **Legacy Projects**: Already have large amounts of xUnit tests
2. **Conservative Teams**: Need stability over innovation
3. **Complex Test Ecosystem**: Heavy use of xUnit specific packages
4. **Old .NET Versions**: Still on .NET 6/7
---
## Reference Resources
### Original Articles
This skill content is distilled from the "Old School Software Engineer's Testing Practice - 30 Day Challenge" article series:
- **Day 28 - TUnit Introduction - Next Generation .NET Testing Framework Exploration**
- Article: https://ithelp.ithome.com.tw/articles/10377828
- Sample code: https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day28
### Official Resources
- [TUnit Official Website](https://tunit.dev/)
- [TUnit GitHub](https://github.com/thomhurst/TUnit)
- [Migration from xUnit Guide](https://tunit.dev/docs/migration/xunit)
### Microsoft Official Documentation
- [Microsoft.Testing.Platform Introduction](https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-intro)
- [Native AOT Deployment](https://learn.microsoft.com/dotnet/core/deploying/native-aot)
