Some bugs you can only find by waiting a year. A license that expires at the end of its term, a key that is NotBefore until a future activation date, a grace window that lapses after seventy-two offline hours — all of this is time-dependent logic, and the obvious way to test it is to change the system clock and see what happens. That does not scale to a CI run, and it does not survive two tests executing in parallel.
The good news is that none of that is necessary. If your licensing code never reads the ambient clock directly, you can advance time by exact amounts inside a unit test and assert every boundary deterministically, in milliseconds.
Key takeaway: Stop calling DateTimeOffset.UtcNow inside license logic. Read time through .NET's TimeProvider, inject it into the Keyright SDK, and in tests pass a FakeTimeProvider whose clock you move with Advance(...). Now "the day before expiry", "the exact expiry instant", and "one tick past grace" are three ordinary, fast, parallel-safe assertions.
The real question: where does the time come from?
A license check is a comparison against now. Validate() asks whether the cached lease is still inside its validity window, whether its NotBefore has arrived, and whether the offline grace window has lapsed. Every one of those is something <= now or now < something. The whole testability problem is the single word now.
If now is DateTimeOffset.UtcNow, there is no seam. UtcNow is a static property that reads the OS clock; you cannot override it per test without an ambient global shim, and an ambient global is exactly the shared mutable state that makes a test suite flaky under parallelism.
TimeProvider, built into .NET 8 and up, is the seam. It is a small abstract class with the methods that matter here:
public abstract class TimeProvider { public static TimeProvider System { get; } // reads the real OS clock public abstract DateTimeOffset GetUtcNow(); // calendar time public abstract long GetTimestamp(); // monotonic ticks public TimeSpan GetElapsedTime(long startingTimestamp); // ... CreateTimer, GetLocalNow, etc. } The Keyright SDK reads time exclusively through a TimeProvider. You supply it once, on KeyrightOptions; if you leave it unset it defaults to TimeProvider.System, so production code reads the real clock and you never think about it.
static readonly KeyrightClient License = KeyrightClient.Initialize(new KeyrightOptions { Product = "acme-suite", PublicKeyBase64 = "MIIBIjANBgkq...", // ships in your binary; not a secret ServiceUrl = "https://keyright.example.com", // your self-hosted instance TimeProvider = TimeProvider.System, // the default; override it in tests }); Driving the clock with FakeTimeProvider
The test double is FakeTimeProvider, from the Microsoft.Extensions.TimeProvider.Testing package. You construct it at a fixed instant and move it forward by hand. Nothing advances on its own, so a test is perfectly reproducible.
using Microsoft.Extensions.Time.Testing; var clock = new FakeTimeProvider(new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero)); var license = KeyrightClient.Initialize(new KeyrightOptions { Product = "acme-suite", PublicKeyBase64 = TestKeys.PublicKey, TimeProvider = clock, // the SDK now reads *this* clock Offline = true, // unit test: validate the embedded lease, no network }); license.ImportLicense(TestKeys.SignForTest(expiresAtUtc: new DateTimeOffset(2026, 4, 1, 0, 0, 0, TimeSpan.Zero))); Assert.Equal(LicenseStatus.Valid, license.Validate().Status); // 2026-01-01: well inside the term clock.Advance(TimeSpan.FromDays(89)); // -> 2026-03-31 Assert.Equal(LicenseStatus.Valid, license.Validate().Status); clock.Advance(TimeSpan.FromDays(1)); // -> 2026-04-01, the expiry instant Assert.Equal(LicenseStatus.Expired, license.Validate().Status); Assert.Equal(LicenseEdition.Community, license.Validate().Edition); // fell back cleanly The figure below is the mental model: a single fake clock you slide along the term, reading the license state at each stop.
Asserting the boundaries, not just the middle
Deterministic time lets you test the parts that matter — the edges — instead of a comfortable point in the middle. Three cases are worth a test apiece.
NotBefore has not arrived. A key activated for a future date must read as not-yet-valid, then flip the instant the clock reaches it.
var clock = new FakeTimeProvider(new DateTimeOffset(2026, 1, 1, 0, 0, 0, TimeSpan.Zero)); var license = NewClient(clock); license.ImportLicense(TestKeys.SignForTest( notBeforeUtc: new DateTimeOffset(2026, 2, 1, 0, 0, 0, TimeSpan.Zero), expiresAtUtc: new DateTimeOffset(2027, 2, 1, 0, 0, 0, TimeSpan.Zero))); Assert.Equal(LicenseStatus.NotYetValid, license.Validate().Status); clock.Advance(TimeSpan.FromDays(31)); // -> 2026-02-01 exactly Assert.Equal(LicenseStatus.Valid, license.Validate().Status); The clock-skew leeway at the edge. If you allow a small NotBeforeLeeway for client clock drift, the fake clock proves it is exactly that wide — valid one tick inside the leeway, invalid one tick outside — without you ever touching the real clock.
// Lease NotBefore = 2026-02-01, configured leeway = 5 minutes. clock.SetUtcNow(new DateTimeOffset(2026, 1, 31, 23, 56, 0, TimeSpan.Zero)); // 4 min early Assert.Equal(LicenseStatus.Valid, license.Validate().Status); // inside leeway clock.SetUtcNow(new DateTimeOffset(2026, 1, 31, 23, 54, 0, TimeSpan.Zero)); // 6 min early Assert.Equal(LicenseStatus.NotYetValid, license.Validate().Status); // outside leeway Grace lapsing after the last confirmation. For the online path, set the last confirmed instant on the lease, then advance past GracePeriod and assert the fallback to Community Edition. Because the countdown is anchored to a confirmation timestamp, a FakeTimeProvider reproduces the whole window exactly.
var clock = new FakeTimeProvider(new DateTimeOffset(2026, 6, 1, 12, 0, 0, TimeSpan.Zero)); var license = NewClient(clock, grace: TimeSpan.FromHours(72)); license.ImportLeaseForTest(confirmedAtUtc: clock.GetUtcNow()); // "service last answered now" clock.Advance(TimeSpan.FromHours(71)); Assert.Equal(LicenseEdition.Pro, license.Validate().Edition); // still inside grace clock.Advance(TimeSpan.FromHours(2)); // 73h since confirmation Assert.Equal(LicenseEdition.Community, license.Validate().Edition); // grace exhausted, failed closed How it fits a real test project
A small helper keeps each test to its three lines of intent. Build the client from a clock, hand out signed test leases, and let xUnit run the class in parallel — there is no shared static clock to collide over.
static KeyrightClient NewClient(TimeProvider clock, TimeSpan? grace = null) => KeyrightClient.Initialize(new KeyrightOptions { Product = "acme-suite", PublicKeyBase64 = TestKeys.PublicKey, // a throwaway keypair generated for the test run TimeProvider = clock, Offline = true, GracePeriod = grace ?? TimeSpan.FromHours(72), }); Generate a dedicated test keypair in a fixture so you can sign leases with arbitrary NotBefore/ExpiresAt values and verify them with the matching public key. You are testing your integration against the SDK's clock-reading behaviour, not re-testing the signature scheme, so the keys can be ephemeral. Keep the real production public key out of the test project entirely.
Caveats: what the fake clock does and does not prove
A FakeTimeProvider is a unit-test seam, and it is honest about its limits.
It controls only where the SDK reads the local wall clock. It does not move a server-signed ConfirmedAtUtc inside a lease, and it does not defeat the SDK's tamper checks — in production, winding the real clock backward is detected against a monotonic high-water mark and fails closed. So a test can simulate time passing forward cleanly, but to test rollback-tamper behaviour you drive the fake clock backward and assert the SDK reports ClockStatus.WentBackwards, which is itself a valuable deterministic test.
It is a unit-level tool. It proves your gating logic responds correctly to time; it does not exercise the real network path to your self-hosted issuing service. Keep a thin layer of integration tests that run the actual RefreshAsync against a test instance, and let the fast FakeTimeProvider suite cover the dozens of boundary cases.
Finally, be deliberate about GetUtcNow versus GetTimestamp. Calendar decisions — expiry, NotBefore, a signed timestamp — use GetUtcNow. Short in-process durations — a cache TTL, a refresh interval — use the monotonic GetTimestamp/GetElapsedTime pair so an operator nudging the wall clock cannot distort them. FakeTimeProvider.Advance moves both together, so one clock still drives the whole test.
Takeaway
Time-dependent license logic is only hard to test when it reads the clock it cannot see. Route every "what time is it" through TimeProvider, leave it as TimeProvider.System in production, and hand the SDK a FakeTimeProvider in tests. Expiry, not-before, clock-skew leeway and grace all collapse into fast, parallel-safe assertions where you advance the clock by the exact amount that matters and read the result. The year you would have waited becomes a call to Advance.
