ASP.NET Core 整合測試指南

核心概念

整合測試的兩種定義

1. 多物件協作測試 — 將兩個以上的類別做整合，測試它們之間的運作是否正確
2. 外部資源整合測試 — 使用到資料庫、外部服務、檔案等外部資源的測試

為什麼需要整合測試？

• 確保多個模組整合後能正確工作
• 單元測試無法涵蓋的整合點：Routing、Middleware、Request/Response Pipeline
• 確認 WebApplication 的整合與設定是否正確
• 確認異常處理是否完善

測試金字塔定位

測試類型	測試範圍	執行速度	維護成本	建議比例
單元測試	單一類別/方法	很快	低	70%
整合測試	多個元件	中等	中等	20%
端對端測試	完整流程	慢	高	10%

原則一：使用 WebApplicationFactory 建立測試環境

透過 WebApplicationFactory<Program> 建立記憶體中的 TestServer，搭配 IClassFixture 在測試類別間共享。

基本流程

1. 測試類別實作 IClassFixture<WebApplicationFactory<Program>>
2. 透過建構函式注入 Factory
3. 使用 factory.CreateClient() 建立 HttpClient
4. 對 API 端點發送請求並驗證回應

自訂 Factory

繼承 WebApplicationFactory<Program> 並覆寫 ConfigureWebHost：

• 移除原本的 DbContextOptions，改用 UseInMemoryDatabase
• 使用 services.Replace() 替換外部服務為測試版本
• 設定 builder.UseEnvironment("Testing") 使用測試環境

測試基底類別

建立 IntegrationTestBase 封裝共用邏輯：

• Factory 與 HttpClient 初始化
• SeedShipperAsync() 等資料準備方法
• CleanupDatabaseAsync() 清理方法
• 實作 IDisposable 確保資源釋放

完整程式碼範例（基本使用、自訂 Factory、測試基底類別）請參考 references/webapplicationfactory-examples.md

原則二：使用 AwesomeAssertions.Web 驗證 HTTP 回應

提供流暢的 HTTP 狀態碼斷言與強型別回應驗證：

• 狀態碼斷言：Be200Ok()、Be201Created()、Be400BadRequest()、Be404NotFound() 等
• Satisfy<T> 驗證：response.Should().Be200Ok().And.Satisfy<T>(result => { ... })
• 優勢：取代手動 ReadAsStringAsync() + JsonSerializer.Deserialize<T>() 的冗長程式碼

原則三：使用 System.Net.Http.Json 簡化 JSON 操作

• PostAsJsonAsync(url, object) — 取代手動 JsonSerializer.Serialize + new StringContent
• ReadFromJsonAsync<T>() — 取代手動 ReadAsStringAsync + JsonSerializer.Deserialize

完整斷言與 JSON 操作範例請參考 references/assertion-and-json-examples.md

三個層級的整合測試策略

Level	特色	測試重點	Factory 設定
1	無資料庫、無 Service	API 輸入輸出、路由、狀態碼	直接使用原始 Factory
2	有 Service（NSubstitute）	依賴注入配置、服務互動	ConfigureTestServices
3	完整架構 + 資料庫	真實 CRUD、資料完整性	InMemoryDatabase 替換

Level 1：簡單的 WebApi 專案

最簡單的形式，直接使用 WebApplicationFactory<Program> 測試各個 API 端點的輸入輸出。

Level 2：相依 Service 的 WebApi 專案

使用 NSubstitute 建立 Service stub，透過自訂 Factory 的 ConfigureTestServices 注入測試用服務。

Level 3：完整的 WebApi 專案

包含真實的資料庫操作，移除原本的 DbContextOptions 並改用 InMemoryDatabase，在測試中呼叫 EnsureCreated() 建立結構。

完整三個層級的程式碼範例請參考 references/three-level-testing-strategy.md

CRUD 操作測試

測試涵蓋範圍

