dotnet-testing-advanced-testcontainers-database

Name: dotnet-testing-advanced-testcontainers-database
Author: kevintsengtw

28stars4forks

How to install dotnet-testing-advanced-testcontainers-database?

kevintsengtw/dotnet-testing-agent-skills/dotnet-testing-advanced-testcontainers-database

$npx -y skills add kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-advanced-testcontainers-database

Installs into the current project.

Summary

使用 Testcontainers 進行容器化資料庫測試的專門技能。當需要測試真實資料庫行為、使用 SQL Server/PostgreSQL/MySQL 容器、測試 EF Core/Dapper 時使用。涵蓋容器啟動、資料庫遷移、測試隔離、容器共享等。 Make sure to use this skill whenever the user mentions Testcontainers database, SQL Server container, PostgreSQL container, EF Core integration test, Da

Files · 1

View on GitHub

SKILL.md

1	# Testcontainers 資料庫整合測試指南
2
3	## EF Core InMemory 的限制
4
5	在選擇測試策略前，必須了解 EF Core InMemory 資料庫的重大限制：
6
7	### 1. 交易行為與資料庫鎖定
8
9	- 不支援資料庫交易 (Transactions)：`SaveChanges()` 後資料立即儲存，無法進行 Rollback
10	- 無資料庫鎖定機制：無法模擬並發 (Concurrency) 情境下的行為
11
12	### 2. LINQ 查詢差異
13
14	- 查詢翻譯差異：某些 LINQ 查詢（複雜 GroupBy、JOIN、自訂函數）在 InMemory 中可執行，但轉換成 SQL 時可能失敗
15	- Case Sensitivity：InMemory 預設不區分大小寫，但真實資料庫依賴校對規則 (Collation)
16	- 效能模擬不足：無法模擬真實資料庫的效能瓶頸或索引問題
17
18	### 3. 資料庫特定功能
19
20	InMemory 模式無法測試：預存程序、Triggers、Views、外鍵約束、檢查約束、資料類型精確度、Concurrency Tokens 等。
21
22	結論：當需要驗證複雜交易邏輯、並發處理、資料庫特定行為時，應使用 Testcontainers 進行整合測試。
23
24	## Testcontainers 核心概念
25
26	Testcontainers 是一個測試函式庫，提供輕量好用的 API 來啟動 Docker 容器，專門用於整合測試。
27
28	### 核心優勢
29
30	1. 真實環境測試：使用真實資料庫，測試實際 SQL 語法與資料庫限制
31	2. 環境一致性：確保測試環境與正式環境使用相同服務版本
32	3. 清潔測試環境：每個測試有獨立乾淨的環境，容器自動清理
33	4. 簡化開發環境：開發者只需 Docker，不需安裝各種服務
34
35	## 必要套件
36
37	```xml
38	<ItemGroup>
39	<!-- 測試框架 -->
40	<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
41	<PackageReference Include="xunit" Version="2.9.3" />
42	<PackageReference Include="xunit.runner.visualstudio" Version="3.1.5" />
43	<PackageReference Include="AwesomeAssertions" Version="9.4.0" />
44
45	<!-- Testcontainers 核心套件 -->
46	<PackageReference Include="Testcontainers" Version="4.11.0" />
47
48	<!-- 資料庫容器 -->
49	<PackageReference Include="Testcontainers.PostgreSql" Version="4.11.0" />
50	<PackageReference Include="Testcontainers.MsSql" Version="4.11.0" />
51
52	<!-- Entity Framework Core -->
53	<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
54	<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
55	<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.0" />
56
57	<!-- Dapper (可選) -->
58	<PackageReference Include="Dapper" Version="2.1.72" />
59	<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
60	</ItemGroup>
61	```
62
63	> 重要：使用 `Microsoft.Data.SqlClient` 而非舊版 `System.Data.SqlClient`，提供更好的效能與安全性。
64
65	## 環境需求
66
67	- Windows 10 版本 2004+，啟用 WSL 2，8GB RAM（建議 16GB+），64GB 磁碟空間
68	- Docker Desktop 建議設定：Memory 6GB、CPUs 4 cores、Swap 2GB、Disk 64GB
69
70	## 基本容器操作模式
71
72	使用 `IAsyncLifetime` 管理容器生命週期，在 `InitializeAsync` 中啟動容器並建立 DbContext，在 `DisposeAsync` 中釋放資源。支援 PostgreSQL（`PostgreSqlBuilder`）和 SQL Server（`MsSqlBuilder`）。
73
74	> 完整程式碼範例請參考 [references/container-basics.md](references/container-basics.md)
75
76	## Collection Fixture 模式：容器共享
77
78	在大型專案中，每個測試類別都建立新容器會遇到嚴重的效能瓶頸。Collection Fixture 讓所有測試類別共享同一個容器，測試執行時間可減少約 67%。
79
80	包含 SQL 腳本外部化策略（將 SQL 檔案從 C# 程式碼分離）與 Wait Strategy 最佳實務。
81
82	> 完整 Collection Fixture 實作、SQL 腳本外部化與 Wait Strategy 範例請參考 [references/collection-fixture-and-scripts.md](references/collection-fixture-and-scripts.md)
83
84	## EF Core 進階功能測試
85
86	涵蓋 Include/ThenInclude 多層關聯查詢、AsSplitQuery 避免笛卡兒積、N+1 查詢問題驗證、AsNoTracking 唯讀查詢最佳化等完整測試範例。
87
88	> 完整程式碼範例請參考 [references/orm-advanced-testing.md](references/orm-advanced-testing.md#ef-core-進階功能測試)
89
90	## Dapper 進階功能測試
91
92	涵蓋基本 CRUD 測試類別設置、QueryMultiple 一對多關聯處理、DynamicParameters 動態查詢建構等完整測試範例。
93
94	> 完整程式碼範例請參考 [references/orm-advanced-testing.md](references/orm-advanced-testing.md#dapper-進階功能測試)
95
96	## Repository Pattern 設計原則
97
98	### 介面分離原則 (ISP) 的應用
99
100	- `IProductRepository`：基礎 CRUD 操作介面（GetAll、GetById、Add、Update、Delete）
101	- `IProductByEFCoreRepository`：EF Core 特有進階功能（SplitQuery、BatchUpdate、NoTracking）
102	- `IProductByDapperRepository`：Dapper 特有進階功能（多表查詢、動態參數、預存程序）
103
104	### 設計優勢
105
106	1. 單一職責原則 (SRP)：每個介面專注於特定職責
107	2. 介面隔離原則 (ISP)：使用者只需依賴所需的介面
108	3. 依賴反轉原則 (DIP)：高層模組依賴抽象而非具體實作
109	4. 測試隔離性：可針對特定功能進行精準測試
110
111	## 常見問題處理
112
113	### Docker 容器啟動失敗
114
115	```bash
116	# 檢查連接埠是否被佔用
117	netstat -an \| findstr :5432
118
119	# 清理未使用的映像檔
120	docker system prune -a
121	```
122
123	### ContainerNotRunningException（4.8.0+ 新增）
124
125	Testcontainers 4.8.0 起，預設等待策略改為等待容器進入 Running 狀態。若容器未能正常啟動，會拋出此例外。常見原因：映像檔名稱錯誤、Docker 資源不足、連接埠衝突。
126
127	### 記憶體不足問題
128
129	- 調整 Docker Desktop 記憶體配置
130	- 限制同時執行的容器數量
131	- 使用 Collection Fixture 共享容器
132
133	### 測試資料隔離
134
135	在 `Dispose` 中按照外鍵約束順序清理資料（OrderItems → Orders → Products → Categories）。
136
137	## 輸出格式
138
139	- 產生使用 Testcontainers 的 xUnit 整合測試類別（.cs 檔案）
140	- 包含 IAsyncLifetime 容器生命週期管理程式碼
141	- 包含 Collection Fixture 共享容器設定
142	- 產生外部化 SQL 腳本檔案（.sql）與對應的 .csproj 設定
143	- 包含 Repository Pattern 介面與實作範例
144
145	## 參考資源
146
147	### 原始文章
148
149	本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
150
151	- Day 20 - Testcontainers 初探：使用 Docker 架設測試環境
152	- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10376401
153	- 範例程式碼：https://github.com

People who liked this also viewed

6 picks

Type

dotnet-testing-advanced-testcontainers-database

28stars4forks

View on GitHub

How to install dotnet-testing-advanced-testcontainers-database?

kevintsengtw/dotnet-testing-agent-skills/dotnet-testing-advanced-testcontainers-database

$npx -y skills add kevintsengtw/dotnet-testing-agent-skills --skill dotnet-testing-advanced-testcontainers-database

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Testcontainers 資料庫整合測試指南
2
3	## EF Core InMemory 的限制
4
5	在選擇測試策略前，必須了解 EF Core InMemory 資料庫的重大限制：
6
7	### 1. 交易行為與資料庫鎖定
8
9	- 不支援資料庫交易 (Transactions)：`SaveChanges()` 後資料立即儲存，無法進行 Rollback
10	- 無資料庫鎖定機制：無法模擬並發 (Concurrency) 情境下的行為
11
12	### 2. LINQ 查詢差異
13
14	- 查詢翻譯差異：某些 LINQ 查詢（複雜 GroupBy、JOIN、自訂函數）在 InMemory 中可執行，但轉換成 SQL 時可能失敗
15	- Case Sensitivity：InMemory 預設不區分大小寫，但真實資料庫依賴校對規則 (Collation)
16	- 效能模擬不足：無法模擬真實資料庫的效能瓶頸或索引問題
17
18	### 3. 資料庫特定功能
19
20	InMemory 模式無法測試：預存程序、Triggers、Views、外鍵約束、檢查約束、資料類型精確度、Concurrency Tokens 等。
21
22	結論：當需要驗證複雜交易邏輯、並發處理、資料庫特定行為時，應使用 Testcontainers 進行整合測試。
23
24	## Testcontainers 核心概念
25
26	Testcontainers 是一個測試函式庫，提供輕量好用的 API 來啟動 Docker 容器，專門用於整合測試。
27
28	### 核心優勢
29
30	1. 真實環境測試：使用真實資料庫，測試實際 SQL 語法與資料庫限制
31	2. 環境一致性：確保測試環境與正式環境使用相同服務版本
32	3. 清潔測試環境：每個測試有獨立乾淨的環境，容器自動清理
33	4. 簡化開發環境：開發者只需 Docker，不需安裝各種服務
34
35	## 必要套件
36
37	```xml
38	<ItemGroup>
39	<!-- 測試框架 -->
40	<PackageReference Include="Microsoft.NET.Test.Sdk" Version="18.3.0" />
41	<PackageReference Include="xunit" Version="2.9.3" />
42	<PackageReference Include="xunit.runner.visualstudio" Version="3.1.5" />
43	<PackageReference Include="AwesomeAssertions" Version="9.4.0" />
44
45	<!-- Testcontainers 核心套件 -->
46	<PackageReference Include="Testcontainers" Version="4.11.0" />
47
48	<!-- 資料庫容器 -->
49	<PackageReference Include="Testcontainers.PostgreSql" Version="4.11.0" />
50	<PackageReference Include="Testcontainers.MsSql" Version="4.11.0" />
51
52	<!-- Entity Framework Core -->
53	<PackageReference Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
54	<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="9.0.0" />
55	<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.0" />
56
57	<!-- Dapper (可選) -->
58	<PackageReference Include="Dapper" Version="2.1.72" />
59	<PackageReference Include="Microsoft.Data.SqlClient" Version="7.0.0" />
60	</ItemGroup>
61	```
62
63	> 重要：使用 `Microsoft.Data.SqlClient` 而非舊版 `System.Data.SqlClient`，提供更好的效能與安全性。
64
65	## 環境需求
66
67	- Windows 10 版本 2004+，啟用 WSL 2，8GB RAM（建議 16GB+），64GB 磁碟空間
68	- Docker Desktop 建議設定：Memory 6GB、CPUs 4 cores、Swap 2GB、Disk 64GB
69
70	## 基本容器操作模式
71
72	使用 `IAsyncLifetime` 管理容器生命週期，在 `InitializeAsync` 中啟動容器並建立 DbContext，在 `DisposeAsync` 中釋放資源。支援 PostgreSQL（`PostgreSqlBuilder`）和 SQL Server（`MsSqlBuilder`）。
73
74	> 完整程式碼範例請參考 [references/container-basics.md](references/container-basics.md)
75
76	## Collection Fixture 模式：容器共享
77
78	在大型專案中，每個測試類別都建立新容器會遇到嚴重的效能瓶頸。Collection Fixture 讓所有測試類別共享同一個容器，測試執行時間可減少約 67%。
79
80	包含 SQL 腳本外部化策略（將 SQL 檔案從 C# 程式碼分離）與 Wait Strategy 最佳實務。
81
82	> 完整 Collection Fixture 實作、SQL 腳本外部化與 Wait Strategy 範例請參考 [references/collection-fixture-and-scripts.md](references/collection-fixture-and-scripts.md)
83
84	## EF Core 進階功能測試
85
86	涵蓋 Include/ThenInclude 多層關聯查詢、AsSplitQuery 避免笛卡兒積、N+1 查詢問題驗證、AsNoTracking 唯讀查詢最佳化等完整測試範例。
87
88	> 完整程式碼範例請參考 [references/orm-advanced-testing.md](references/orm-advanced-testing.md#ef-core-進階功能測試)
89
90	## Dapper 進階功能測試
91
92	涵蓋基本 CRUD 測試類別設置、QueryMultiple 一對多關聯處理、DynamicParameters 動態查詢建構等完整測試範例。
93
94	> 完整程式碼範例請參考 [references/orm-advanced-testing.md](references/orm-advanced-testing.md#dapper-進階功能測試)
95
96	## Repository Pattern 設計原則
97
98	### 介面分離原則 (ISP) 的應用
99
100	- `IProductRepository`：基礎 CRUD 操作介面（GetAll、GetById、Add、Update、Delete）
101	- `IProductByEFCoreRepository`：EF Core 特有進階功能（SplitQuery、BatchUpdate、NoTracking）
102	- `IProductByDapperRepository`：Dapper 特有進階功能（多表查詢、動態參數、預存程序）
103
104	### 設計優勢
105
106	1. 單一職責原則 (SRP)：每個介面專注於特定職責
107	2. 介面隔離原則 (ISP)：使用者只需依賴所需的介面
108	3. 依賴反轉原則 (DIP)：高層模組依賴抽象而非具體實作
109	4. 測試隔離性：可針對特定功能進行精準測試
110
111	## 常見問題處理
112
113	### Docker 容器啟動失敗
114
115	```bash
116	# 檢查連接埠是否被佔用
117	netstat -an \| findstr :5432
118
119	# 清理未使用的映像檔
120	docker system prune -a
121	```
122
123	### ContainerNotRunningException（4.8.0+ 新增）
124
125	Testcontainers 4.8.0 起，預設等待策略改為等待容器進入 Running 狀態。若容器未能正常啟動，會拋出此例外。常見原因：映像檔名稱錯誤、Docker 資源不足、連接埠衝突。
126
127	### 記憶體不足問題
128
129	- 調整 Docker Desktop 記憶體配置
130	- 限制同時執行的容器數量
131	- 使用 Collection Fixture 共享容器
132
133	### 測試資料隔離
134
135	在 `Dispose` 中按照外鍵約束順序清理資料（OrderItems → Orders → Products → Categories）。
136
137	## 輸出格式
138
139	- 產生使用 Testcontainers 的 xUnit 整合測試類別（.cs 檔案）
140	- 包含 IAsyncLifetime 容器生命週期管理程式碼
141	- 包含 Collection Fixture 共享容器設定
142	- 產生外部化 SQL 腳本檔案（.sql）與對應的 .csproj 設定
143	- 包含 Repository Pattern 介面與實作範例
144
145	## 參考資源
146
147	### 原始文章
148
149	本技能內容提煉自「老派軟體工程師的測試修練 - 30 天挑戰」系列文章：
150
151	- Day 20 - Testcontainers 初探：使用 Docker 架設測試環境
152	- 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10376401
153	- 範例程式碼：https://github.com

People who liked this also viewed

6 picks

Type