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(); // 會互相干擾
}

---

進階時間控制技術

時間凍結

當需要驗證多個操作發生在「同一時間點」：

[Fact]
public void ProcessBatch_在固定時間點_應產生相同時間戳()
{
    var fakeTimeProvider = new FakeTimeProvider();
    var fixedTime = new DateTime(2024, 12, 25, 10, 30, 0);
    fakeTimeProvider.SetLocalNow(fixedTime);
    
    var processor = new BatchProcessor(fakeTimeProvider);
    
    var result1 = processor.ProcessItem("Item1");
    var result2 = processor.ProcessItem("Item2");
    
    // 時間被凍結，兩次操作的時間戳相同
    result1.Timestamp.Should().Be(result2.Timestamp);
}

時間快轉 (Advance)

測試快取過期、Token 失效等時間敏感邏輯：

[Fact]
public void Cache_經過過期時間_應清除項目()
{
    var fakeTimeProvider = new FakeTimeProvider();
    fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, 10, 0, 0));
    
    var cache = new TimedCache(fakeTimeProvider, TimeSpan.FromMinutes(5));
    cache.Set("key", "value");
    
    // 3 分鐘後 - 尚未過期
    fakeTimeProvider.Advance(TimeSpan.FromMinutes(3));
    cache.Get("key").Should().Be("value");
    
    // 再 3 分鐘後（共 6 分鐘）- 已過期
    fakeTimeProvider.Advance(TimeSpan.FromMinutes(3));
    cache.Get("key").Should().BeNull();
}

重要：Advance() 是非阻塞的，瞬間完成時間跳躍，不會真正等待。

以歷史時間起始

測試歷史資料處理或重播場景時，在新建立的實例上設定起始時間：

[Fact]
public void HistoricalDataProcessor_回到過去時間_應正確處理()
{
    var fakeTimeProvider = new FakeTimeProvider();
    var historicalTime = new DateTime(2020, 1, 15, 9, 0, 0);
    fakeTimeProvider.SetLocalNow(historicalTime);
    
    var processor = new HistoricalDataProcessor(fakeTimeProvider);
    var result = processor.ProcessDataForDate(historicalTime.Date);
    
    result.ProcessedAt.Should().Be(historicalTime);
}

⚠️ SetUtcNow 是單向的：同一個 FakeTimeProvider 實例只能把時間往前設， 回設較早的時間會拋 ArgumentOutOfRangeException: Cannot go back in time. （8.0.0／9.0.0／10.9.0 實測一致）。上面能設定 2020 年，是因為那是一個剛建立、 尚未推進的實例，不是「可以倒轉」。

因此，若測試類別把 FakeTimeProvider 提為共用欄位（在 constructor 建立、 多個測試方法共用同一實例），初始時間必須取所有測試會用到的最早時間， 其後各測試以 SetUtcNow() 或 Advance() 往前推進。 不想受此限制時，回到〈原則三〉：每個測試各自 new FakeTimeProvider()。

---

實戰測試模式

模式一：參數化邊界測試

[Theory]
[InlineData(8, false)]   // 上午 8 點 - 營業時間前
[InlineData(9, true)]    // 上午 9 點 - 剛開始營業
[InlineData(12, true)]   // 中午 12 點 - 營業時間內
[InlineData(16, true)]   // 下午 4 點 - 營業時間內
[InlineData(17, false)]  // 下午 5 點 - 剛結束營業
[InlineData(18, false)]  // 下午 6 點 - 營業時間後
public void CanPlaceOrder_不同時間點_應回傳正確結果(int hour, bool expected)
{
    var fakeTimeProvider = new FakeTimeProvider();
    fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, hour, 0, 0));
    
    var sut = new OrderService(fakeTimeProvider);
    
    sut.CanPlaceOrder().Should().Be(expected);
}

模式二：交易時間窗口測試

[Theory]
[InlineData("09:30:00", true)]   // 上午交易時間
[InlineData("12:00:00", false)]  // 中午休息
[InlineData("14:30:00", true)]   // 下午交易時間
[InlineData("15:30:00", false)]  // 交易結束後
public void IsInTradingHours_不同時間_應回傳正確結果(string timeStr, bool expected)
{
    var fakeTimeProvider = new FakeTimeProvider();
    var testTime = DateTime.Today.Add(TimeSpan.Parse(timeStr));
    fakeTimeProvider.SetLocalNow(testTime);
    
    var sut = new TradingService(fakeTimeProvider);
    
    sut.IsInTradingHours().Should().Be(expected);
}

模式三：排程觸發邏輯測試

