275 lines
7.1 KiB
Markdown
275 lines
7.1 KiB
Markdown
# 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 容器設定
|
|
- **自動清理**: 測試完成後自動清理資源
|
|
- **服務配置**: 可覆寫的服務配置方法
|
|
|
|
```csharp
|
|
public abstract class TestBase : IDisposable
|
|
{
|
|
protected readonly DramaLingDbContext DbContext;
|
|
protected readonly ServiceProvider ServiceProvider;
|
|
|
|
// 提供完整的測試環境設定
|
|
}
|
|
```
|
|
|
|
### TestDataFactory 類別
|
|
|
|
提供便利的測試資料建立方法：
|
|
|
|
```csharp
|
|
// 建立測試使用者
|
|
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` - 複雜物件完整性測試
|
|
|
|
---
|
|
|
|
## 🚀 執行測試
|
|
|
|
### 基本指令
|
|
|
|
```bash
|
|
# 執行所有測試
|
|
dotnet test
|
|
|
|
# 執行特定類別測試
|
|
dotnet test --filter "ClassName=FlashcardRepositoryTests"
|
|
|
|
# 執行特定測試方法
|
|
dotnet test --filter "MethodName=GetByUserIdAsync_ShouldReturnUserFlashcards"
|
|
|
|
# 產生覆蓋率報告
|
|
dotnet test --collect:"XPlat Code Coverage"
|
|
```
|
|
|
|
### 測試分類
|
|
|
|
```bash
|
|
# 執行單元測試
|
|
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 模式：
|
|
|
|
```csharp
|
|
[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. **繼承適當的基類**
|
|
```csharp
|
|
public class NewServiceTests : TestBase
|
|
{
|
|
// 測試實作
|
|
}
|
|
```
|
|
|
|
3. **使用 TestDataFactory 建立測試資料**
|
|
```csharp
|
|
var testData = TestDataFactory.CreateFlashcard();
|
|
```
|
|
|
|
4. **遵循 AAA 模式和命名規則**
|
|
|
|
5. **確保測試隔離和清理**
|
|
|
|
---
|
|
|
|
**最後更新**: 2025-09-30
|
|
**維護者**: DramaLing 開發團隊
|
|
**測試架構版本**: 1.0
|
|
**狀態**: 階段四完成 ✅ |