跳轉到

ADR 0004: 採用 Capture-First 的 TDD 測試驅動策略

Context (背景脈絡)

在開發階段，專案高度依賴外部甚至閉源的生態系 API（Google Calendar, Moodle）。如果針對每一次的 Code Change 都要真實發出網路請求，會導致： 1. 測試極度緩慢且不穩定（網路延遲、登入失效）。 2. 無法模擬複雜的極端情況（如某天排入 20 個事件的碰撞情境，要在真實 Calendar 裡建立這些假事件非常痛苦）。 而如果由開發者「自己手捏 JSON Mock」，又往往會出錯，導致寫出來的測試通過了，串接到真實 API 卻掛掉（因為自己捏的 Mock 與真實回傳格式有落差）。

Decision (技術決策)

強制推行 Capture-First 的測試與除錯哲學。

  1. 攔截與快照真相 (Snapshot Truth)： 我們區分兩種層級的離線資料：
  2. tests/snapshots/ (測試快照)：包含 API 回傳的最原始、未經清洗的 Raw JSON。這是用於 Unit Test 與 Regression Test 的唯一可信來源。
  3. assets/fixtures/ (展示用 Mock)：這是經過清洗、脫敏處理的資料，專門提供給 MCP_DEV_MODE 作為 Demo 或前端渲染驗證使用。
  4. 基於數據驅動測試： 所有的資料流 (Data-flow) 與領域邏輯轉換測試，都必須讀取這些快照檔案作為輸入，不再進行任何網路請求。

Consequences (決策結果)

Positive (優點)

  • 光速的回饋迴圈：執行跑過所有的單元測試套件只需數百毫秒，極大地加速了開發效率。
  • 零憑證開發體驗 (Dev Mode)：這套架構催生了 MCP_DEV_MODE=1 的誕生。使得評審、設計師或新進開發者可以在完全沒有授權 Token 的情況下，透過讀取本機快照完成全流程式的檢驗與 UI 開發。
  • 消解 Mock 幻覺：消除了手動捏造 Mock 所帶來的結構不一致型別錯誤風險。

Negative (缺點)

  • 外部 API 變更盲點：如果 Google 或臺科大 Moodle 擅自更改了真實 API 的回傳欄位，基於舊版截圖的測試會全部綠色通過，無法提早發出警報（這能透過定期執行 Live Test 緩解）。
  • 快照檔案膨脹：長期開發下來，存放 Snapshot 的目錄會堆積許多 JSON 檔案，需建立定期清理或命名的管理準則。