dramaling-vocab-learning/backend/DramaLing.Api/DramaLing.Api.Tests/README.md

DramaLing.Api.Tests

版本: 1.0 框架: xUnit + .NET 8 狀態: 階段四測試架構已建立 ✅

🧪 測試架構概覽

本測試專案採用現代化的 .NET 8 測試框架，提供完整的單元測試、整合測試和端到端測試基礎設施。

測試專案結構

DramaLing.Api.Tests/
├── README.md                 # 本文檔 - 測試架構說明
├── TestBase.cs              # 測試基類 - 提供通用測試設施
├── Unit/                    # 單元測試
│   ├── Services/           # 服務層測試
│   │   └── JsonCacheSerializerTests.cs  # 快取序列化器測試
│   ├── Controllers/        # 控制器測試
│   └── Repositories/       # Repository 測試
│       └── FlashcardRepositoryTests.cs  # Flashcard Repository 測試
├── Integration/            # 整合測試
├── E2E/                   # 端到端測試
└── TestData/              # 測試資料工廠
    └── TestDataFactory.cs # 測試資料建立工具

---

🔧 核心測試基礎設施

TestBase 類別

所有單元測試的基礎類別，提供：

• InMemory 資料庫: 使用 Entity Framework InMemory 提供者
• 依賴注入: 完整的 DI 容器設定
• 自動清理: 測試完成後自動清理資源
• 服務配置: 可覆寫的服務配置方法

public abstract class TestBase : IDisposable
{
    protected readonly DramaLingDbContext DbContext;
    protected readonly ServiceProvider ServiceProvider;

    // 提供完整的測試環境設定
}

TestDataFactory 類別

提供便利的測試資料建立方法：

// 建立測試使用者
var user = TestDataFactory.CreateUser();

// 建立測試單字卡
var flashcard = TestDataFactory.CreateFlashcard(userId);

// 建立多個測試單字卡
var flashcards = TestDataFactory.CreateFlashcards(userId, count: 5);

// 建立分析快取資料
var cache = TestDataFactory.CreateAnalysisCache(sentence);

---

📋 已實施的測試

1. Repository 層測試

FlashcardRepositoryTests - 完整的 Repository 模式測試：

• ✅ GetByUserIdAsync_ShouldReturnUserFlashcards - 使用者單字卡查詢
• ✅ GetByUserIdAndFlashcardIdAsync_ShouldReturnSpecificFlashcard - 特定單字卡查詢
• ✅ GetByUserIdAsync_WithSearch_ShouldReturnFilteredResults - 搜尋過濾功能
• ✅ GetCountByUserIdAsync_ShouldReturnCorrectCount - 計數功能測試

2. 服務層測試

JsonCacheSerializerTests - 快取序列化服務測試：

• ✅ Serialize_ValidObject_ShouldReturnByteArray - 物件序列化
• ✅ Deserialize_ValidByteArray_ShouldReturnObject - 反序列化
• ✅ Serialize_NullObject_ShouldThrowException - 例外處理
• ✅ Deserialize_InvalidByteArray_ShouldReturnNull - 錯誤處理
• ✅ RoundTrip_ComplexObject_ShouldMaintainDataIntegrity - 複雜物件完整性測試

---

🚀 執行測試

基本指令

# 執行所有測試
dotnet test

# 執行特定類別測試
dotnet test --filter "ClassName=FlashcardRepositoryTests"

# 執行特定測試方法
dotnet test --filter "MethodName=GetByUserIdAsync_ShouldReturnUserFlashcards"

# 產生覆蓋率報告
dotnet test --collect:"XPlat Code Coverage"

測試分類

# 執行單元測試
dotnet test --filter "Category=Unit"

# 執行整合測試
dotnet test --filter "Category=Integration"

# 執行端到端測試
dotnet test --filter "Category=E2E"

---

📊 測試覆蓋狀況

已覆蓋組件

組件類型	已測試項目	測試數量	狀態
Repository	FlashcardRepository	4 個測試	✅ 完成
Services	JsonCacheSerializer	5 個測試	✅ 完成
Controllers	-	0 個測試	⏳ 待實施
Integration	-	0 個測試	⏳ 待實施

測試指標

• 單元測試數量: 9 個
• 測試類別數量: 2 個
• 測試基礎設施: ✅ 完整
• 測試資料工廠: ✅ 完整

---

🔬 測試模式和最佳實務

AAA 模式 (Arrange-Act-Assert)

所有測試都遵循 AAA 模式：

[Fact]
public async Task GetByUserIdAsync_ShouldReturnUserFlashcards()
{
    // Arrange - 準備測試資料
    var user = TestDataFactory.CreateUser();
    var flashcards = TestDataFactory.CreateFlashcards(user.Id, 3);

    // Act - 執行被測試的動作
    var result = await _repository.GetByUserIdAsync(user.Id);

    // Assert - 驗證結果
    Assert.NotNull(result);
    Assert.Equal(3, result.Count());
}

測試命名規則

• 模式: {MethodName}_{Scenario}_{ExpectedBehavior}
• 範例: GetByUserIdAsync_WithSearch_ShouldReturnFilteredResults

測試資料隔離

• 每個測試使用獨立的 InMemory 資料庫
• 測試完成後自動清理資源
• 避免測試間的資料污染

---

🎯 階段四完成成果

✅ 已完成項目

1. 測試專案結構建立

   • xUnit 測試框架設定
   • 標準目錄結構 (Unit/Integration/E2E)
   • 必要套件配置

2. 基礎測試設施實作

   • TestBase 抽象基類
   • TestDataFactory 資料工廠
   • 依賴注入和資料庫設定

3. 關鍵服務單元測試

   • Repository 層完整測試覆蓋
   • 核心服務層測試實作
   • 錯誤處理和邊界情況測試

4. 測試文檔和規範

   • 完整的測試指南
   • 最佳實務文檔
   • 執行指令說明

📈 技術優勢

• Clean Architecture 支援: 測試架構完全符合專案的 Clean Architecture 原則
• 依賴注入整合: 完整支援 ASP.NET Core DI 容器
• 資料隔離: 每個測試都有獨立的資料庫環境
• 可擴展性: 易於添加新的測試類別和測試案例
• 效能優化: 使用 InMemory 資料庫提供快速測試執行

---

📋 後續開發建議

階段五建議

1. 增加整合測試

   • API 端點測試
   • 中間件測試
   • 認證授權測試

2. 提升測試覆蓋率

   • Controller 層測試
   • 更多 Service 層測試
   • 錯誤處理測試

3. 效能測試

   • 負載測試
   • 記憶體使用測試
   • 資料庫查詢效能測試

4. CI/CD 整合

   • GitHub Actions 設定
   • 自動化測試執行
   • 覆蓋率報告生成

---

🔧 開發指南

新增測試的步驟

1. 選擇適當的測試類別目錄

   • Unit/ - 單元測試
   • Integration/ - 整合測試
   • E2E/ - 端到端測試

2. 繼承適當的基類

   public class NewServiceTests : TestBase
   {
       // 測試實作
   }
   

3. 使用 TestDataFactory 建立測試資料

   var testData = TestDataFactory.CreateFlashcard();
   

4. 遵循 AAA 模式和命名規則

5. 確保測試隔離和清理

---

最後更新: 2025-09-30 維護者: DramaLing 開發團隊 測試架構版本: 1.0 狀態: 階段四完成 ✅