三個判斷問題

斷言的是行為嗎

Assertion 應該斷言程式碼的外部可觀察行為（回傳值、狀態變化、副作用），而非內部實作細節（私有變數的值、呼叫次數、執行順序）。

斷言行為的 test 在重構時不需要改 — 只要行為不變，test 就通過。斷言實作的 test 在任何內部調整時都會壞掉，即使行為完全正確。

例：驗證「parser 正確解析紅色文字」時，斷言 token 的顏色屬性（行為）比斷言 parser 內部的 state machine 走了哪些步驟（實作）更穩定。

能區分正確和錯誤嗎

Assertion 應該在程式碼正確時通過、錯誤時失敗。如果 assertion 無論程式碼正確或錯誤都通過，這個 assertion 沒有提供保護。

常見的無效 assertion：

斷言不為 null：expect(result, isNotNull) 只驗證「有回傳值」，不驗證「回傳值正確」。回傳錯誤的值也會通過。

斷言型別：expect(result, isA<List>()) 只驗證「回傳 List」，不驗證 List 的內容。空 List 和錯誤內容的 List 都會通過。

斷言包含：expect(result, contains('error')) 驗證字串包含 ’error’，但如果回傳 ’no error occurred’（正確情境）也包含 ’error’ — assertion 無法區分正確和錯誤。

T.C3 的 parser test 斷言 expect(tokens.first, isA<TextToken>()) — 驗證 token 型別是 TextToken。但正確解析和透傳亂碼都可能產生 TextToken，assertion 無法區分（本章合成，TF-5 Derive — 透傳的靜默副作用和 assertion 的區分力有 tension）。

會 flaky 嗎

Assertion 是否依賴非確定性因素 — 時間、隨機數、外部服務狀態、執行順序。如果是，test 可能在程式碼正確時失敗（false negative），降低團隊對 test 的信任。

常見的 flaky assertion 來源：

• 依賴 DateTime.now() 或 stopwatch.elapsed — 時間精度和系統負載影響結果
• 依賴特定的執行順序 — Set 或 Map 的迭代順序不保證
• 依賴外部服務的回應時間 — 網路延遲導致 timeout

Assertion 改善的操作步驟

對既有的 test assertion 逐一問三個問題，標記需要改善的：

1. 行為 check：assertion 斷言的是 public API 的回傳值或狀態嗎？如果斷言私有變數或呼叫次數，考慮改成行為斷言。
2. 區分 check：把 assertion 改成反向（expect(result, 'wrong_value')），test 會失敗嗎？如果 assertion 太寬鬆（isNotNull、isA），test 可能在錯誤的情況下也通過。
3. 穩定 check：連續跑 10 次，每次都通過嗎？如果有 flaky，找到依賴的非確定性因素。

下一步路由

• Flaky test 的系統性根因分類 → Flaky test 根因分類
• 測試資料的代表性 → Test data 代表性
• Mock 邊界判斷 → Mock 邊界判斷決策表

格式統一性

app_tunnel 在 W2 修復時補的 developer.log 格式不統一（T.C4）。不同元件由不同時間點、不同 debug 需求補上的 log，各自有各自的風格：

有的帶 name: 參數讓 log 可以按元件過濾：

1developer.log('WS connected', name: 'ConnectionManager');

有的不帶，混在全域 log 裡無法過濾：

1developer.log('auth token sent');

有的帶 // i18n-exempt 標記（因為 linter 會對 hardcoded string 報警），有的忘了加。有的把錯誤訊息放在 error: 參數，有的用字串串接。

這些不一致來自事後補 log 的結構性原因：每條 log 是在解決當下問題時加的，沒有統一規範，也沒有 review。加完能定位問題就提交，下次遇到新問題再加新的 log — 格式隨機。

設計產物 log 在產出前就有命名規則和格式規範（見 功能規格中的 log 點定義方法）。所有 log 點走同一個 AppLogger 介面，name、level、結構化欄位在規格階段就定義好，實作時照規格寫。

覆蓋完整性

事後補 log 的覆蓋範圍由「哪些問題已經發生過」決定。W2-002 auth token 問題觸發了 ConnectionManager 和 TerminalScreen 的 log 補充，但 TtydProtocol、BiometricService、CredentialRepository、EnrollmentScreen 四個元件仍然零 log — 因為這四個元件在 W2 的 debug 過程中不是瓶頸。

六個核心元件中四個零 log 的狀態意味著：下次如果問題出在 BiometricService（例如特定 iOS 版本的 biometric API 行為改變），debug 又會回到「手動加 log → 重新編譯 → 插拔裝置」的循環。事後補 log 只覆蓋已知問題的路徑，對未知問題沒有防護。

設計產物 log 的覆蓋範圍由功能流程的步驟數決定。每個功能規格列出所有步驟的 log 點，不管這些步驟是否曾經出過問題。BiometricService.authenticate() 在規格中就有 start/done/failed 三個 log 點，無論是否遇過 biometric 問題。

維護成本

事後補 log 隨 debug 過程累積，沒有統一管理。隨時間推移：

• 某些 log 的觸發條件已經不存在了（被修復的 bug 對應的 log），但沒人清理
• 某些 log 的格式和新加的 log 不一致，但沒人統一
• 某些 log 的 context 資訊不足（當時能定位問題是因為開發者記得 context，半年後換人接手就不夠了）
• 某些 log 在 release build 中不該出現但忘了加條件

設計產物 log 有規格文件作為 source of truth。功能變更時更新規格中的 log 點列表，刪除的步驟對應的 log 點一起刪除，新增的步驟對應的 log 點一起新增。Log 的生命週期和功能的生命週期綁定。

從事後補過渡到設計產物

已有的事後補 log 不需要全部重寫。過渡策略是：

統一入口：建立 AppLogger 封裝，把現有的 developer.log 呼叫改為走 AppLogger。這一步不改 log 內容，只改呼叫方式，讓後續的格式統一和功能切換有統一入口。

補規格：對每個功能寫出 log 點規格表（四類 log 點），比對現有 log 和規格的差距。規格中有但程式碼中沒有的 log 點 = 覆蓋缺口，補上。程式碼中有但規格中沒有的 log 點 = 可能是過時的 debug log，評估是否刪除。

新功能走設計產物流程：從下一個新功能開始，功能規格中包含可觀測性欄位。新功能的 log 從一開始就是設計產物品質。

過渡的第一步是建立統一入口，具體的 log 點規格格式見功能規格中的 log 點定義方法。規格中的每個 log 點屬於哪一層（連線生命週期 / protocol / 使用者行為），在三層 log 設計中定義。收集到 log 之後用自架還是商業方案處理，見自架 log endpoint vs 商業方案的判斷流程。