AGENT SKILL

deniz-dotnet-general.writing-tunit-tests

Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 1
Forks
0

01 前言 Front Matter

name
deniz-dotnet-general.writing-tunit-tests
description
Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.

02 资源文件 1

03 SKILL.md 正文

Writing TUnit Tests

TUnit is a .NET test framework built on Microsoft.Testing.Platform with compile-time test discovery. Almost everything about it that surprises people comes from two design choices: assertions are async, and every test gets its own instance and runs in parallel with every other test. Get those two right and the rest is ordinary.

This skill is the syntax and the semantics. When a test's oracle depends on time, concurrency, a process boundary, or a mutant, read references/oracle-rules.md as well. It does not cover:

  • what to test, and in what order — that is the red-green loop in deniz-process.test-driven-development
  • whether a test is worth having — deniz-dotnet-general.test-gap-analysis asks whether a test would catch a real bug, deniz-dotnet-general.test-anti-patterns catches the smells
  • running or filtering tests — deniz-dotnet-general.run-tests gives the exact command, deniz-dotnet-general.filter-syntax the filter
  • making untestable code testable — that is a seam problem, and the ceremony that builds the abstraction is one the human starts by name: @deniz-dotnet-general.generate-testability-wrappers

Setting up a project

The template is the shortest path, and it needs installing first:

dotnet new install TUnit.Templates
dotnet new TUnit -n MyProject.Tests

By hand, the test project is a console executable, not a library:

dotnet new console -n MyProject.Tests
cd MyProject.Tests
dotnet add package TUnit

Then delete the generated Program.cs and make sure the project keeps <OutputType>Exe</OutputType>. The TUnit meta-package pulls in the assertions, the engine, the analyzers and coverage support.

Three things break discovery, and all three are things a .NET developer adds out of habit:

  • Microsoft.NET.Test.Sdk — remove it. It is VSTest infrastructure and TUnit is not VSTest.
  • coverlet.collector / coverlet.msbuild — remove them for the same reason. Coverage comes from Microsoft.Testing.Extensions.CodeCoverage, already in the meta-package, via --coverage.
  • A missing <OutputType>Exe</OutputType> — without it nothing is discovered at all.

The sample project targets net8.0. TUnit also ships a netstandard2.0 target, so .NET Framework works, but it needs a polyfill package for types the old BCL lacks (ModuleInitializerAttribute among them).

The shape of a test

public class CheckoutTests
{
    [Test]
    public async Task Discount_is_applied_to_a_gold_tier_subtotal()
    {
        var checkout = new CheckoutService();

        var total = await checkout.ApplyDiscountAsync("GOLD", 100.00);

        await Assert.That(total).IsEqualTo(80.00);
    }
}

[Test] on the method, and nothing on the class — there is no [TestClass] or [TestFixture]. Test methods must be public instance methods. The bundled analyzers reject private or static tests, and generated invocations can produce ordinary C# compiler errors too — fix the build rather than looking for a silently missing test.

A test with no assertion passes as long as it does not throw. That is occasionally what you want (a smoke test that a pipeline runs at all), but state it deliberately rather than by accident.

Assertions: everything is awaited

This is the rule that catches everyone:

await Assert.That(result).IsEqualTo(3);

Assert.That(result).IsEqualTo(3) without await does nothing at runtime. The fluent chain only builds a rule; await is what executes it. In a normal TUnit project the bundled analyzer makes a forgotten await a build error. If that analyzer is removed, suppressed, or demoted, the test can instead pass silently whatever the value was.

Two things save you. The design reason: because every assertion is async, you never have to remember which ones need awaiting — they all do. And the mechanical backstop: the bundled analyzer raises TUnitAssertions0002 ("Assert statements must be awaited") with a code fix. If you see that ID in build output, that is what it means.

The catalogue, by what you are asserting:

Asserting Written as
Equality IsEqualTo(x) / IsNotEqualTo(x)
Same instance IsSameReferenceAs(x) / IsNotSameReferenceAs(x)
Booleans IsTrue() / IsFalse()
Numbers IsGreaterThan(x), IsLessThan(x), IsEqualTo(x).Within(0.001)
Collections Contains(item) / DoesNotContain(item), predicate overloads too
Strings Contains, StartsWith, EndsWith, Matches(pattern)
Exceptions Throws<T>(), ThrowsExactly<T>(), ThrowsNothing()