操作	測試重點
GET	單一資源查詢、集合查詢、不存在資源回傳 404
POST	建立成功回傳 201、驗證錯誤回傳 400
PUT	更新成功、不存在資源處理
DELETE	刪除成功回傳 204、不存在資源回傳 404

測試資料管理

• 每個測試開始前呼叫 CleanupDatabaseAsync() 確保乾淨狀態
• 使用 SeedShipperAsync() 等方法準備測試資料
• 使用 Satisfy<T>() 驗證回應內容的正確性

完整的 CRUD 操作測試程式碼請參考 references/crud-test-examples.md

專案結構建議

tests/
├── Sample.WebApplication.UnitTests/           # 單元測試
├── Sample.WebApplication.Integration.Tests/   # 整合測試
│   ├── Controllers/                           # 控制器整合測試
│   ├── Infrastructure/                        # 測試基礎設施
│   │   └── CustomWebApplicationFactory.cs
│   ├── IntegrationTestBase.cs                 # 測試基底類別
│   └── GlobalUsings.cs
└── Sample.WebApplication.E2ETests/            # 端對端測試

常見錯誤排除

'ObjectAssertions' 未包含 'Be200Ok' 的定義

此錯誤通常是因為安裝了不相容的斷言套件組合。請確認基礎斷言庫與 Web 擴充套件版本一致。

Program 類別無法存取

確保主專案的 Program.cs 包含以下宣告，讓測試專案可以存取：

public partial class Program { }

測試資料互相干擾

• 每個測試開始前清理資料庫
• 不要依賴其他測試的執行順序
• 使用唯一識別碼避免資料衝突

套件相容性

基礎斷言庫	正確的套件
FluentAssertions < 8.0.0	FluentAssertions.Web
FluentAssertions >= 8.0.0	FluentAssertions.Web.v8
AwesomeAssertions >= 8.0.0	AwesomeAssertions.Web

<!-- 推薦組合 -->
<PackageReference Include="AwesomeAssertions" Version="9.4.0" />
<PackageReference Include="AwesomeAssertions.Web" Version="1.9.6" />

最佳實踐

應該做

1. 獨立測試專案 — 整合測試與單元測試分離
2. 測試資料隔離 — 每個測試案例有獨立的資料準備和清理
3. 使用基底類別 — 共用設定和輔助方法放在基底類別
4. 明確的命名 — 使用三段式命名法（方法_情境_預期）
5. 適當的測試範圍 — 專注於整合點，不過度測試

應該避免

1. 混合測試類型 — 不要將單元測試和整合測試放在同一專案
2. 測試相依性 — 每個測試應獨立，不依賴其他測試的執行順序
3. 過度模擬 — 整合測試應盡量使用真實元件
4. 忽略清理 — 測試完成後要清理測試資料
5. 硬編碼資料 — 使用工廠方法或 Builder 模式建立測試資料

輸出格式

• 產生 CustomWebApplicationFactory.cs，配置測試用 DI 容器與資料庫替換
• 產生 IntegrationTestBase.cs 測試基底類別，包含資料準備與清理方法
• 產生控制器測試類別（*ControllerTests.cs），涵蓋 CRUD 操作驗證
• 修改測試專案 .csproj，加入 Microsoft.AspNetCore.Mvc.Testing 與 AwesomeAssertions.Web
• 確保主專案 Program.cs 包含 public partial class Program { } 以支援測試存取

參考資源

原始文章

• Day 19 - 整合測試入門：基礎架構與應用場景
  • 鐵人賽文章：https://ithelp.ithome.com.tw/articles/10376335
  • 範例程式碼：https://github.com/kevintsengtw/30Days_in_Testing_Samples/tree/main/day19

官方文件

• ASP.NET Core 整合測試文件
• WebApplicationFactory 使用指南
• AwesomeAssertions.Web GitHub

相關技能

• unit-test-fundamentals - 單元測試基礎
• nsubstitute-mocking - 使用 NSubstitute 進行模擬
• awesome-assertions-guide - AwesomeAssertions 流暢斷言
• testcontainers-database - 使用 Testcontainers 進行容器化資料庫測試