feat: Add TUnit skill and references for testing framework, assertions, attributes, data-driven tests, and integration patterns

Author: aalmada

.github/skills/tunit/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: tunit
+description: >
+  Write, review, and fix TUnit tests in .NET projects. Use this skill whenever
+  you're writing a new test class, adding assertions, creating data-driven tests,
+  setting up test lifecycle hooks, or debugging why a test compiles but behaves
+  unexpectedly. Also triggers for: migrating from xUnit/NUnit to TUnit, choosing
+  the right assertion, using Bogus for test data, wiring up NSubstitute mocks,
+  writing integration tests, or any question about parallelism and test ordering.
+  Prefer this skill over guessing — TUnit's async-first API has several
+  non-obvious patterns that differ from xUnit/NUnit.
+---
+
+# TUnit Testing Skill
+
+TUnit is a modern .NET testing framework that is async-first, source-generated,
+and runs on Microsoft.Testing.Platform.
+
+---
+
+## Quick-start anatomy
+
+```csharp
+public class OrderHandlerTests
+{
+    [Test]
+    [Category("Unit")]                             // categorise for filtering
+    public async Task PlaceOrder_Valid_ReturnsOk()
+    {
+        // Arrange …
+        // Act …
+        // Assert — always await the assertion
+        await Assert.That(result).IsNotNull();
+        await Assert.That(result.Status).IsEqualTo("Confirmed");
+    }
+}
+```
+
+Key rule: **every assertion line must be `await`-ed**. Forgetting the `await`
+silently skips the assertion.
+
+---
+
+## Reference files — read before writing code
+
+| Topic | File |
+|-------|------|
+| Assertion API (equality, nulls, booleans, collections, strings, exceptions, multiple) | [references/assertions.md](references/assertions.md) |
+| All attributes (Test, Category, Arguments, Before/After, Retry, Repeat, NotInParallel…) | [references/attributes.md](references/attributes.md) |
+| Data-driven tests (Arguments, MethodDataSource, ClassDataSource) | [references/data-driven.md](references/data-driven.md) |
+| Integration test patterns (Aspire, test infrastructure, async helpers) | [references/integration-patterns.md](references/integration-patterns.md) |
+
+---
+
+## Core rules
+
+```
+✅ [Test] async Task               ❌ [Fact] / [TestMethod] / [TestCase]
+✅ await Assert.That(...)          ❌ Assert.Equal / FluentAssertions
+✅ Per-test data creation          ❌ shared mutable state between tests
+```
+
+---
+
+## Running tests
+
+```bash
+dotnet test                                              # all projects (parallel)
+dotnet test -- --maximum-parallel-tests 4               # cap parallelism
+dotnet test -- --treenode-filter "/*/*/*/*[Category=Unit]" # filter by category
+dotnet test --project tests/MyProject.Tests/MyProject.Tests.csproj
+```
+
+---
+
+## Common mistakes & fixes
+
+| Mistake | Fix |
+|---------|-----|
+| Assertion silently skipped | Add `await` to every `Assert.That(…)` call |
+| Tests interfere with each other | Create all test data inside each test; never share mutable fields |
+| Polling for eventual consistency | Use condition helpers or WaitForConditionAsync patterns; never `Task.Delay` |
+| `Assert.Fail` not reached after exception | Use `Assert.That(…).Throws<T>()` pattern instead of try/catch |
+| Missing `[Before(Class)]` / `[After(Class)]` | Hooks must be `public static async Task`; see attributes reference |
+| Data-driven test parameters don't compile | Types in `[Arguments]` must exactly match method parameter types |

.github/skills/tunit/references/assertions.md