Prefer the specific assertion over a boolean: Assert.That(count).IsGreaterThan(0) reports what it actually saw, while Assert.That(count > 0).IsTrue() can only tell you false.

Numeric tolerance has to match the type — Within(0.01f) for a float, Within(0.01m) for a decimal.

String assertions take modifiers: .IgnoringCase(), .IgnoringWhitespace(), .WithTrimming(), .WithComparison(StringComparison.Ordinal).

Exceptions

The fluent form wraps a delegate, and it is the same Throws<T>() whether the delegate is sync or async:

await Assert.That(() => service.Parse("nonsense")).Throws<FormatException>();
await Assert.That(async () => await service.LoadAsync(id)).Throws<HttpRequestException>();

There is no fluent .ThrowsAsync<T>(). There is a static helper of that name which returns the exception when you want to assert on its contents:

var ex = await Assert.ThrowsAsync<ValidationException>(async () => await service.SaveAsync(bad));
await Assert.That(ex.Message).Contains("email");

Combining

.And and .Or both chain — but never in the same chain. Mixing them throws MixedAndOrAssertionsException at runtime, and the analyzer TUnitAssertions0001 flags it first. Split into two awaited assertions instead.

Data-driven tests

Inline rows:

[Test]
[Arguments("GOLD", 100.00, 80.00)]
[Arguments("SILVER", 100.00, 90.00)]
[Arguments("NONE", 100.00, 100.00)]
public async Task Discount_matches_the_tier(string tier, double subtotal, double expected)
{
    var total = await new CheckoutService().ApplyDiscountAsync(tier, subtotal);
    await Assert.That(total).IsEqualTo(expected);
}

Rows from a method use [MethodDataSource]. A static source is the simplest form:

[Test]
[MethodDataSource(nameof(DiscountCases))]
public async Task Discount_matches_the_tier(string tier, double subtotal, double expected) { }

public static IEnumerable<(string tier, double subtotal, double expected)> DiscountCases() =>
[
    ("GOLD", 100.00, 80.00),
    ("SILVER", 100.00, 90.00),
];

Prefer the tuple because it keeps rows strongly typed. TUnit also accepts IEnumerable<object[]>, but then the compiler cannot check each element against the matching test parameter. [MethodDataSource(typeof(Other), nameof(Other.Cases))] reaches another class, and [MethodDataSource<T>(nameof(T.Cases))] names a provider without reflection. Public instance sources are supported when TUnit can construct the test or provider instance; [InstanceMethodDataSource] makes that lifetime choice explicit.

[ClassDataSource<T>] is not a row provider. Despite the name it is the shared-fixture mechanism — the equivalent of xUnit's IClassFixture<T>. It injects one managed instance whose lifetime you choose:

[ClassDataSource<DatabaseFixture>(Shared = SharedType.PerClass)]
public class OrderRepositoryTests(DatabaseFixture db) { }

SharedType is None, PerClass, PerAssembly, PerTestSession, or Keyed (with Key). If you actually want rows from a class, use [MethodDataSource(nameof(MyClass.Rows))].

For a generated source, subclass DataSourceGeneratorAttribute<T…> (or the async / untyped variants) and override GenerateDataSources(DataGeneratorMetadata). It returns Func<…> delegates, not values. There is no ITestDataSource — that is an MSTest interface and it does not exist here.

Also available: [MatrixDataSource] with [Matrix(...)] per parameter for a cross product, and [GenerateGenericTest(typeof(...))] for generic test methods. TestDataRow<T> is not an attribute; return that wrapper from a data-source method when a row needs metadata such as a custom display name or categories.

Parallelism, and the instance rule that goes with it

Every test is eligible to run concurrently with every other test — including the ones in the same class. There is no implicit per-class serialisation. If you are coming from xUnit, this is the assumption to drop: xUnit collections serialise a class, TUnit does not.

Paired with that: a fresh instance of the test class is created for every test method.

Together those two make instance fields useless as a channel between tests, and the failure is quiet:

public class Wrong
{
    private int _value;                          // reset for every test

