01-test-strategy.md

測試策略規範

目標讀者：AI 代理（規範解析）與人類 QA/開發人員。
背景：本文檔定義了認證考試題庫應用程式的測試策略。例如，在一個網路考試應用程式中，這些策略可確保題目、網路邏輯（如 IP 位址計算）及使用者進度的可靠性。

1. 測試金字塔

本專案遵循標準測試金字塔，以平衡執行速度與信心水準：

• 單元測試 (70%)：專注於 Models、Services、Controllers、Repositories 及 Utils。這些測試在隔離環境中執行，不依賴 UI。
• 元件測試 (Widget Tests, 20%)：確保 UI 元件、畫面渲染及使用者互動在無頭 (headless) 環境中運作正常。
• 整合/端到端測試 (10%)：驗證完整使用者流程與跨服務互動，於模擬器或實體裝置上執行。

2. 工具鏈

• flutter_test：內建的單元與元件測試框架。
• mockito / mocktail：用於產生模擬類別 (Mock) 及模擬依賴項。
• flutter_gherkin：用於行為驅動開發 (BDD) 測試執行與定義 Feature 檔案。
• integration_test：官方的端到端 (E2E) 測試套件。
• golden_toolkit：（選用）用於跨不同螢幕尺寸的像素級截圖測試。

3. 測試環境

• Mock Repository 注入：透過 RepositoryFactory.setMockRepository() 在元件與控制器測試中注入模擬資料來源。
• Firebase Emulator Suite：用於身分驗證與即時資料庫測試的本機模擬器，避免影響正式環境資料。
• 記憶體內資料庫 (In-Memory)：用於 PowerSync 本機 SQLite 同步測試。
• RevenueCat Sandbox：使用測試 API 金鑰與沙盒環境進行 App 內購買驗證。

4. 覆蓋率目標

我們的目標程式碼覆蓋率指標如下：

• Models：100%（對資料完整性至關重要）
• Services：80%+（商業邏輯層）
• Controllers：90%+（狀態管理）
• Repositories：85%+（資料存取層）
• Widgets：60%+（核心 UI 元件）
• Screens：40%+（主要透過整合/E2E 測試涵蓋）

5. CI 整合

• Pre-commit：提交前必須通過 flutter analyze lib 與 flutter test（單元/元件測試）。
• PR Gate：在 GitHub Actions 上執行完整測試套件並產生覆蓋率報告。未達覆蓋率標準的 PR 將被阻擋。

graph TD
    A["提交程式碼"] --> B["Pre-commit Hooks"]
    B -->|通過| C["推送到 GitHub"]
    C --> D["GitHub Actions CI"]
    D --> E["Linter 與格式化"]
    D --> F["單元與元件測試"]
    D --> G["整合測試 (Firebase 模擬器)"]
    F --> H["覆蓋率報告"]
    H --> I{"達到目標？"}
    I -->|是| J["允許合併"]
    I -->|否| K["阻擋 PR"]

02-unit-tests.md

單元測試規範

目標讀者：AI 代理與 QA 工程師。
背景：核心通用認證考試模組的全面單元測試，涵蓋封包邏輯與通用題型。

1. Models 測試 (約 25 個案例)

2. Services 測試 (約 30 個案例)

3. Controllers 測試 (約 15 個案例)

4. Repository 測試 (約 10 個案例)

03-widget-tests.md

元件測試規範 (Widget Tests)

目標讀者：AI 代理與 QA 工程師。
背景：確保練習測驗應用程式中的各個 UI 元件能正確渲染並符合預期行為。

1. 元件測試 (約 20 個案例)