Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions .claude/docs/workflows.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,3 +128,34 @@ dotnet test --treenode-filter "/*/*/ClassB/*"
- [ ] If performance-critical: profiled before/after
- [ ] If using reflection: tested AOT, added annotations
- [ ] No `.received.txt` files staged

---

## Documentation Snippets

CI compiles C# fences in `README.md` and `docs/docs` against packages produced by the pipeline. Fences nested in Markdown lists are supported.

Use a directive immediately before a fence when its context needs to be explicit:

```markdown
<!-- doc-test-declaration -->
<!-- doc-test-member -->
<!-- doc-test-statements -->
<!-- doc-test-contextual -->
<!-- doc-test-ignore: Reason this fence cannot compile independently. -->
```

Use `<!-- doc-test-contextual -->` on each fence that depends on surrounding prose. Its page must declare `<!-- doc-test-contextual-file: Reason. -->`, so unmarked fences still compile and cannot be silently excluded by page-level configuration. Use `<!-- doc-test-ignore-file: Reason. -->` when no snippets on a page can compile independently. File directives require a reason.

For a fence that mixes declarations or members with usage, split it explicitly at an exact marker:

```markdown
<!-- doc-test-declaration: split-before=// Usage -->
<!-- doc-test-member: split-before=// Usage -->
```

Run the check against local packages with:

```powershell
./scripts/Verify-DocSnippets.ps1 -PackagesPath <package-directory> -Version <semver>
```
5 changes: 5 additions & 0 deletions .github/workflows/dotnet.yml
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,11 @@ jobs:
nuget-apikey: ${{ steps.login.outputs.NUGET_API_KEY }}
publish-packages: ${{ (github.event.inputs.publish-packages || false) && matrix.os == 'ubuntu-latest' }}

- name: Compile documentation snippets
if: matrix.os == 'ubuntu-latest'
shell: pwsh
run: ./scripts/Verify-DocSnippets.ps1 -PackagesPath . -Version $env:PackageVersion

Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
- name: Upload Diagnostic Logs
uses: actions/upload-artifact@v7.0.1
if: always()
Expand Down
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
![TUnit](assets/banner.png)

<!-- doc-test-contextual-file: Examples include fragments whose variables and helpers are defined by surrounding prose. -->

# TUnit