    [Test]
    public void Sets_it() => _value = 99;

    [Test]
    public async Task Reads_it()
        => await Assert.That(_value).IsEqualTo(99);   // fails: different instance, _value is 0
}

Share deliberately instead — static for genuinely global state, [ClassDataSource<T>] for a fixture with a managed lifetime.

When a test genuinely cannot run beside others, say so:

  • [NotInParallel] — with optional constraint keys and an Order
  • [ParallelGroup("name")] — everything in the group runs together, apart from other groups
  • [ParallelLimiter<T>] — cap concurrency, where T : IParallelLimit has a parameterless constructor and an int Limit. Mind the spelling: the attribute ends in -er, the interface does not. Assembly-wide: [assembly: ParallelLimiter<MyLimit>]

Ordering is a dependency, not a number: [DependsOn(nameof(OtherTest))] makes this test wait for that one while everything else keeps running. ProceedOnFailure = true runs it even if the dependency failed.

Lifecycle hooks

[Before(X)] and [After(X)] where X is Test, Class, Assembly, TestSession, or TestDiscovery. They nest outermost to innermost — TestSession, Assembly, Class, Test — and the After side unwinds in reverse.

Staticness is not optional, and the bundled analyzers fail the build when it is wrong:

Hook level Must be
Test instance
Class, Assembly, TestSession, TestDiscovery static
every [BeforeEvery(...)] / [AfterEvery(...)] static

[Before(Class)] runs once for this class. [BeforeEvery(Class)] runs before every class in the session — a different job, and the Every family is easy to miss.

Never write async void on a hook; it is a compile error here.

Multiple [After(Test)] methods all run even when one throws, and the exceptions are aggregated — so cleanup does not silently stop halfway.

Control attributes

Attribute Effect
[Repeat(n)] n more runs, so n + 1 total. [Repeat(3)] executes four times
[Retry(n)] Re-run on exception. Subclass RetryAttribute and override ShouldRetry to be selective
[Skip("reason")] Reason is required. Subclass for conditional skipping; Skip.Test(reason) skips at runtime, including from a [Before(Test)] hook
[Timeout(30_000)] Milliseconds. Take a CancellationToken parameter and pass it down, or the timeout cannot actually stop the work. Each retry gets a fresh one
[Category("Smoke")] Groups tests for filtering
[Property("key", "value")] Arbitrary metadata — the [Trait] equivalent
[DisplayName("Adds $a and $b")] $parameterName interpolates the argument

Scope depends on the attribute. Scoped controls such as repeat, retry, skip, and timeout resolve the most specific applicable value. Category and Property are additive metadata across their supported scopes, while DisplayName applies only to methods and classes.

Test output

There is no ITestOutputHelper. Ordinary test methods read the current context from TestContext.Current! — TestContext parameters are supported by test-level hooks, not injected into [Test] methods:

[Test]
public void Writes_a_note()
{
    var context = TestContext.Current!;
    context.Output.WriteLine("about to call the API");
}

Output.WriteError(...) and Output.AttachArtifact(...) are there too.

Mocking

TUnit ships a separate source-generated mocking package. Add it explicitly and use a C# 14-capable SDK/compiler; the TUnit meta-package alone does not include it:

dotnet add package TUnit.Mocks

It works under Native AOT where reflection-based mockers do not:

var mock = IGreeter.Mock();
mock.Greet(Any()).Returns("Hello!");

IGreeter greeter = mock;
var result = greeter.Greet("Alice");

mock.Greet("Alice").WasCalled(Times.Once);

Mock.Of<IGreeter>() is the alternative entry point. TUnit.Mocks.Http and TUnit.Mocks.Logging cover those two cases specifically. Ordinary mocking libraries still work — they are just libraries — but they give up AOT compatibility.

Compile-time discovery, and what it forbids

Tests are found by a Roslyn source generator, not by reflection. That is what makes Native AOT and single-file publish work — and it is the reason a few things that compile in other frameworks do not compile here.

Under Native AOT these are hard rules. A reflection mode exists (--reflection, [assembly: ReflectionMode], or TUNIT_EXECUTION_MODE=reflection) for cases the generator cannot see, such as bUnit Razor components — but it is exactly the thing AOT removes, so an AOT-published suite has no escape hatch. Write for the generator from the start.

