feat(assertions): add CancellationToken overload to WaitsFor and Eventually

[JohnVerheij]

Description

Adds a CancellationToken parameter to WaitsFor and Eventually. The token is honoured between iterations of the polling loop, and the internal Task.Delay is wired through a linked cancellation source so both external cancellation and the internal timeout break the sleep. External cancellation propagates as OperationCanceledException; the internal timeout still produces the standard AssertionException.

The parameter is defaulted (CancellationToken cancellationToken = default), so callers using named arguments compile and behave unchanged.

Implements the locked defaults proposed in #5932:

• Parameter name: cancellationToken
• Signature shape: single overload with defaulted CT (not two non-defaulting overloads)
• Pre-cancelled-token shortcut: yes (ThrowIfCancellationRequested at the top of each iteration)
• Exception type for external cancellation: plain OperationCanceledException (no TUnit wrapper)
• Scope: WaitsFor and Eventually only (no change to other timeout-bearing assertions)

Any of these defaults can be reversed in review.

Breaking changes

The new cancellationToken parameter is positioned between pollingInterval and the [CallerArgumentExpression] parameters of WaitsFor / Eventually, matching the convention used elsewhere in AssertionExtensions.cs (real parameters first, compiler-fill diagnostic parameters last).

Impact on callers:

• Named-argument call sites (the form used in every existing test in WaitsForAssertionTests.cs): unaffected.
• Positional call sites up to and including pollingInterval: unaffected.
• Positional call sites that pass timeoutExpression or pollingIntervalExpression directly (overriding the compiler's auto-fill; non-standard but legal): CS0029 type mismatch at the 5th positional argument. Resolution is a one-line shift to named arguments.
• Binary callers: any DLL compiled against the prior TUnit needs recompilation; the method signatures changed.

The functional contract for existing callers is preserved: when cancellationToken is not passed, the linked CTS short-circuits to a plain timeout-only source and behaviour matches the prior release.

Related Issue

Fixes #5932

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update
• Performance improvement
• Refactoring (no functional changes)

Checklist

Required

• I have read the Contributing Guidelines
• If this is a new feature, I started a discussion first and received agreement
• My code follows the project's code style (modern C# syntax, proper naming conventions)
• I have written tests that prove my fix is effective or my feature works

TUnit-Specific Requirements

• Dual-Mode Implementation: If this change affects test discovery/execution, I have implemented it in BOTH:
  • Source Generator path (TUnit.Core.SourceGenerator)
  • Reflection path (TUnit.Engine)
• Snapshot Tests: If I changed source generator output or public APIs:
  • I ran TUnit.Core.SourceGenerator.Tests and/or TUnit.PublicAPI tests
  • I reviewed the .received.txt files and accepted them as .verified.txt
  • I committed the updated .verified.txt files
• Performance: If this change affects hot paths (test discovery, execution, assertions):
  • I minimized allocations and avoided LINQ in hot paths
  • I cached reflection results where appropriate
• AOT Compatibility: If this change uses reflection:
  • I added appropriate [DynamicallyAccessedMembers] annotations
  • I verified the change works with dotnet publish -p:PublishAot=true

Testing

• All existing tests pass (dotnet test)
• I have added tests that cover my changes
• I have tested both source-generated and reflection modes (if applicable)

Additional Notes

Regression tests added

Five new tests in WaitsForAssertionTests.cs:

1. WaitsFor_PropagatesExternalCancellation_Before_Internal_Timeout: external CT cancels after 100ms, predicate returns false continuously, internal timeout 30s. Asserts OperationCanceledException and elapsed time under 1 second.
2. WaitsFor_Throws_AssertionException_On_Internal_Timeout_When_Token_Not_Cancelled: CT created but never cancelled, internal timeout 200ms. Asserts AssertionException (the existing contract is preserved when CT is unused).
3. WaitsFor_Honours_PreCancelled_Token_Before_First_Poll: pre-cancelled CT, would-pass predicate, internal timeout 5s. Asserts OperationCanceledException and elapsed under 500ms (proves the loop exits on the first iteration).
4. Eventually_PropagatesExternalCancellation_Before_Internal_Timeout: alias-symmetry test confirming the same cancellation contract holds for Eventually (which forwards to WaitsFor).
5. WaitsFor_Propagates_OCE_When_Predicate_Observes_Supplied_Token: predicate calls cts.Token.ThrowIfCancellationRequested() after the token is cancelled mid-poll; verifies cancellation propagates within roughly the cancel delay plus one poll interval.

Implementation

• WaitsForAssertion<TValue> constructor takes the token and stores it as a field.
• CheckAsync builds a linked CTS when the supplied token is cancellable, otherwise a plain timeout-only CTS. This avoids the linked-registration overhead when no external token is provided.
• Between iterations: cancellationToken.ThrowIfCancellationRequested() honours external cancel before each predicate invocation.
• During the poll sleep: Task.Delay(_pollingInterval, linkedCts.Token) is wrapped in two catch (OperationCanceledException) clauses, the first using a when (cancellationToken.IsCancellationRequested) filter to rethrow on external cancel and the second falling through to the existing AssertionResult.Failed path on internal timeout.

Public API snapshot updates

The TUnit.PublicAPI test project's Tests.Assertions_Library_Has_No_API_Changes snapshots have been regenerated for the four supported TFMs (net472 / net8.0 / net9.0 / net10.0). Each delta is exactly three lines: the WaitsForAssertion constructor, the WaitsFor extension, and the Eventually extension all gain the new defaulted CancellationToken parameter.

Local verification

• Full TUnit.Assertions.Tests suite: 2111/2111 pass (existing 2106 + 5 new).
• This change is in TUnit.Assertions only; no source-generator emit is affected.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 4 complexity

Metric	Results
Complexity	4

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.}

