|
| 1 | +--- |
| 2 | +mode: 'agent' |
| 3 | +tools: ['changes', 'codebase', 'editFiles', 'problems', 'search'] |
| 4 | +description: 'Get best practices for TUnit unit testing, including data-driven tests' |
| 5 | +--- |
| 6 | + |
| 7 | +# TUnit Best Practices |
| 8 | + |
| 9 | +Your goal is to help me write effective unit tests with TUnit, covering both standard and data-driven testing approaches. |
| 10 | + |
| 11 | +## Project Setup |
| 12 | + |
| 13 | +- Use a separate test project with naming convention `[ProjectName].Tests` |
| 14 | +- Reference TUnit package and TUnit.Assertions for fluent assertions |
| 15 | +- Create test classes that match the classes being tested (e.g., `CalculatorTests` for `Calculator`) |
| 16 | +- Use .NET SDK test commands: `dotnet test` for running tests |
| 17 | +- TUnit requires .NET 8.0 or higher |
| 18 | + |
| 19 | +## Test Structure |
| 20 | + |
| 21 | +- No test class attributes required (like xUnit/NUnit) |
| 22 | +- Use `[Test]` attribute for test methods (not `[Fact]` like xUnit) |
| 23 | +- Follow the Arrange-Act-Assert (AAA) pattern |
| 24 | +- Name tests using the pattern `MethodName_Scenario_ExpectedBehavior` |
| 25 | +- Use lifecycle hooks: `[Before(Test)]` for setup and `[After(Test)]` for teardown |
| 26 | +- Use `[Before(Class)]` and `[After(Class)]` for shared context between tests in a class |
| 27 | +- Use `[Before(Assembly)]` and `[After(Assembly)]` for shared context across test classes |
| 28 | +- TUnit supports advanced lifecycle hooks like `[Before(TestSession)]` and `[After(TestSession)]` |
| 29 | + |
| 30 | +## Standard Tests |
| 31 | + |
| 32 | +- Keep tests focused on a single behavior |
| 33 | +- Avoid testing multiple behaviors in one test method |
| 34 | +- Use TUnit's fluent assertion syntax with `await Assert.That()` |
| 35 | +- Include only the assertions needed to verify the test case |
| 36 | +- Make tests independent and idempotent (can run in any order) |
| 37 | +- Avoid test interdependencies (use `[DependsOn]` attribute if needed) |
| 38 | + |
| 39 | +## Data-Driven Tests |
| 40 | + |
| 41 | +- Use `[Arguments]` attribute for inline test data (equivalent to xUnit's `[InlineData]`) |
| 42 | +- Use `[MethodData]` for method-based test data (equivalent to xUnit's `[MemberData]`) |
| 43 | +- Use `[ClassData]` for class-based test data |
| 44 | +- Create custom data sources by implementing `ITestDataSource` |
| 45 | +- Use meaningful parameter names in data-driven tests |
| 46 | +- Multiple `[Arguments]` attributes can be applied to the same test method |
| 47 | + |
| 48 | +## Assertions |
| 49 | + |
| 50 | +- Use `await Assert.That(value).IsEqualTo(expected)` for value equality |
| 51 | +- Use `await Assert.That(value).IsSameReferenceAs(expected)` for reference equality |
| 52 | +- Use `await Assert.That(value).IsTrue()` or `await Assert.That(value).IsFalse()` for boolean conditions |
| 53 | +- Use `await Assert.That(collection).Contains(item)` or `await Assert.That(collection).DoesNotContain(item)` for collections |
| 54 | +- Use `await Assert.That(value).Matches(pattern)` for regex pattern matching |
| 55 | +- Use `await Assert.That(action).Throws<TException>()` or `await Assert.That(asyncAction).ThrowsAsync<TException>()` to test exceptions |
| 56 | +- Chain assertions with `.And` operator: `await Assert.That(value).IsNotNull().And.IsEqualTo(expected)` |
| 57 | +- Use `.Or` operator for alternative conditions: `await Assert.That(value).IsEqualTo(1).Or.IsEqualTo(2)` |
| 58 | +- Use `.Within(tolerance)` for DateTime and numeric comparisons with tolerance |
| 59 | +- All assertions are asynchronous and must be awaited |
| 60 | + |
| 61 | +## Advanced Features |
| 62 | + |
| 63 | +- Use `[Repeat(n)]` to repeat tests multiple times |
| 64 | +- Use `[Retry(n)]` for automatic retry on failure |
| 65 | +- Use `[ParallelLimit<T>]` to control parallel execution limits |
| 66 | +- Use `[Skip("reason")]` to skip tests conditionally |
| 67 | +- Use `[DependsOn(nameof(OtherTest))]` to create test dependencies |
| 68 | +- Use `[Timeout(milliseconds)]` to set test timeouts |
| 69 | +- Create custom attributes by extending TUnit's base attributes |
| 70 | + |
| 71 | +## Test Organization |
| 72 | + |
| 73 | +- Group tests by feature or component |
| 74 | +- Use `[Category("CategoryName")]` for test categorization |
| 75 | +- Use `[DisplayName("Custom Test Name")]` for custom test names |
| 76 | +- Consider using `TestContext` for test diagnostics and information |
| 77 | +- Use conditional attributes like custom `[WindowsOnly]` for platform-specific tests |
| 78 | + |
| 79 | +## Performance and Parallel Execution |
| 80 | + |
| 81 | +- TUnit runs tests in parallel by default (unlike xUnit which requires explicit configuration) |
| 82 | +- Use `[NotInParallel]` to disable parallel execution for specific tests |
| 83 | +- Use `[ParallelLimit<T>]` with custom limit classes to control concurrency |
| 84 | +- Tests within the same class run sequentially by default |
| 85 | +- Use `[Repeat(n)]` with `[ParallelLimit<T>]` for load testing scenarios |
| 86 | + |
| 87 | +## Migration from xUnit |
| 88 | + |
| 89 | +- Replace `[Fact]` with `[Test]` |
| 90 | +- Replace `[Theory]` with `[Test]` and use `[Arguments]` for data |
| 91 | +- Replace `[InlineData]` with `[Arguments]` |
| 92 | +- Replace `[MemberData]` with `[MethodData]` |
| 93 | +- Replace `Assert.Equal` with `await Assert.That(actual).IsEqualTo(expected)` |
| 94 | +- Replace `Assert.True` with `await Assert.That(condition).IsTrue()` |
| 95 | +- Replace `Assert.Throws<T>` with `await Assert.That(action).Throws<T>()` |
| 96 | +- Replace constructor/IDisposable with `[Before(Test)]`/`[After(Test)]` |
| 97 | +- Replace `IClassFixture<T>` with `[Before(Class)]`/`[After(Class)]` |
| 98 | + |
| 99 | +**Why TUnit over xUnit?** |
| 100 | + |
| 101 | +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. |
0 commit comments