TimeAssertions.TUnit
0.8.1
Prefix Reserved
See the version list below for details.
dotnet add package TimeAssertions.TUnit --version 0.8.1
NuGet\Install-Package TimeAssertions.TUnit -Version 0.8.1
<PackageReference Include="TimeAssertions.TUnit" Version="0.8.1" />
<PackageVersion Include="TimeAssertions.TUnit" Version="0.8.1" />
<PackageReference Include="TimeAssertions.TUnit" />
paket add TimeAssertions.TUnit --version 0.8.1
#r "nuget: TimeAssertions.TUnit, 0.8.1"
#:package TimeAssertions.TUnit@0.8.1
#addin nuget:?package=TimeAssertions.TUnit&version=0.8.1
#tool nuget:?package=TimeAssertions.TUnit&version=0.8.1
TimeAssertions.TUnit
Scope: Test projects only. Not intended for production code.
TUnit-native fluent time-assertion DSL on top of Microsoft.Extensions.Time.Testing.FakeTimeProvider. Adds FakeTimeProvider state assertions, TimeProvider-aware DateTimeOffset recency / past / future checks, plus the cross-cutting .WithinTimeBudget(TimeSpan) chain extension. AOT-compatible, trimmable, no reflection.
Full documentation, "Why TimeProvider in tests", cookbook, design notes, and roadmap: github.com/JohnVerheij/TimeAssertions.TUnit
Install
dotnet add package TimeAssertions.TUnit
TimeAssertions (the framework-agnostic core) and Microsoft.Extensions.TimeProvider.Testing come transitively. Requirements: TUnit 1.50.0 or later, .NET 10.
The source-generated entry points (HasAdvancedExactly, HasAdvancedApproximately, HasUtcNow, HasUtcNowApproximately, IsRecent, IsBeforeNow, IsAfterNow, WithinTimeBudget, WithinTimeBudgetCapturing, WasInvokedAtMostOncePer, HasNoActiveTimers, HasActiveTimerCount, HasActiveTimers, HasAtLeastActiveTimerCount, HasNoActiveTimersEventually, HasActiveTimerCountEventually, HasAtLeastActiveTimerCountEventually, HasAtMostActiveTimerCountEventually, HasActiveTimersEventually, HasNextTimerDueApproximately, HasPendingTimerDueWithin) auto-import via TUnit.Assertions.Extensions. Add the following to a GlobalUsings.cs in your test project for the call-site and FakeTimeProvider namespaces:
global using Microsoft.Extensions.Time.Testing;
global using TimeAssertions;
global using TimeAssertions.TUnit;
Quick start
[Test]
public async Task PreReleaseExpiration_advances_state_after_clock_moves_forward()
{
var fakeTime = new FakeTimeProvider();
var service = new ExpirationService(fakeTime);
fakeTime.Advance(TimeSpan.FromMinutes(31));
await Assert.That(fakeTime).HasAdvancedExactly(TimeSpan.FromMinutes(31));
await Assert.That(service.LastRefresh).IsRecent(TimeSpan.FromSeconds(1), fakeTime);
// Cross-cutting timing budget on any behavioral assertion chain
await Assert.That(service.IsExpiredAsync())
.IsTrue()
.And.WithinTimeBudget(TimeSpan.FromMilliseconds(500));
}
Entry points
| Method | Purpose |
|---|---|
HasAdvancedExactly(TimeSpan) / HasAdvancedApproximately(total, tolerance) |
FakeTimeProvider advanced by exact / approximate amount (renamed from HasAdvanced / HasAdvancedBy in v0.2.0; old names [Obsolete] until v0.4.0) |
HasUtcNow(DateTimeOffset) / HasUtcNowApproximately(expected, tolerance) |
FakeTimeProvider is at exact / approximate moment |
IsRecent(TimeSpan, TimeProvider?) |
DateTimeOffset is within window before "now" of supplied (or system) clock |
IsBeforeNow(TimeProvider) / IsAfterNow(TimeProvider) |
DateTimeOffset ordering relative to supplied clock |
WithinTimeBudget(TimeSpan) |
Cross-cutting timing budget; chains via .And after any behavioral assertion |
WithinTimeBudgetCapturing(TimeSpan, Action<TimeSpan>) |
Same as WithinTimeBudget plus a callback that receives the measured elapsed on every evaluation path except external cancellation (added in v0.2.0; cancellation-skip behavior added in v0.5.0) |
WasInvokedAtMostOncePer(this IReadOnlyList<DateTimeOffset>, TimeSpan interval) |
Rate-limit assertion on a recorded invocation log: every consecutive gap is at least interval (added in v0.5.0) |
HasNoActiveTimers() / HasActiveTimerCount(int) on ObservableTimeProvider |
Timer-leak assertions: no undisposed timers / exact active-timer count, naming each survivor by its schedule on failure (added in v0.6.0) |
HasActiveTimers() / HasAtLeastActiveTimerCount(int) on ObservableTimeProvider |
Positive-count assertions: at least one / at least count active timers, for a lower bound rather than an exact count (added in v0.7.0) |
HasNoActiveTimersEventually(TimeSpan, ...) / HasActiveTimerCountEventually(int, TimeSpan, ...) on ObservableTimeProvider |
Real-time poll until the active count reaches zero / a target count, for the asynchronous disposal race a synchronous check cannot see (added in v0.7.0) |
HasNextTimerDueApproximately(TimeSpan, TimeSpan) / HasPendingTimerDueWithin(TimeSpan, TimeSpan) on ObservableTimeProvider |
Pending-timer due-time assertions: inspect the next scheduled timer's due time without advancing the clock, within a tolerance or an inclusive range (added in v0.6.0) |
Failure diagnostics
On a failed assertion, the exception message includes the elapsed / expected duration, the absolute drift, and (for budget overruns) the overshoot plus a grep-friendly (elapsed=Xms, budget=Yms, overrun=Zms) suffix for log scrapers. No Console.WriteLine debugging needed: every dimension you can assert on is also rendered in the failure message.
Full failure-diagnostics example, design notes, stability intent, and roadmap on GitHub.
Family
Part of an assertion family for TUnit:
- LogAssertions.TUnit
- SnapshotAssertions.TUnit
- MathAssertions.TUnit
- JsonAssertions.TUnit
- SseAssertions.TUnit
- GrpcAssertions.TUnit
License
MIT. Copyright (c) 2026 John Verheij.
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
-
net10.0
- Microsoft.Extensions.TimeProvider.Testing (>= 10.6.0)
- TimeAssertions (>= 0.8.1)
- TUnit.Assertions (>= 1.48.6)
- TUnit.Core (>= 1.48.6)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
View the rendered release notes: https://github.com/JohnVerheij/TimeAssertions.TUnit/releases/tag/v0.8.1
Tooling release. No library API or behavior change. The release workflow now publishes the matching `CHANGELOG.md` section as the GitHub release body, so release notes carry the full Added / Changed / Breaking detail instead of GitHub's auto-generated commit summary.
### Changed
- The release workflow extracts the `## [version]` section from `CHANGELOG.md` and passes it as the GitHub release body (`body_path`), so the notes carry the full hand-written detail instead of an auto-generated commit summary. Earlier releases published only the auto-generated notes, which omitted the hand-written breaking-change and feature detail.
### Note for anyone upgrading across 0.8.0
`0.8.0` contained **source-breaking** changes that its published release notes did not surface (this release fixes the notes mechanism, not the changes themselves):
- The `CancellationToken` parameter on `HasNoActiveTimersEventually` and `HasActiveTimerCountEventually` was renamed from `ct` to `cancellationToken`. A call that passed the token by name (`ct: token`) must become `cancellationToken: token`; positional calls are unaffected.
- `EventuallyTimerAssertionExtensions` moved from the `TimeAssertions.TUnit` namespace to `TUnit.Assertions.Extensions`. Code referencing the type by its full name must update the namespace; use through `Assert.That(...)` is unaffected.
See the 0.8.0 Breaking section below for the full detail.