dotnet-testing-datetime-testing-timeprovider

Name: dotnet-testing-datetime-testing-timeprovider
Author: kevintsengtw

28stars4forks

How to install dotnet-testing-datetime-testing-timeprovider?

kevintsengtw/dotnet-testing-agent-skills/dotnet-testing-datetime-testing-timeprovider

$npx -y skills add kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-datetime-testing-timeprovider

Installs into the current project.

Summary

使用 TimeProvider 測試時間相依邏輯的專門技能。當需要測試 DateTime、控制時間流逝、處理時區轉換、測試過期邏輯時使用。涵蓋 TimeProvider 抽象化、FakeTimeProvider 時間控制、時間凍結與快轉等。 Make sure to use this skill whenever the user mentions DateTime testing, TimeProvider, FakeTimeProvider, time-dependent logic, cache expiration, or token expir

Files · 1

View on GitHub

SKILL.md

1	# DateTime 與時間相依性測試指南
2
3	## 核心原則
4
5	### 原則一：時間抽象化 - 以 TimeProvider 取代 DateTime
6
7	傳統問題程式碼：
8
9	```csharp
10	// ❌ 無法測試 - 直接使用靜態時間
11	public class OrderService
12	{
13	public bool CanPlaceOrder()
14	{
15	var now = DateTime.Now;
16	return now.Hour >= 9 && now.Hour < 17;
17	}
18	}
19	```
20
21	可測試的重構：
22
23	```csharp
24	// ✅ 可測試 - 透過依賴注入接收 TimeProvider
25	public class OrderService
26	{
27	private readonly TimeProvider _timeProvider;
28
29	public OrderService(TimeProvider timeProvider)
30	{
31	_timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
32	}
33
34	public bool CanPlaceOrder()
35	{
36	var now = _timeProvider.GetLocalNow();
37	return now.Hour >= 9 && now.Hour < 17;
38	}
39	}
40	```
41
42	依賴注入設定：
43
44	```csharp
45	// Program.cs - 生產環境使用系統時間
46	services.AddSingleton(TimeProvider.System);
47	services.AddScoped<OrderService>();
48	```
49
50	### 原則二：FakeTimeProvider 控制測試時間
51
52	FakeTimeProvider 提供完整的時間控制能力：
53
54	\| 方法 \| 用途 \| 使用時機 \|
55	\| -------------------------------- \| ------------- \| ------------------- \|
56	\| `SetUtcNow(DateTimeOffset)` \| 設定 UTC 時間 \| 需要精確 UTC 時間時 \|
57	\| `SetLocalTimeZone(TimeZoneInfo)` \| 設定本地時區 \| 測試時區相關邏輯 \|
58	\| `Advance(TimeSpan)` \| 時間快轉 \| 測試過期、延遲邏輯 \|
59	\| `GetUtcNow()` \| 取得 UTC 時間 \| 讀取當前模擬時間 \|
60	\| `GetLocalNow()` \| 取得本地時間 \| 讀取本地模擬時間 \|
61
62	建議擴充方法：
63
64	```csharp
65	public static class FakeTimeProviderExtensions
66	{
67	/// <summary>
68	/// 設定 FakeTimeProvider 的本地時間
69	/// </summary>
70	public static void SetLocalNow(this FakeTimeProvider fakeTimeProvider, DateTime localDateTime)
71	{
72	fakeTimeProvider.SetLocalTimeZone(TimeZoneInfo.Local);
73	var utcTime = TimeZoneInfo.ConvertTimeToUtc(localDateTime, TimeZoneInfo.Local);
74	fakeTimeProvider.SetUtcNow(utcTime);
75	}
76	}
77	```
78
79	### 原則三：每個測試使用獨立的時間環境
80
81	```csharp
82	// ✅ 正確：每個測試獨立建立 FakeTimeProvider
83	public class OrderServiceTests
84	{
85	[Fact]
86	public void CanPlaceOrder_在營業時間內_應回傳True()
87	{
88	// Arrange - 獨立實例
89	var fakeTimeProvider = new FakeTimeProvider();
90	fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, 14, 0, 0));
91	var sut = new OrderService(fakeTimeProvider);
92
93	// Act
94	var result = sut.CanPlaceOrder();
95
96	// Assert
97	result.Should().BeTrue();
98	}
99	}
100
101	// ❌ 避免：多個測試共用靜態實例
102	public class BadTestClass
103	{
104	private static readonly FakeTimeProvider SharedProvider = new(); // 會互相干擾
105	}
106	```
107
108	---
109
110	## 進階時間控制技術
111
112	### 時間凍結
113
114	當需要驗證多個操作發生在「同一時間點」：
115
116	```csharp
117	[Fact]
118	public void ProcessBatch_在固定時間點_應產生相同時間戳()
119	{
120	var fakeTimeProvider = new FakeTimeProvider();
121	var fixedTime = new DateTime(2024, 12, 25, 10, 30, 0);
122	fakeTimeProvider.SetLocalNow(fixedTime);
123
124	var processor = new BatchProcessor(fakeTimeProvider);
125
126	var result1 = processor.ProcessItem("Item1");
127	var result2 = processor.ProcessItem("Item2");
128
129	// 時間被凍結，兩次操作的時間戳相同
130	result1.Timestamp.Should().Be(result2.Timestamp);
131	}
132	```
133
134	### 時間快轉 (Advance)
135
136	測試快取過期、Token 失效等時間敏感邏輯：
137
138	```csharp
139	[Fact]
140	public void Cache_經過過期時間_應清除項目()
141	{
142	var fakeTimeProvider = new FakeTimeProvider();
143	fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, 10, 0, 0));
144
145	var cache = new TimedCache(fakeTimeProvider, TimeSpan.FromMinutes(5));
146	cache.Set("key", "value");
147
148	// 3 分鐘後 - 尚未過期
149	fakeTimeProvider.Advance(TimeSpan.FromMinutes(3));
150	cache.Get("key").Should().Be("value");
151
152	// 再 3 分鐘後（共 6 分鐘）- 已過期
153	fakeTimeProvider.Advance(TimeSpan.FromMinutes(3));
154	cache.Get("key").Should().BeNull();
155	}
156	```
157
158	> 重要：`Advance()` 是非阻塞的，瞬間完成時間跳躍，不會真正等待。
159
160	### 時間倒轉
161
162	測試歷史資料處理或重播場景：
163
164	```csharp
165	[Fact]
166	public void HistoricalDataProcessor_回到過去時間_應正確處理()
167	{
168	var fakeTimeProvider = new FakeTimeProvider();
169	var historicalTime = new DateTime(2020, 1, 15, 9, 0, 0);
170	fakeTimeProvider.SetLocalNow(historicalTime);
171
172	var processor = new HistoricalDataProcessor(fakeTimeProvider);
173	var result = processor.ProcessDataForDate(historicalTime.Date);
174
175	result.ProcessedAt.Should().Be(historicalTime);
176	}
177	```
178
179	---
180
181	## 實戰測試模式
182
183	### 模式一：參數化邊界測試
184
185	```csharp
186	[Theory]
187	[InlineData(8, false)] // 上午 8 點 - 營業時間前
188	[InlineData(9, true)] // 上午 9 點 - 剛開始營業
189	[InlineData(12, true)] // 中午 12 點 - 營業時間內
190	[InlineData(16, true)] // 下午 4 點 - 營業時間內
191	[InlineData(17, false)] // 下午 5 點 - 剛結束營業
192	[Inline

People who liked this also viewed

6 picks

Type

dotnet-testing-datetime-testing-timeprovider

28stars4forks

View on GitHub

How to install dotnet-testing-datetime-testing-timeprovider?

kevintsengtw/dotnet-testing-agent-skills/dotnet-testing-datetime-testing-timeprovider

$npx -y skills add kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-datetime-testing-timeprovider

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# DateTime 與時間相依性測試指南
2
3	## 核心原則
4
5	### 原則一：時間抽象化 - 以 TimeProvider 取代 DateTime
6
7	傳統問題程式碼：
8
9	```csharp
10	// ❌ 無法測試 - 直接使用靜態時間
11	public class OrderService
12	{
13	public bool CanPlaceOrder()
14	{
15	var now = DateTime.Now;
16	return now.Hour >= 9 && now.Hour < 17;
17	}
18	}
19	```
20
21	可測試的重構：
22
23	```csharp
24	// ✅ 可測試 - 透過依賴注入接收 TimeProvider
25	public class OrderService
26	{
27	private readonly TimeProvider _timeProvider;
28
29	public OrderService(TimeProvider timeProvider)
30	{
31	_timeProvider = timeProvider ?? throw new ArgumentNullException(nameof(timeProvider));
32	}
33
34	public bool CanPlaceOrder()
35	{
36	var now = _timeProvider.GetLocalNow();
37	return now.Hour >= 9 && now.Hour < 17;
38	}
39	}
40	```
41
42	依賴注入設定：
43
44	```csharp
45	// Program.cs - 生產環境使用系統時間
46	services.AddSingleton(TimeProvider.System);
47	services.AddScoped<OrderService>();
48	```
49
50	### 原則二：FakeTimeProvider 控制測試時間
51
52	FakeTimeProvider 提供完整的時間控制能力：
53
54	\| 方法 \| 用途 \| 使用時機 \|
55	\| -------------------------------- \| ------------- \| ------------------- \|
56	\| `SetUtcNow(DateTimeOffset)` \| 設定 UTC 時間 \| 需要精確 UTC 時間時 \|
57	\| `SetLocalTimeZone(TimeZoneInfo)` \| 設定本地時區 \| 測試時區相關邏輯 \|
58	\| `Advance(TimeSpan)` \| 時間快轉 \| 測試過期、延遲邏輯 \|
59	\| `GetUtcNow()` \| 取得 UTC 時間 \| 讀取當前模擬時間 \|
60	\| `GetLocalNow()` \| 取得本地時間 \| 讀取本地模擬時間 \|
61
62	建議擴充方法：
63
64	```csharp
65	public static class FakeTimeProviderExtensions
66	{
67	/// <summary>
68	/// 設定 FakeTimeProvider 的本地時間
69	/// </summary>
70	public static void SetLocalNow(this FakeTimeProvider fakeTimeProvider, DateTime localDateTime)
71	{
72	fakeTimeProvider.SetLocalTimeZone(TimeZoneInfo.Local);
73	var utcTime = TimeZoneInfo.ConvertTimeToUtc(localDateTime, TimeZoneInfo.Local);
74	fakeTimeProvider.SetUtcNow(utcTime);
75	}
76	}
77	```
78
79	### 原則三：每個測試使用獨立的時間環境
80
81	```csharp
82	// ✅ 正確：每個測試獨立建立 FakeTimeProvider
83	public class OrderServiceTests
84	{
85	[Fact]
86	public void CanPlaceOrder_在營業時間內_應回傳True()
87	{
88	// Arrange - 獨立實例
89	var fakeTimeProvider = new FakeTimeProvider();
90	fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, 14, 0, 0));
91	var sut = new OrderService(fakeTimeProvider);
92
93	// Act
94	var result = sut.CanPlaceOrder();
95
96	// Assert
97	result.Should().BeTrue();
98	}
99	}
100
101	// ❌ 避免：多個測試共用靜態實例
102	public class BadTestClass
103	{
104	private static readonly FakeTimeProvider SharedProvider = new(); // 會互相干擾
105	}
106	```
107
108	---
109
110	## 進階時間控制技術
111
112	### 時間凍結
113
114	當需要驗證多個操作發生在「同一時間點」：
115
116	```csharp
117	[Fact]
118	public void ProcessBatch_在固定時間點_應產生相同時間戳()
119	{
120	var fakeTimeProvider = new FakeTimeProvider();
121	var fixedTime = new DateTime(2024, 12, 25, 10, 30, 0);
122	fakeTimeProvider.SetLocalNow(fixedTime);
123
124	var processor = new BatchProcessor(fakeTimeProvider);
125
126	var result1 = processor.ProcessItem("Item1");
127	var result2 = processor.ProcessItem("Item2");
128
129	// 時間被凍結，兩次操作的時間戳相同
130	result1.Timestamp.Should().Be(result2.Timestamp);
131	}
132	```
133
134	### 時間快轉 (Advance)
135
136	測試快取過期、Token 失效等時間敏感邏輯：
137
138	```csharp
139	[Fact]
140	public void Cache_經過過期時間_應清除項目()
141	{
142	var fakeTimeProvider = new FakeTimeProvider();
143	fakeTimeProvider.SetLocalNow(new DateTime(2024, 3, 15, 10, 0, 0));
144
145	var cache = new TimedCache(fakeTimeProvider, TimeSpan.FromMinutes(5));
146	cache.Set("key", "value");
147
148	// 3 分鐘後 - 尚未過期
149	fakeTimeProvider.Advance(TimeSpan.FromMinutes(3));
150	cache.Get("key").Should().Be("value");
151
152	// 再 3 分鐘後（共 6 分鐘）- 已過期
153	fakeTimeProvider.Advance(TimeSpan.FromMinutes(3));
154	cache.Get("key").Should().BeNull();
155	}
156	```
157
158	> 重要：`Advance()` 是非阻塞的，瞬間完成時間跳躍，不會真正等待。
159
160	### 時間倒轉
161
162	測試歷史資料處理或重播場景：
163
164	```csharp
165	[Fact]
166	public void HistoricalDataProcessor_回到過去時間_應正確處理()
167	{
168	var fakeTimeProvider = new FakeTimeProvider();
169	var historicalTime = new DateTime(2020, 1, 15, 9, 0, 0);
170	fakeTimeProvider.SetLocalNow(historicalTime);
171
172	var processor = new HistoricalDataProcessor(fakeTimeProvider);
173	var result = processor.ProcessDataForDate(historicalTime.Date);
174
175	result.ProcessedAt.Should().Be(historicalTime);
176	}
177	```
178
179	---
180
181	## 實戰測試模式
182
183	### 模式一：參數化邊界測試
184
185	```csharp
186	[Theory]
187	[InlineData(8, false)] // 上午 8 點 - 營業時間前
188	[InlineData(9, true)] // 上午 9 點 - 剛開始營業
189	[InlineData(12, true)] // 中午 12 點 - 營業時間內
190	[InlineData(16, true)] // 下午 4 點 - 營業時間內
191	[InlineData(17, false)] // 下午 5 點 - 剛結束營業
192	[Inline

People who liked this also viewed

6 picks

Type