git.stella-ops.org/src/__Libraries/StellaOps.TestKit/Time/DeterministicClock.cs

namespace StellaOps.TestKit.Time;

/// <summary>
/// Deterministic clock for testing that returns a fixed time.
/// </summary>
public sealed class DeterministicClock
{
    private DateTimeOffset _currentTime;

    /// <summary>
    /// Creates a new deterministic clock with the specified initial time.
    /// </summary>
    /// <param name="initialTime">The initial time. If null, uses 2025-01-01T00:00:00Z.</param>
    public DeterministicClock(DateTimeOffset? initialTime = null)
    {
        _currentTime = initialTime ?? new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero);
    }

    /// <summary>
    /// Gets the current time.
    /// </summary>
    public DateTimeOffset UtcNow => _currentTime;

    /// <summary>
    /// Advances the clock by the specified duration.
    /// </summary>
    /// <param name="duration">The duration to advance.</param>
    public void Advance(TimeSpan duration)
    {
        _currentTime = _currentTime.Add(duration);
    }

    /// <summary>
    /// Sets the clock to a specific time.
    /// </summary>
    /// <param name="time">The time to set.</param>
    public void SetTime(DateTimeOffset time)
    {
        _currentTime = time;
    }

    /// <summary>
    /// Resets the clock to the initial time.
    /// </summary>
    public void Reset()
    {
        _currentTime = new DateTimeOffset(2025, 1, 1, 0, 0, 0, TimeSpan.Zero);
    }
}

/// <summary>
/// Extensions for working with deterministic clocks in tests.
/// </summary>
public static class DeterministicClockExtensions
{
    /// <summary>
    /// Standard test epoch: 2025-01-01T00:00:00Z
    /// </summary>
    public static readonly DateTimeOffset TestEpoch = new(2025, 1, 1, 0, 0, 0, TimeSpan.Zero);

    /// <summary>
    /// Creates a clock at the standard test epoch.
    /// </summary>
    public static DeterministicClock AtTestEpoch() => new(TestEpoch);

    /// <summary>
    /// Creates a clock at a specific ISO 8601 timestamp.
    /// </summary>
    public static DeterministicClock At(string iso8601) => new(DateTimeOffset.Parse(iso8601));
}