TimeAssertions.TUnit 0.9.0

Prefix Reserved

dotnet add package TimeAssertions.TUnit --version 0.9.0

NuGet\Install-Package TimeAssertions.TUnit -Version 0.9.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.9.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="TimeAssertions.TUnit" Version="0.9.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.9.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: TimeAssertions.TUnit, 0.9.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.9.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.9.0
                    

                            Install as a Cake Addin

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

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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.53.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, HasTimerFiredCount, HasNoTimerFired, HasTimerFiredAtLeast) 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)
`HasTimerFiredCount(int)` / `HasNoTimerFired()` / `HasTimerFiredAtLeast(int)` on `ObservableTimeProvider`	Timer-fire assertions: how many times timer callbacks ran in total, cumulative and surviving disposal (added in v0.9.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

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.

net10.0
- Microsoft.Extensions.TimeProvider.Testing (>= 10.7.0)
- TimeAssertions (>= 0.9.0)
- TUnit.Assertions (>= 1.53.0)
- TUnit.Core (>= 1.53.0)

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.9.0

Minor release. Adds fire observation to `ObservableTimeProvider`: a count of how many times timer callbacks ran, next to the existing leak and pending-due assertions. Purely additive. Also corrects stale guidance in the docs.

### Added

- **`Assert.That(time).HasTimerFiredCount(int expected)`**, **`HasNoTimerFired()`**, and **`HasTimerFiredAtLeast(int count)`** assert how many times timer callbacks fired across every timer the provider created. `ObservableTimeProvider` now wraps each timer callback to count its fires. The count is cumulative and is not reset on disposal. With a `FakeTimeProvider`, a fire is counted each time test code advances fake time past a due or period boundary, which keeps the count deterministic. `ObservableTimeProvider.TimerFireCount` (cumulative) and `ActiveTimerInfo.TimesFired` (per timer) expose the same data on the framework-agnostic core.
- `ObservableTimeProvider.CreateTimer` now validates that the callback is non-null up front (`ArgumentNullException`), matching the rest of the surface, instead of deferring to the inner provider.

### Fixed

- Once a periodic timer fires, `NextTimerDueTime` (and the `HasNextTimerDueApproximately` / `HasPendingTimerDueWithin` assertions) now report the timer's period, since that is when the next callback is due. A fired one-shot timer is disabled and drops out of the pending-due calculation. Previously the due time stayed frozen at its creation value until an explicit `Change`.
- Corrected stale documentation that claimed the package "deliberately does not ship its own polling assertion": it has shipped `HasNoActiveTimersEventually` and its count-targeted siblings since `0.7.0`/`0.8.0`. The README and the `ActiveTimerAssertions` XML docs now point to those overloads for the asynchronous disposal race, reserving generic `Eventually` for arbitrary conditions.

### Changed

- Bumped `PackageValidationBaselineVersion` from `0.7.0` to `0.8.1` on both packages so ApiCompat strict-mode validates `0.9.0` against the most recently published baseline. The new members are recorded as additive differences in `CompatibilitySuppressions.xml`.