EonaCat.DeterministicTime 1.0.0

EonaCat.DeterministicTime

EonaCat.DeterministicTime is a .NET library for deterministic, testable, and replayable time.

It replaces DateTime.UtcNow, Stopwatch, Timer, and Task.Delay with deterministic equivalents and supports advanced features like:

scheduling, time scaling, replay, NTP offsets, ASP.NET Framework integration. ASP.NET Core integration.

Installation

dotnet add package EonaCat.DeterministicTime

ASP.NET Core integration (optional)

dotnet add package DeterministicTime.AspNetCore

ASP.NET Framework integration (optional)

dotnet add package DeterministicTime.AspNetFramework

ASP.NET 4.8 → add DeterministicTime.AspNetFramework and register HttpModule in web.config:

<system.web>
  <httpModules>
    <add name="DeterministicTime" type="DeterministicTimeHttpModule"/>
  </httpModules>
</system.web>

Basic Usage

using DeterministicTime;

DateTime now = DeterministicTime.UtcNow;
DateTime localNow = DeterministicTime.Now;

Freeze Time

using (TimeScope.Frozen(DateTime.Parse("2025-01-01T00:00:00Z")))
{
    Console.WriteLine(DeterministicTime.UtcNow); // frozen
}

Scale Time

using (TimeScope.Scaled(10)) // 10x faster
{
// all timers and delays scale 10x
}

Advance Time Manually

DeterministicTime.Advance(TimeSpan.FromHours(2));

Offset Time

using (TimeScope.Offset(TimeSpan.FromMinutes(5)))
{
   // all UtcNow calls are offset by 5 minutes
}

Deterministic Stopwatch

var sw = DeterministicStopwatch.StartNew();
// do work
sw.Stop();
Console.WriteLine(sw.Elapsed);

Deterministic Timer

int fired = 0;
DeterministicTimer.Start(TimeSpan.FromSeconds(10), () => fired++);
DeterministicTime.Advance(TimeSpan.FromSeconds(10));
Console.WriteLine(fired); // 1

Deterministic Delay

bool completed = false;
await DeterministicDelay.For(TimeSpan.FromSeconds(5)).ContinueWith(_ => completed = true);
DeterministicTime.Advance(TimeSpan.FromSeconds(5));
Console.WriteLine(completed); // true

Deterministic Scheduler

var scheduler = DeterministicScheduler.Global;
scheduler.Every(TimeSpan.FromMinutes(1), () => Console.WriteLine("Tick"));
DeterministicTime.Advance(TimeSpan.FromMinutes(5)); // fires 5 times

Time Recording & Replay

Record

using var recording = TimeRecording.Start();
// run code
recording.Save("run.json");

Replay

using (TimeReplay.Load("run.json"))
{
    // deterministic replay of UtcNow calls
}

NTP Synchronization

using (NtpSynchronization.Sync(myNtpProvider))
{
  // deterministic time aligned with NTP
}

Distributed Time Source

IDistributedTimeCoordinator coordinator = ...;
DeterministicTime.Push(new DistributedTimeSource(coordinator));
Console.WriteLine(DeterministicTime.UtcNow);

ASP.NET Core Middleware

app.UseDeterministicTime();

• Each request runs in its own deterministic scope

• Works with frozen/scaled time and timers

Advanced Features Summary

• Deterministic UtcNow & Now

• Stopwatch replacement

• One-shot and repeated timers

• Task.Delay replacement

• Time scaling, freezing, offset

• Scheduler for background jobs

• Recording & replay for testing

• NTP synchronization & distributed clocks

• ASP.NET Core integration