[claude]

Code Review — feat(assertions): add CancellationToken to WaitsFor and Eventually

Overall this is a well-designed, thoughtful addition. The edge cases are properly considered, the tests are comprehensive, and the public API snapshots are correctly updated for all four TFMs. A few items worth discussing:

---

1. Conditional linked-CTS construction — correct and good

using var linkedCts = _cancellationToken.CanBeCanceled
    ? CancellationTokenSource.CreateLinkedTokenSource(_cancellationToken)
    : new CancellationTokenSource();
linkedCts.CancelAfter(_timeout);

Checking CanBeCanceled before linking is the right call — it avoids a heap-allocated CancellationTokenRegistration for every assertion invocation when no external token is supplied. Good optimisation that matches TUnit's performance-first principle.

---

2. Exception-filter ordering in Task.Delay catch — correct

catch (OperationCanceledException) when (_cancellationToken.IsCancellationRequested)
{
    throw;   // external
}
catch (OperationCanceledException)
{
    break;   // internal timeout
}

The when filter correctly distinguishes external from internal cancellation. The one inherent race is if both fire at exactly the same instant: IsCancellationRequested will be true and we throw OCE rather than producing AssertionResult.Failed. This is arguably the right semantics (external cancellation takes priority), so the implementation is sound.

---

3. CancelAsync() in tests — verify .NET Framework build

WaitsFor_Honours_PreCancelled_Token_Before_First_Poll calls await cts.CancelAsync(), which was added in .NET 8. The public-API snapshots include Net4_7.verified.txt, which implies TUnit targets net472 somewhere. If TUnit.Assertions.Tests also compiles against net472, this test will fail to compile.

Suggestion: Either add #if NET8_0_OR_GREATER guards or replace with the synchronous cts.Cancel() (which is equivalent for a pre-cancel scenario and works on all TFMs).

---

4. Comment density exceeds project style guide

CLAUDE.md states "Default to writing no comments. Only add one when the WHY is non-obvious." Several comments in WaitsForAssertion.cs describe WHAT the code does rather than WHY it exists:

// Honour external cancellation between iterations: a pre-cancelled token, or a token
// cancelled during the previous Task.Delay, exits the loop without invoking the
// predicate. Internal-timeout cancellation falls through to AssertionResult.Failed.
_cancellationToken.ThrowIfCancellationRequested();

The code is self-explanatory here. The one comment worth keeping is the CanBeCanceled block — the WHY (avoiding registration overhead) is genuinely non-obvious. The others could be removed.

---

5. Timing-sensitive test margins — probably fine, but note the risk

Tests like:

await Assert.That(stopwatch.Elapsed).IsLessThan(TimeSpan.FromSeconds(1));

...with a 100ms cancel delay and a 30s internal timeout leave a comfortable 10× margin. In practice this should be robust, but under heavy CI load even 100ms operations can stretch. If these become flaky, widening the margin (e.g. < TimeSpan.FromSeconds(5)) would be the fix without changing the semantics.

---

6. Breaking change documentation is thorough

The PR description clearly enumerates affected call sites and the resolution path (shift to named arguments). Well-handled.

---

Summary

This is a solid, mergeable implementation. The two actionable items before merging are:

• Verify CancelAsync() compiles on net472 (or switch to cts.Cancel()).
• Trim the explanatory comments to align with the project's comment policy.

The design choices — parameter position, single defaulted overload, plain OperationCanceledException for external cancellation — are all well-reasoned and match the locked defaults from #5932.