dotnet-testing-datetime-testing-timeprovider_skill

Overview

This skill teaches how to test time-dependent .NET code using TimeProvider and FakeTimeProvider. It focuses on replacing DateTime static calls with injectable TimeProvider, freezing or advancing simulated time, and handling time zone scenarios. The guidance helps make time-sensitive logic deterministic and easy to test.

How this skill works

The approach injects TimeProvider into services so tests can supply FakeTimeProvider instances. FakeTimeProvider lets tests SetUtcNow, SetLocalTimeZone, Advance, and retrieve GetUtcNow/GetLocalNow to simulate any temporal scenario. Tests create isolated FakeTimeProvider instances per test, freeze time for consistent timestamps, or advance time instantly to validate expiration and scheduling logic.

When to use it

• When code reads DateTime.Now or DateTime.UtcNow and needs deterministic tests
• Testing cache expiration, token expiry, or retry/backoff windows
• Validating business rules tied to business hours or promotional periods
• Testing scheduled jobs, triggers, and time-window logic
• Verifying behavior across time zones and daylight saving transitions

Best practices

• Inject TimeProvider via constructors and register TimeProvider.System in production
• Use FakeTimeProvider per test to avoid cross-test interference
• Prefer _timeProvider.GetLocalNow() or _timeProvider.GetUtcNow() over DateTime.Now/UtcNow
• Use SetLocalNow or SetUtcNow to establish a fixed baseline, then Advance() to simulate passage of time
• Freeze time for tests that assert identical timestamps; Advance for expiry/timeout scenarios
• When using AutoFixture, register FakeTimeProvider and freeze it as the direct base type so dependencies receive the fake

Example use cases

• Unit-test business hours with FakeTimeProvider.SetLocalNow to assert open/closed behavior
• Freeze time to ensure multiple operations produce the same timestamp in batch processing
• Advance FakeTimeProvider to simulate cache item expiration or token invalidation
• SetLocalTimeZone and SetUtcNow to validate timezone-aware conversions and DST edge cases
• Use per-test FakeTimeProvider instances in parameterized boundary tests (start/end of window)