A modern .NET testing framework. Tests are discovered at compile time via source generators, run in parallel by default, and work under Native AOT — all built on [Microsoft.Testing.Platform](https://learn.microsoft.com/en-us/dotnet/core/testing/microsoft-testing-platform-intro).
Expand All @@ -15,6 +17,7 @@ A modern .NET testing framework. Tests are discovered at compile time via source

## What it looks like

<!-- doc-test-contextual -->
```csharp
[Test]
[Arguments("GOLD", 100.00, 80.00)]
Expand Down Expand Up @@ -94,6 +97,7 @@ dotnet add package TUnit

### Data-driven tests

<!-- doc-test-contextual -->
```csharp
[Test]
[Arguments("user1@test.com", "ValidPassword123")]
Expand All @@ -114,6 +118,7 @@ Need more? `[MethodDataSource]` pulls rows from a method, and custom `DataSource

Assertions are async, chainable, and produce the focused failure messages shown above:

<!-- doc-test-contextual -->
```csharp
await Assert.That(response.StatusCode).IsEqualTo(HttpStatusCode.OK)
.Because("the health endpoint should always be up");
Expand All @@ -125,11 +130,13 @@ await Assert.That(order.Items)

Defining your own assertion is one attribute on a plain method — TUnit generates the fluent extension for you:

<!-- doc-test-member: split-before=// Now available -->
```csharp
[GenerateAssertion]
public static bool IsPositive(this int value) => value > 0;

// Now available on Assert.That:
var account = new { Balance = 1 };
await Assert.That(account.Balance).IsPositive();
```

Expand All @@ -140,8 +147,8 @@ Inject anything into your test classes with `[ClassDataSource<T>]`. Implement `I
```csharp
public class PostgresContainer : IAsyncInitializer, IAsyncDisposable
{
public Task InitializeAsync() { /* start container */ }
public ValueTask DisposeAsync() { /* stop container */ }
public Task InitializeAsync() => Task.CompletedTask; // start container
public ValueTask DisposeAsync() => ValueTask.CompletedTask; // stop container
}

public class OrderRepositoryTests
Expand All @@ -160,6 +167,7 @@ Property injection keeps base test classes clean — subclasses inherit the fixt

Everything runs in parallel by default. Opt out or sequence tests where it matters:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Register_User() { ... }
Expand All @@ -176,6 +184,7 @@ public async Task Migrates_Schema() { ... }

### Lifecycle hooks at every scope

<!-- doc-test-contextual -->
```csharp
[Before(Test)] // also: Class, Assembly, TestSession
public async Task SetUp() { ... }
Expand All @@ -188,6 +197,7 @@ public static async Task TearDownDatabase(ClassHookContext context) { ... }

`TUnit.Mocks` is a source-generated, Native AOT-compatible mocking library — no runtime proxies, no `Castle.Core`. It works with any test framework:

<!-- doc-test-contextual -->
```csharp
var gateway = IPaymentGateway.Mock(); // or Mock.Of<IPaymentGateway>()

Expand All @@ -201,6 +211,7 @@ gateway.ChargeAsync(99.99m).WasCalled(Times.Once);

Companion packages mock the annoying stuff for you:

<!-- doc-test-contextual -->
```csharp
// TUnit.Mocks.Http — a real HttpClient backed by a scriptable handler
using var client = Mock.HttpClient("https://api.example.com");
Expand All @@ -215,12 +226,13 @@ logger.VerifyLog().AtLevel(LogLevel.Warning).ContainingMessage("retrying").WasCa

Extend built-in base classes to create your own skip conditions, retry logic, and more:

<!-- doc-test-contextual -->
```csharp
public class WindowsOnlyAttribute : SkipAttribute
{
public WindowsOnlyAttribute() : base("Windows only") { }

public override Task<bool> ShouldSkip(TestContext testContext)
public override Task<bool> ShouldSkip(TestRegisteredContext testContext)
=> Task.FromResult(!OperatingSystem.IsWindows());
}

Expand Down Expand Up @@ -253,6 +265,7 @@ public class HealthCheckTests(ApiFactory factory)

Spin up your whole distributed app once per test session, with resource log forwarding and OpenTelemetry capture built in:

<!-- doc-test-ignore: Aspire sample depends on the generated Projects.MyApp_AppHost type. -->
```csharp
public class AppFixture : AspireFixture<Projects.MyApp_AppHost>;

Expand Down Expand Up @@ -289,6 +302,7 @@ public class HomePageTests : PageTest

### Property-based testing (FsCheck)

<!-- doc-test-contextual -->
```csharp
[Test, FsCheckProperty]
public bool Reversing_Twice_Returns_Original(int[] array) =>
Expand Down
11 changes: 11 additions & 0 deletions docs/docs/assertions/awaiting.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
sidebar_position: 1
---

<!-- doc-test-contextual-file: Examples include fragments whose variables and helpers are defined by surrounding prose. -->

# Awaiting

In TUnit you `await` your assertions, and this serves two purposes:
Expand All @@ -15,6 +17,7 @@ If you forget to `await`, your assertion will not actually be executed, and your

This will error:

<!-- doc-test-contextual -->
```csharp
[Test]
public void MyTest()
Expand All @@ -27,6 +30,7 @@ This will error:

This won't:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task MyTest()
Expand All @@ -46,6 +50,7 @@ When you `await` an assertion in TUnit, it returns a reference to the subject th

### Type Casting with Confidence

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task CastAndUseSpecificType()
Expand All @@ -69,6 +74,7 @@ public async Task CastAndUseSpecificType()

You can chain multiple assertions together for more complex validations:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task ComplexObjectValidation()
Expand All @@ -86,6 +92,7 @@ public async Task ComplexObjectValidation()

### Collection Assertions with Complex Conditions

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task ComplexCollectionAssertions()
Expand All @@ -109,6 +116,7 @@ public async Task ComplexCollectionAssertions()

### Async Operation Assertions

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task AsyncOperationAssertions()
Expand All @@ -130,6 +138,7 @@ public async Task AsyncOperationAssertions()

### Exception Assertions with Details

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task DetailedExceptionAssertions()
Expand Down Expand Up @@ -157,6 +166,7 @@ public async Task DetailedExceptionAssertions()

### Custom Assertion Conditions

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task CustomAssertionConditions()
Expand All @@ -181,6 +191,7 @@ public async Task CustomAssertionConditions()

### Combining Or and And Conditions

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task ComplexLogicalConditions()
Expand Down
13 changes: 13 additions & 0 deletions docs/docs/assertions/boolean.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@
sidebar_position: 3.5
---

<!-- doc-test-contextual-file: Examples include fragments whose variables and helpers are defined by surrounding prose. -->

# Boolean Assertions

TUnit provides simple, expressive assertions for testing boolean values. These assertions work with both `bool` and `bool?` (nullable boolean) types.
Expand All @@ -12,6 +14,7 @@ TUnit provides simple, expressive assertions for testing boolean values. These a

Tests that a boolean value is `true`:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Value_Is_True()
Expand All @@ -28,6 +31,7 @@ public async Task Value_Is_True()

Tests that a boolean value is `false`:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Value_Is_False()
Expand All @@ -44,6 +48,7 @@ public async Task Value_Is_False()

You can also use `IsEqualTo()` for boolean comparisons:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Using_IsEqualTo()
Expand All @@ -64,6 +69,7 @@ However, `IsTrue()` and `IsFalse()` are more expressive and recommended for bool

Both assertions work with nullable booleans (`bool?`):

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Nullable_Boolean_True()
Expand Down Expand Up @@ -92,6 +98,7 @@ public async Task Nullable_Boolean_False()

If a nullable boolean is `null`, both `IsTrue()` and `IsFalse()` will fail:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Nullable_Boolean_Null()
Expand All @@ -111,6 +118,7 @@ public async Task Nullable_Boolean_Null()

Boolean assertions can be chained with other assertions:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Chained_With_Other_Assertions()
Expand All @@ -127,6 +135,7 @@ public async Task Chained_With_Other_Assertions()

### Validation Results

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Email_Validation()
Expand All @@ -141,6 +150,7 @@ public async Task Email_Validation()

### Permission Checks

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task User_Permissions()
Expand All @@ -155,6 +165,7 @@ public async Task User_Permissions()

### State Flags

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Service_State()
Expand All @@ -171,6 +182,7 @@ public async Task Service_State()

### Feature Flags

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Feature_Toggles()
Expand All @@ -186,6 +198,7 @@ public async Task Feature_Toggles()

When testing the boolean result of a comparison, use the specific assertion instead for clearer failure messages:

<!-- doc-test-contextual -->
```csharp
[Test]
public async Task Prefer_Specific_Assertions()
Expand Down
Loading
Loading