csharp-tunit

---
name: csharp-tunit
description: "Get best practices for TUnit unit testing, including data-driven tests"
---

# TUnit Best Practices

Your goal is to help me write effective unit tests with TUnit, covering both standard and data-driven testing approaches.

## Project Setup

- Use a separate test project with naming convention `[ProjectName].[TestType]` (e.g., `MyApp.UnitTests`)
- Reference TUnit package and TUnit.Assertions for fluent assertions
- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`)
- Use .NET SDK test commands: `dotnet test` for running tests
- TUnit requires .NET 8.0 or higher

## Test Structure

- No test class attributes required (like xUnit/NUnit)
- Use `[Test]` attribute for test methods (not `[Fact]` like xUnit)
- Follow the Arrange-Act-Assert (AAA) pattern
- Name tests using the pattern `Given[Condition]_When[Action]_Then[ExpectedResult]` for clarity
- Use lifecycle hooks: `[Before(Test)]` for setup and `[After(Test)]` for teardown
- Use `[Before(Class)]` and `[After(Class)]` for shared context between tests in a class
- Use `[Before(Assembly)]` and `[After(Assembly)]` for shared context across test classes
- TUnit supports advanced lifecycle hooks like `[Before(TestSession)]` and `[After(TestSession)]`

## Standard Tests

- Keep tests focused on a single behavior
- Avoid testing multiple behaviors in one test method
- Use Shouldly's fluent assertion syntax (e.g., `actual.ShouldBe(expected)`)
- Include only the assertions needed to verify the test case
- Make tests independent and idempotent (can run in any order)
- Avoid test interdependencies (use `[DependsOn]` attribute if needed)

## Data-Driven Tests

- Use `[Arguments]` attribute for inline test data (equivalent to xUnit's `[InlineData]`)
- Use `[MethodData]` for method-based test data (equivalent to xUnit's `[MemberData]`)
- Use `[ClassData]` for class-based test data
- Create custom data sources by implementing `ITestDataSource`
- Use meaningful parameter names in data-driven tests
- Multiple `[Arguments]` attributes can be applied to the same test method

## Assertions (Shouldly)

- Use `actual.ShouldBe(expected)` for value equality
- Use `actual.ShouldBeSameAs(expected)` for reference equality
- Use `actual.ShouldBeTrue()` or `actual.ShouldBeFalse()` for boolean conditions
- Use `actual.ShouldBeNull()` or `actual.ShouldNotBeNull()` for null checks
- Use `actual.ShouldContain(item)` or `actual.ShouldNotContain(item)` for collections
- Use `actual.ShouldContain("substring")` for string containment
- Use `actual.ShouldMatch(pattern)` for regex pattern matching
- Use `actual.ShouldBeGreaterThan(value)`, `actual.ShouldBeLessThan(value)` for comparisons
- Use `actual.ShouldBeOfType<T>()` for type assertions
- Use `actual.ShouldBeEmpty()` or `actual.ShouldNotBeEmpty()` for collections and strings
- Use `Should.Throw<TException>(() => action)` for sync exception testing
- Use `Should.Throw<TException>(async () => await asyncAction)` for async exception testing
- Use `Should.NotThrow(() => action)` to verify no exception is thrown
- All Shouldly assertions are synchronous (no `await` needed except for async exception testing)

## Advanced Features

- Use `[Repeat(n)]` to repeat tests multiple times
- Use `[Retry(n)]` for automatic retry on failure
- Use `[ParallelLimit<T>]` to control parallel execution limits
- Use `[Skip("reason")]` to skip tests conditionally
- Use `[DependsOn(nameof(OtherTest))]` to create test dependencies
- Use `[Timeout(milliseconds)]` to set test timeouts
- Create custom attributes by extending TUnit's base attributes

## Test Organization

- Group tests by feature or component
- Use `[Category("CategoryName")]` for test categorization
- Use `[DisplayName("Custom Test Name")]` for custom test names
- Consider using `TestContext` for test diagnostics and information
- Use conditional attributes like custom `[WindowsOnly]` for platform-specific tests

## Performance and Parallel Execution

- TUnit runs tests in parallel by default (unlike xUnit which requires explicit configuration)
- Use `[NotInParallel]` to disable parallel execution for specific tests
- Use `[ParallelLimit<T>]` with custom limit classes to control concurrency
- Tests within the same class run sequentially by default
- Use `[Repeat(n)]` with `[ParallelLimit<T>]` for load testing scenarios

## Migration from xUnit

- Replace `[Fact]` with `[Test]`
- Replace `[Theory]` with `[Test]` and use `[Arguments]` for data
- Replace `[InlineData]` with `[Arguments]`
- Replace `[MemberData]` with `[MethodData]`
- Replace `Assert.Equal` with `actual.ShouldBe(expected)`
- Replace `Assert.True` with `condition.ShouldBeTrue()`
- Replace `Assert.Throws<T>` with `Should.Throw<T>(() => action)`
- Replace constructor/IDisposable with `[Before(Test)]`/`[After(Test)]`
- Replace `IClassFixture<T>` with `[Before(Class)]`/`[After(Class)]`

**Why TUnit over xUnit?**

TUnit offers a modern, fast, and flexible testing experience with advanced features not present in xUnit, such as asynchronous assertions, more refined lifecycle hooks, and improved data-driven testing capabilities. TUnit's fluent assertions provide clearer and more expressive test validation, making it especially suitable for complex .NET projects.