跳轉到

如何執行測試 (How-to Run Tests)

Time Compass 採用嚴格的三層測試架構，確保開發過程與外部 API 變動時的穩定性。

核心指令

執行測試前，請確保已安裝 uv 並執行過 uv sync。

1. 快速單元測試 (Unit Tests) - 🚀 推薦每 5 分鐘跑一次

  • 目的：驗證 TOON 編解碼、資料模型轉換與 Domain 邏輯。
  • 憑證：不需要任何 API Key。
  • 指令： 
    uv run pytest tests/unit

2. 真實資料擷取 (Live Tests)

  • 目的：直接與 Google/Moodle API 溝通，擷取原始 JSON 用於更新 tests/snapshots。
  • 憑證：需要完整的 .env 配置與 OAuth 授權、moodle 帳號密碼。
  • 指令： 
    uv run pytest tests/live

3. 端對端系統測試 (System Tests)

  • 目的：模擬真實用戶對話，測試 MCP 工具鏈與 AI 的整合。
  • 指令： 
    uv run pytest tests/system

測試哲學：Capture-First

  1. 遇到 Bug 時，先寫一份 tests/live/reproduce_bug.py。
  2. 執行它，擷取真實 API 的報錯快照 (Snapshot)。
  3. 將該 JSON 移入 tests/snapshots/。
  4. 在 tests/unit/ 撰寫測試，讀取該快照，並修正 Code 直到測試通過。
  5. 刪除 reproduce_bug.py。

詳細決策背景請見 ADR 0004: Capture-First TDD