TimeAssertions.TUnit 0.8.0

Prefix Reserved
.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package TimeAssertions.TUnit --version 0.8.0
                    


                    

                
NuGet\Install-Package TimeAssertions.TUnit -Version 0.8.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="TimeAssertions.TUnit" Version="0.8.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="TimeAssertions.TUnit" Version="0.8.0" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="TimeAssertions.TUnit" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add TimeAssertions.TUnit --version 0.8.0
                    


                    

                
#r "nuget: TimeAssertions.TUnit, 0.8.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package TimeAssertions.TUnit@0.8.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=TimeAssertions.TUnit&version=0.8.0
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=TimeAssertions.TUnit&version=0.8.0
                    


                            Install as a Cake Tool

TimeAssertions.TUnit

NuGet Downloads License: MIT .NET

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.49.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 behavioural 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 behavioural 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 behaviour 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:

License

MIT. Copyright (c) 2026 John Verheij.

Product 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. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.9.0 735 6/12/2026
0.8.1 1,600 6/6/2026
0.8.0 148 6/5/2026
0.7.0 235 6/4/2026
0.6.0 147 6/3/2026
0.5.0 222 5/19/2026
0.4.0 344 5/13/2026
0.3.0 164 5/12/2026
0.2.0 180 5/7/2026
0.1.0 158 5/6/2026

View the rendered release notes: https://github.com/JohnVerheij/TimeAssertions.TUnit/releases/tag/v0.8.0

Minor release. Adds asynchronous lower-bound, upper-bound, and at-least-one active-timer assertions, completing the bounded-count set begun in `0.7.0`. Aligns the active-timer "eventually" assertions with the BCL `CancellationToken` naming and discoverability convention. Contains breaking changes (parameter rename and a namespace move); see Breaking below.

### Added

- **`Assert.That(time).HasAtLeastActiveTimerCountEventually(count, timeout, ...)`** polls the live active-timer count until it is at least `count`. The asynchronous lower-bound sibling of the synchronous `HasAtLeastActiveTimerCount(count)` and the exact-count `HasActiveTimerCountEventually`: the right shape for an asynchronous registration wait where more than one timer may register, where the exact-count form would flake once an additional timer registers and the synchronous form would race a not-yet-registered timer.
- **`Assert.That(time).HasAtMostActiveTimerCountEventually(count, timeout, ...)`** polls until the active-timer count is at most `count`. The upper-bound sibling for "the active set settles to no more than N" without pinning the exact survivor count. `HasAtMostActiveTimerCountEventually(0, ...)` is equivalent to `HasNoActiveTimersEventually`.
- **`Assert.That(time).HasActiveTimersEventually(timeout, ...)`** polls until at least one timer is active. The asynchronous counterpart of `HasActiveTimers()` and a named shorthand for `HasAtLeastActiveTimerCountEventually(1, ...)`.
- Positional-`CancellationToken` sugar overloads for all three new assertions, matching the existing `(timeout, token)` and `(count, timeout, token)` shapes.

### Changed

- The positional-`CancellationToken` sugar (`EventuallyTimerAssertionExtensions`) now lives in the globally imported `TUnit.Assertions.Extensions` namespace, the same namespace the source generator emits the canonical extensions into, so the `(timeout, token)` / `(count, timeout, token)` forms are discoverable wherever the generated extensions are, without an extra `using TimeAssertions.TUnit;`.
- Bumped `PackageValidationBaselineVersion` from `0.6.0` to `0.7.0` on both packages and regenerated `CompatibilitySuppressions.xml` for the new public types, the namespace move, and the parameter rename.

### Breaking

- The `CancellationToken` parameter on `HasNoActiveTimersEventually` and `HasActiveTimerCountEventually` is renamed from `ct` to `cancellationToken`, matching the BCL convention and the new bounded-count assertions. A call that passed the token by name (`ct: token`) must use `cancellationToken: token`; positional calls are unaffected.
- `EventuallyTimerAssertionExtensions` moved from the `TimeAssertions.TUnit` namespace to `TUnit.Assertions.Extensions`. Code that referenced the type by its full name must update the namespace; code that used the extension methods through `Assert.That(...)` is unaffected (and no longer needs `using TimeAssertions.TUnit;` for them).