@@ -0,0 +1,154 @@
+# TUnit Assertion Reference
+
+All assertions are async and must be `await`-ed.
+
+```csharp
+await Assert.That(actual).IsEqualTo(expected);
+```
+
+---
+
+## Equality & comparison
+
+```csharp
+await Assert.That(actual).IsEqualTo(expected);
+await Assert.That(actual).IsNotEqualTo(unexpected);
+await Assert.That(number).IsGreaterThan(0);
+await Assert.That(number).IsGreaterThanOrEqualTo(1);
+await Assert.That(number).IsLessThan(100);
+await Assert.That(number).IsLessThanOrEqualTo(99);
+await Assert.That(number).IsBetween(1, 99);        // inclusive
+```
+
+---
+
+## Null & existence
+
+```csharp
+await Assert.That(value).IsNull();
+await Assert.That(value).IsNotNull();
+```
+
+---
+
+## Boolean
+
+```csharp
+await Assert.That(flag).IsTrue();
+await Assert.That(flag).IsFalse();
+```
+
+---
+
+## Type checks
+
+```csharp
+await Assert.That(obj).IsTypeOf<MyType>();
+await Assert.That(obj).IsNotTypeOf<WrongType>();
+await Assert.That(obj).IsAssignableTo<IMyInterface>();
+```
+
+---
+
+## Collections
+
+```csharp
+await Assert.That(list).IsEmpty();
+await Assert.That(list).IsNotEmpty();
+await Assert.That(list).Contains(item);
+await Assert.That(list).DoesNotContain(item);
+await Assert.That(list).Count().IsEqualTo(3);
+await Assert.That(list).HasSingleItem();
+```
+
+---
+
+## Strings
+
+```csharp
+await Assert.That(text).IsEqualTo("exact");
+await Assert.That(text).IsEmpty();
+await Assert.That(text).IsNotEmpty();
+await Assert.That(text).Contains("sub");
+await Assert.That(text).DoesNotContain("absent");
+await Assert.That(text).StartsWith("prefix");
+await Assert.That(text).EndsWith("suffix");
+await Assert.That(text).Matches(@"^\d{4}-\d{2}-\d{2}$");  // regex
+```
+
+---
+
+## Exceptions
+
+```csharp
+// Synchronous throw wrapped in a lambda
+await Assert.ThrowsAsync<ArgumentException>(() =>
+{
+    SomeMethod();
+    return Task.CompletedTask;
+});
+
+// Async throw
+await Assert.ThrowsAsync<InvalidOperationException>(async () =>
+    await SomeAsyncMethod());
+
+// Capture and inspect the exception
+var ex = await Assert.ThrowsAsync<ApiException>(async () =>
+    await client.GetBookAsync(id));
+await Assert.That(ex!.StatusCode).IsEqualTo(HttpStatusCode.NotFound);
+
+// Verify NO exception is thrown (rarely needed — just call the method directly)
+await Assert.DoesNotThrowAsync(async () => await SafeMethod());
+```
+
+---
+
+## Multiple assertions grouped (Assert.Multiple)
+
+Use `Assert.Multiple()` to run several assertions and collect all failures before
+reporting, rather than stopping at the first failure.
+
+```csharp
+[Test]
+public async Task Constructor_SetsAllProperties()
+{
+    var date = new PartialDate(2023, 5, 15);
+
+    using var scope = Assert.Multiple();
+    await Assert.That(date.Year).IsEqualTo(2023);
+    await Assert.That(date.Month).IsEqualTo(5);
+    await Assert.That(date.Day).IsEqualTo(15);
+}
+```
+
+> `Assert.Multiple()` returns an `IDisposable`; always wrap in `using var scope`.
+
+---
+
+## Chained member assertions (single await, multiple properties)
+
+```csharp
+await Assert.That(user)
+    .IsNotNull()
+    .And.Member(u => u.Email, e => e.IsEqualTo("john@example.com"))
+    .And.Member(u => u.Age, a => a.IsGreaterThan(18));
+```
+
+---
+
+## Assert.Fail
+
+Use when a code path should never be reached:
+
+```csharp
+Assert.Fail("Expected an exception, but none was thrown.");
+```
+
+---
+
+## Awaiting assertions — why it matters
+
+TUnit returns a lazy assertion object from `Assert.That(…)`. The assertion is only
+evaluated when `await`-ed. Missing the `await` means the check is never run and
+the test passes silently even when the code is wrong. This is the most common
+mistake when migrating from xUnit/NUnit.