[Theory]
[InlineData("2024-03-15 14:30:00", "2024-03-15 14:00:00", true)]   // 已到執行時間
[InlineData("2024-03-15 13:30:00", "2024-03-15 14:00:00", false)]  // 尚未到時間
public void ShouldExecuteJob_根據時間判斷_應回傳正確結果(
    string currentTimeStr, string scheduledTimeStr, bool expected)
{
    var fakeTimeProvider = new FakeTimeProvider();
    fakeTimeProvider.SetLocalNow(DateTime.Parse(currentTimeStr));
    
    var schedule = new JobSchedule { NextExecutionTime = DateTime.Parse(scheduledTimeStr) };
    var sut = new ScheduleService(fakeTimeProvider);
    
    sut.ShouldExecuteJob(schedule).Should().Be(expected);
}

---

AutoFixture 整合

FakeTimeProviderCustomization

public class FakeTimeProviderCustomization : ICustomization
{
    public void Customize(IFixture fixture)
    {
        fixture.Register(() => new FakeTimeProvider());
    }
}

AutoDataWithCustomization 屬性

public class AutoDataWithCustomizationAttribute : AutoDataAttribute
{
    public AutoDataWithCustomizationAttribute() : base(CreateFixture)
    {
    }
    
    private static IFixture CreateFixture()
    {
        return new Fixture()
            .Customize(new AutoNSubstituteCustomization())
            .Customize(new FakeTimeProviderCustomization());
    }
}

使用 Matching.DirectBaseType

[Theory]
[AutoDataWithCustomization]
public void GetTimeBasedDiscount_週五_應回傳九折優惠(
    [Frozen(Matching.DirectBaseType)] FakeTimeProvider fakeTimeProvider,
    OrderService sut)
{
    // Matching.DirectBaseType 讓 AutoFixture 知道：
    // 當需要 TimeProvider（基底類型）時，使用 FakeTimeProvider（衍生類型）
    
    var fridayTime = new DateTime(2024, 3, 15, 14, 0, 0); // 週五
    fakeTimeProvider.SetLocalNow(fridayTime);
    
    sut.GetTimeBasedDiscount().Should().Be("週五快樂：九折優惠");
}

關鍵：必須使用 [Frozen(Matching.DirectBaseType)]，否則 AutoFixture 無法正確將 FakeTimeProvider 注入到需要 TimeProvider 的建構式中。

---

最佳實踐檢查清單

程式碼設計

• [ ] 所有時間相依類別透過建構式接收 TimeProvider
• [ ] 使用 _timeProvider.GetLocalNow() 取代 DateTime.Now
• [ ] 使用 _timeProvider.GetUtcNow() 取代 DateTime.UtcNow
• [ ] DI 容器註冊 TimeProvider.System 作為生產環境實作

測試設計

• [ ] 每個測試方法使用獨立的 FakeTimeProvider 實例
• [ ] 若改用共用實例，初始時間取所有測試會用到的最早時間（SetUtcNow 不可回設）
• [ ] 整合測試中由 DI 註冊的 FakeTimeProvider 同屬共用實例：不要在每個測試開始時設回固定起點，時間以 GetUtcNow() 為基準推算
• [ ] 使用 SetLocalNow() 擴充方法簡化時間設定
• [ ] 使用 Advance() 測試時間敏感邏輯（快取、過期、延遲）
• [ ] 測試涵蓋邊界條件（開始時間、結束時間、臨界點）

進階考量

• [ ] FakeTimeProvider 是執行緒安全的，可用於並行測試
• [ ] 使用 IDisposable 模式正確釋放 FakeTimeProvider
• [ ] 時區測試使用 SetLocalTimeZone() 明確設定時區

---

輸出格式

• 產生使用 TimeProvider 抽象的服務類別
• 產生使用 FakeTimeProvider 的測試類別
• 包含時間凍結、快轉、時區轉換測試範例
• 提供 .csproj 套件參考（Microsoft.Bcl.TimeProvider）

參考資源

範例檔案

• templates/timeprovider-basics.cs - 把時間相依的程式碼重構為可測試設計，含 LegacyOrderService 與 OrderService 的前後對照、TimeProvider API 對照表與 DI 註冊
• templates/faketimeprovider-examples.cs - 以 FakeTimeProvider 控制時間，涵蓋邊界條件、時間凍結與批次處理情境
• templates/autofixture-integration.cs - 與 AutoFixture 整合，含 FakeTimeProviderCustomization 與自訂的 AutoData 屬性

原始文章

本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：

• Day 16 - 測試日期與時間：Microsoft.Bcl.TimeProvider 取代 DateTime
  • 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10375821
  • 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day16

官方文件

• TimeProvider API
• Microsoft.Bcl.TimeProvider NuGet
• Microsoft.Extensions.TimeProvider.Testing NuGet

相關技能

• autofixture-basics - AutoFixture 自動測試資料生成
• nsubstitute-mocking - 測試替身與模擬
• autodata-xunit-integration - xUnit 與 AutoFixture 的 AutoData 整合