---
name: tdd-workflow
description: 在編寫新功能、修復 Bug 或進行程式碼重構時使用。強制執行測試驅動開發 (TDD)，要求包含單元測試、整合測試與 E2E 測試在內的 80% 以上覆蓋率。
---

# 測試驅動開發工作流 (TDD Workflow)

本技能確保所有程式碼開發均遵循 TDD 原則，並具備全面的測試覆蓋。

## 何時啟用

- 撰寫新功能或模組。
- 修復 Bug 或解決已知問題。
- 重構現有程式碼。
- 建立 API 端點。
- 封裝新的組件 (Components)。

## 核心原則

### 1. 先寫測試，後寫代碼
**務必**先編寫測試案例，接著才編寫最少量的程式碼使測試通過。

### 2. 覆蓋率硬指標
- 整體覆蓋率（單元 + 整合 + E2E）需達到 **80% 以上**。
- 必須涵蓋所有邊際案例 (Edge Cases)。
- 必須測試錯誤情境 (Error Scenarios) 與邊界條件。

### 3. 測試類型定義

- **單元測試 (Unit)**：測試純函式、工具類、組件邏輯。
- **整合測試 (Integration)**：驗證 API 端點、資料庫操作與服務間的交互。
- **E2E 測試 (Playwright/Cypress)**：模擬真實用戶在瀏覽器中的完整操作流程。

## TDD 標準步驟

1. **撰寫用戶旅程 (User Journey)**：以使用者視角定義需求。
2. **產出測試案例 (Fail)**：先定義 `describe` 與 `it` 區塊，此時執行測試應為失敗（紅燈）。
3. **實作最小代碼 (Success)**：編寫程式碼直到測試轉為通過（綠燈）。
4. **重構 (Refactor)**：在測試通過的前提下優化程式碼品質（如：消除重複、提升效能）。
5. **驗證覆蓋率**：執行覆蓋率工具，確保達標。

## 實踐之最佳實踐

- **測試行為，而非實作**：測試使用者看到的結果（如：文字內容），而非內部變數狀態。
- **使用穩健的選取器**：在前端測試中優先使用 `data-testid` 或語義化選取器（如：`getByRole`），避免使用易變的 CSS Class。
- **測試隔離**：每個測試案例應獨立設置其所需數據，避免案例間的相互依賴。
- **模擬外部服務 (Mocking)**：對於資料庫、第三方 API（如 OpenAI, Redis）應進行 Mock 處理以保持單元測試的速度與穩定性。
- **一測一斷言**：每個測試案例應專注於驗證單一行為。

## 常見錯誤避免

- ❌ **錯誤**：為了測試而測試，忽略了真實的業務邏輯邊界。
- ❌ **錯誤**：不維護測試代碼，導致測試變成開發的累贅。
- ✅ **正確**：將測試視為開發的一部分，持續優化並與功能同步更新。

---

**核心原則**：測試不是可選項，它是支撐頻繁重構、快速開發與生產環境穩定性的安全網。
