dotnet-testing-datetime-testing-timeprovider

DateTime 與時間相依性測試指南

核心原則

原則一：時間抽象化 - 以 TimeProvider 取代 DateTime

傳統問題程式碼：

// ❌ 無法測試 - 直接使用靜態時間
public class OrderService
{
    public bool CanPlaceOrder()
    {
        var now = DateTime.Now;
        return now.Hour >= 9 && now.Hour < 17;
    }
}

可測試的重構：

// ✅ 可測試 - 透過依賴注入接收 TimeProvider
public class OrderService
{
    private readonly TimeProvider _timeProvider;
    
    public OrderService(TimeProvider timeProvider)
    {
        _timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
    }
    
    public bool CanPlaceOrder()
    {
        var now = _timeProvider.GetLocalNow();
        return now.Hour >= 9 && now.Hour < 17;
    }
}

依賴注入設定：

// Program.cs - 生產環境使用系統時間
services.AddSingleton(TimeProvider.System);
services.AddScoped<OrderService>();

原則二：FakeTimeProvider 控制測試時間

套件名與命名空間不同：安裝 Microsoft.Extensions.TimeProvider.Testing，程式碼中寫 using Microsoft.Extensions.Time.Testing;。

FakeTimeProvider 提供完整的時間控制能力：

方法	用途	使用時機
SetUtcNow(DateTimeOffset)	設定 UTC 時間（只能往前，不能回設更早的時間）	需要精確 UTC 時間時
SetLocalTimeZone(TimeZoneInfo)	設定本地時區	測試時區相關邏輯
Advance(TimeSpan)	時間快轉	測試過期、延遲邏輯
GetUtcNow()	取得 UTC 時間	讀取當前模擬時間
GetLocalNow()	取得本地時間	讀取本地模擬時間

建議擴充方法：

public static class FakeTimeProviderExtensions
{
    /// <summary>
    /// 設定 FakeTimeProvider 的本地時間
    /// </summary>
    public static void SetLocalNow(this FakeTimeProvider fakeTimeProvider, DateTime localDateTime)
    {
        fakeTimeProvider.SetLocalTimeZone(TimeZoneInfo.Local);
        var utcTime = TimeZoneInfo.ConvertTimeToUtc(localDateTime, TimeZoneInfo.Local);
        fakeTimeProvider.SetUtcNow(utcTime);
    }
}

原則三：每個測試使用獨立的時間環境

// ✅ 正確：每個測試獨立建立 FakeTimeProvider
public class OrderServiceTests
{
    [Fact]
    public void CanPlaceOrder_在營業時間內_應回傳True()
    {
        // Arrange - 獨立實例
        var fakeTimeProvider = new FakeTimeProvider();
        fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, 14, 0, 0));
        var sut = new OrderService(fakeTimeProvider);
        
        // Act
        var result = sut.CanPlaceOrder();
        
        // Assert
        result.Should().BeTrue();
    }
}

// ❌ 避免：多個測試共用靜態實例
public class BadTestClass
{
    private static readonly FakeTimeProvider SharedProvider = new(); // 會互相干擾
}