測試標準與風格指南

本文件定義 Time Compass 的測試目錄規範、命名準則與分層測試哲學。

決策背景請見：ADR 0004：採用 Capture-First 的 TDD 測試驅動策略

1. 目錄結構（Mirror 規範）

測試目錄必須嚴格鏡像 src/ 的模組結構，確保可發現性與維護一致性。

tests/
├── helpers/                    # 測試工具（fixtures、evidence 收集）
│   └── evidence.py             # 核心 evidence 收集器
├── live/                       # 真實 API 測試（需憑證、手動執行）
│   └── moodle/                 # Moodle Live Tests
├── snapshots/                  # L0 API 回應快照（Source of Truth）
│   ├── google/                 # Google API 快照
│   └── moodle/                 # Moodle API 快照
├── output_result/              # 執行產物（Git 忽略）
├── unit/                       # L1-L2：單元與整合測試（Mock/Snapshot Based）
│   ├── integrations/           # 鏡像 src/time_compass/integrations/
│   │   ├── google_calendar/    # 測試 Read Model、Core Mock、TOON
│   │   ├── google_tasks/
│   │   ├── moodle/
│   │   └── common/             # 測試 Batch Dispatcher 等
│   ├── planner/                # Planner 演算法與執行期測試
│   └── utils/                  # 工具函式測試（時間、TOON utils）
└── system/                     # L3：系統層測試（End-to-End）
    └── mcp_suite/              # MCP 工具測試（In-Process FastMCP）

2. 命名慣例

測試命名應具備文件可讀性。

• 檔案：test_<subject>.py（例如：test_event_read_model.py）。避免 test_core.py 這種模糊命名。
• 類別：Test<Subject><Scenario>（例如：TestGoogleEventReadParsing）。
• 函式：test_<unit>_should_<expected_behavior>_when_<condition>
• ✅ test_to_toon_task_should_mark_done_when_completed_field_exists
• ❌ test_to_toon_task_done

3. 測試哲學：Capture -> Mock

第三方整合測試請遵循分層資料流策略（Data Flow Tiered Strategy）：

1. Transport / Raw 層：以真實擷取資料（L0 Snapshots）作為 Mock 來源。
2. Why：確保解析邏輯能覆蓋真實 API 回應與未文件化邊界情境。
3. How：從 tests/snapshots/ 載入 JSON/Text，禁止在測試中手寫大型 Dict。
4. Core / Application 層：Mock API Client，聚焦商業邏輯與流程控制。
5. Focus：分頁、錯誤重試、並行請求聚合。
6. Data：使用建構過的 Internal/Read 物件。
7. TOON / Presentation 層：驗證最終輸出格式。
8. Focus：Token 壓縮率與格式正確性。

4. 工具與執行環境

• 執行指令：uv run pytest（不要使用 python -m pytest）。
• 證據收集：使用 tests.helpers.evidence.save_test_result() 保存關鍵輸出（如 TOON 字串）到 tests/output_result/，供人工檢視。
• 禁止事項：正式測試程式碼中禁止 print()。