What the generator has to be able to see at compile time:

  • Data-source members must be named at compile time. Use nameof, not a value resolved at runtime. Static sources are simplest; an instance source also works when TUnit can generate a factory for a constructible test or provider instance.
  • Generic test methods and classes need [GenerateGenericTest(typeof(...))], one per closed type you want emitted. Without a concrete type the generator has no runnable test to produce.
  • Do not diagnose those two cases from TUnit0058 or TUnit0059. In current TUnit, TUnit0058 reports unsupported hook parameters and TUnit0059 reports an abstract data-driven test class whose concrete subclass is missing [InheritsTests].
  • Mocking has to be generated too. Reflection-based mockers cannot run under AOT, which is why TUnit.Mocks is source-generated.

Coming from another framework

xUnit TUnit
[Fact], [Theory] [Test]
[InlineData] [Arguments]
[MemberData(nameof(X))] [MethodDataSource(nameof(X))]
[ClassData(typeof(X))] [MethodDataSource(nameof(X.Rows))]
[Trait("k","v")] [Property("k","v")]
IClassFixture<T> [ClassDataSource<T>(Shared = SharedType.PerClass)]
ICollectionFixture<T> [ClassDataSource<T>(Shared = SharedType.Keyed, Key = "name")]
IAsyncLifetime [Before(Test)] / [After(Test)]
ITestOutputHelper TestContext.Output
constructor + IDisposable [Before(Test)] / [After(Test)]

From NUnit, the trap is the opposite of xUnit's: NUnit reuses one fixture instance across a class, TUnit creates a fresh one per test.

From MSTest, the trap is ITestDataSource, which does not exist here.

04 同仓库更多 Skills

Blind-Striker
Blind-Striker/agent-skills-and-plugins

writing-tunit-tests

Write tests in TUnit — the attributes, the async assertion model, data-driven cases, lifecycle hooks, and the parallelism rules. USE FOR writing or fixing a test in a TUnit project, translating a test idea into TUnit syntax, or reviewing TUnit test code for API mistakes. DO NOT USE FOR deciding what to test, judging whether a test is any good, or running tests.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

dotnet-walls

Walls for a .NET change in a repository without its own quality gates — pinned, ephemeral analyzer, format, clone and scanner commands for the verify step, their identity ratchet, and the build traps. Use during a walls preflight, or when a worker's verify step needs .NET quality gates.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

csharp-15

Write, review and modernize C# 15 (.NET 11) code correctly. Covers every C# 15 feature - collection expression arguments (`[with(...), ...]`), union types (`union`, `[Union]`, `IUnion`, custom unions), closed class hierarchies (`closed`), extension indexers, labeled `break`/`continue`, non-virtual static interface members on runtimes without default interface methods, and the preview memory-safety model (`unsafe(expr)`, `safe`, requires-unsafe members). Use when code targets net11.0 or LangVersion 15/preview, when the user mentions any of these features, when replacing marker interfaces, OneOf-style results, `goto`/flag loop exits or capacity/comparer boilerplate, or when the build reports CS8121, CS8509, CS8655, CS8510, CS0121/CS0411 on a `with(...)` element, CS9370, CS9380 or CS9363.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

verified-waves

Run one task as verified multi-agent waves. Plans the fan-out, sends findings to fresh skeptics, keeps a ledger, and reports N of M done; small tasks stay solo.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

harness

The bundled dispatch harness, which runs a task file on worker models through OpenCode or Codex, fences their writes, escalates their asks to the operator, settles each result from git and its verify commands, and records every step in a ledger. Its commands, task file, modes and write fence, configuration, runs and their recovery, ledger and exit codes.

★ 1
Blind-Striker
Blind-Striker/agent-skills-and-plugins

delegating-to-worker-models

Use when you hand off implementation, a plan, research a decision will rely on, or a review, and you brief the worker and check what comes back. A subagent that searches, reads in parallel, or keeps your context small is ordinary tool use. Covers what stays with you, the mechanism, assigning work by strength, the walls preflight, prompts without contradictions, the worker contract and model profiles, evidence from your own run, review, and the fix-up loop.

★ 1