| name | test-assertion-design |
| description | Assertion design judgment framework for flaky and design-quality issues. Use when writing tests, reviewing assertions, diagnosing flaky tests, or deciding if a timing/float/cache assertion is appropriate. Do NOT use for API syntax or refactoring. |
Test Assertion Design
斷言設計判斷概念框架。職責：識別「此斷言設計是否合理」，提供跨語言判斷標準。不提供測試寫法或重構步驟。
斷言品質三問
設計或審查斷言時，依序回答三個問題。任一問題答「否」即進入對應的類型判斷：
| 問題 | 判斷標準 | 「否」時對應類型 |
|---|
| 確定性 | 同一程式碼在任何執行環境下，pass/fail 結果一致？ | 類型 1–6（確定性失效） |
| 聚焦性 | 此測試案例只驗證一個行為面向？ | 類型 8–9（設計問題） |
| 隔離性 | 此測試不依賴其他測試建立的狀態或執行順序？ | 類型 7（隔離違反） |
確定性斷言的基礎形態（無問題，作為對比基線）
以下 4 種確定性斷言類型符合三問標準，可直接放功能測試套件：
| 確定性類型 | 說明 |
|---|
| 功能正確性 | 輸出值直接比對固定預期值 |
| 邏輯不變式 | 驗證數學/邏輯關係（a < b、rate < 1.0），兩側均非環境依賴值 |
| 結構驗證 | 驗證欄位存在、型別正確、陣列長度 |
| 資源清理 | 驗證洩漏偵測差值（前後 count 差值 = 0），用差值而非絕對值 |
9 類型問題斷言分類決策表
判斷軸
9 類型問題依問題本質分為兩族（partition，互斥）：
- 環境依賴 flaky 族（類型 1–4）：斷言結果受執行環境影響，核心問題是「確定性」
- 斷言設計族（類型 5–9）：斷言內容設計不當，核心問題是「驗什麼」
此分族與斷言品質三問為不同視角：三問是快速分流入口（任一否即識別問題族群）；分族是依問題本質歸類（幫助理解根因、選擇對應設計原則）。
問題類型表
| 類型 | 問題本質 | 識別信號 | 設計原則 | 來源 |
|---|
| 1. 計時硬門檻 | 使用單次計時值與絕對毫秒數比較作為 pass/fail | 計時差值對比 N ms 常數 | 受機器負載影響；功能測試套件禁用；效能門檻移至隔離執行環境 | W1-017 + W1-018 實證 |
| 2. 高精度浮點 | 浮點計算結果用超過 2 位小數精度斷言 | toBeCloseTo(x, numDigits) 其中 numDigits 超過 2 | IEEE 754 浮點路徑在跨 JIT 環境下末位數字不保證一致；超過 2 位精度需附確定性計算理由 | W1-017 + W1-018 實證 |
| 3. 相對計時比較 | 以兩次執行時間的差距或倍數比較驗證快取效果 | secondRunTime < firstRunTime * K | 相對計時同樣受 GC/JIT 影響；改用快取命中率或物件參考等價（identity equality）驗證 | W1-017 + W1-018 實證 |
| 4. 記憶體絕對值 | 用堆積記憶體使用絕對上限作為 pass/fail | heapUsed < N MB 在功能測試套件 | 記憶體使用受 GC 時機影響；改用前後差值偵測洩漏（差值 = 0）而非絕對上限 | W1-017 + W1-018 實證 |
| 5. 非同步時序 | 斷言非同步操作尚未完成時的中間狀態 | 斷言位置在觸發事件之後但等待機制之前；結果隨執行速度改變 | 等待最終狀態再斷言；等待機制因框架而異但「等完成再斷言」原則跨語言一致 | W1-024 推導 |
| 6. 亂數輸出 | 斷言由不可控隨機源驅動的特定輸出值 | 斷言依賴具體的隨機生成值（特定 ID、特定排序、特定分組） | 隨機源必須可控；斷言驗證演算法行為（分佈特性、邊界條件），不斷言特定隨機輸出 | W1-024 推導 |
| 7. 測試隔離違反 | 測試依賴其他測試建立的副作用或特定執行順序 | 測試單獨執行通過但全套件執行失敗；測試順序改變影響 pass/fail | 每個測試自建前置條件，teardown 還原所有共享狀態；隔離違反問題跨語言同形 | W1-024 推導 |
| 8. 快照過度覆蓋 | 快照比對整體輸出結構，非業務相關的格式變更觸發 false positive | 修改一個不相關欄位或樣式，整個快照紅燈 | 快照粒度匹配驗證意圖；業務邏輯驗收用欄位/屬性斷言，全結構快照只用於偵測非預期變更 | W1-024 推導 |
| 9. 斷言過度集中 | 單一測試案例驗證多個行為面向，前面的斷言失敗遮蔽後面的 | 一個 test case 驗 10 個以上屬性，或測試名稱難以用單一行為描述 | 一測試案例一行為面向；斷言數量與被測行為的複雜度成比例，不與輸出結構大小成比例 | W1-024 推導 |
不在範圍聲明
此 skill 提供判斷概念，以下內容屬下游層級，不在此 skill 範圍：
| 不在範圍的內容 | 所在層級 |
|---|
具體測試寫法（toBeLessThan、pumpAndSettle、testing.T） | 語言/框架文件 |
| 重構步驟（如何將計時斷言改為功能斷言） | 實作代理人職責 |
| 精度數字規定（numDigits <= 2）、目錄結構規定（tests/perf/） | 專案 rules 層 |
| 效能測試 SLA 門檻設定 | 專案決策層 |
專案 rules 層：.claude/rules/core/test-assertion-design-rules.md（本專案 Chrome Extension/JS/Jest 專屬規則）
專案類型脈絡（按需讀取）
各類型在不同專案中有脈絡差異。讀取對應 reference 取得輕量提示：
| 情境 | 讀取 reference |
|---|
| WEB 類專案（JS/TS + Jest/Vitest/Playwright） | references/web-testing-context.md |
| APP 類專案（Flutter/React Native） | references/app-testing-context.md |
| 後端類專案（Go/Python/Node.js 服務） | references/backend-testing-context.md |
定位說明
此 skill 與同主題層級的正交性（定位依據：三者職責不重疊）：
| 層級 | 職責 |
|---|
test-assertion-design skill（本檔） | 斷言內容設計的判斷概念（驗什麼、設計是否合理），跨語言通用 |
tdd skill | TDD 流程管理（Red/Green/Refactor 階段推進） |
dart-test-async-guardian skill | 非同步資源清理的生命週期防護（清理洩漏，非斷言設計） |
.claude/rules/core/test-assertion-design-rules.md | 本專案（Chrome Extension/JS/Jest）專屬規則，含具體精度數字與目錄規定 |
Last Updated: 2026-05-21
Version: 1.2.0 — 第 2 輪審查：三問「確定性」對應標籤由「環境依賴」改為「確定性失效」（類型 5-6 屬設計族）。1.1.0：F2-F5 修正（W1-027 第 1 輪審查）
