菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
broken-link 偵測工具。掃描 .claude/ 目錄所有 Markdown 文件中的路徑引用，偵測失效連結。Use for: (1) 一次性掃描所有 broken links, (2) 搭配 /loop 定期監控, (3) 修改規則/方法論/代理人文件後驗證路徑完整性。Use when: user runs /broken-link-check, 或搭配 /loop 定期執行, 或發現 broken link 錯誤後。
Dart/Flutter copyWith 收窄判準與 entity 不變式設計。Use when designing or reviewing copyWith, entity classes, value objects, freezed models, domain invariants, or state transition methods (markAsX/completeY).
全量掃描硬編碼中文字串並生成 i18n 修正建議。檢測所有層（Model/Service/Domain/UI）中文硬編碼，生成 ARB 鍵值建議，支援批量替換工作流程。Use for: (1) 檢查專案全部硬編碼中文（不只 UI 層）, (2) 進行大規模 i18n 修復, (3) 生成 ARB 鍵值建議, (4) i18n 技術債務評估
Riverpod Provider 架構設計規範 - 確保正確的依賴注入、介面隔離和測試可行性。Use for: (1) 設計新的 ViewModel/Notifier 類別, (2) 審查 Provider 依賴注入是否正確, (3) 測試中配置 ProviderScope.overrides, (4) 發現 ref.read/watch 使用錯誤時。Use when: 程式碼涉及 Riverpod Provider、Notifier、ViewModel 設計或出現 ref 操作問題時。
Performs security review for Flutter/Dart code. Use when implementing authentication, handling user input, working with API keys or secrets, managing permissions, storing sensitive data locally, or integrating third-party APIs. Provides Flutter-specific security checklists and patterns.
Style Guardian - Unified Design System Enforcement Tool. Use for: (1) Preventing hardcoded styles (colors, spacing, typography), (2) Preventing hardcoded text (i18n violations), (3) Guiding unified configuration usage, (4) Detecting and fixing style violations
| 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. |
斷言設計判斷概念框架。職責：識別「此斷言設計是否合理」，提供跨語言判斷標準。不提供測試寫法或重構步驟。
設計或審查斷言時，依序回答三個問題。任一問題答「否」即進入對應的類型判斷：
| 問題 | 判斷標準 | 「否」時對應類型 |
|---|---|---|
| 確定性 | 同一程式碼在任何執行環境下，pass/fail 結果一致？ | 類型 1–6（確定性失效） |
| 聚焦性 | 此測試案例只驗證一個行為面向？ | 類型 8–9（設計問題） |
| 隔離性 | 此測試不依賴其他測試建立的狀態或執行順序？ | 類型 7（隔離違反） |
以下 4 種確定性斷言類型符合三問標準，可直接放功能測試套件：
| 確定性類型 | 說明 |
|---|---|
| 功能正確性 | 輸出值直接比對固定預期值 |
| 邏輯不變式 | 驗證數學/邏輯關係（a < b、rate < 1.0），兩側均非環境依賴值 |
| 結構驗證 | 驗證欄位存在、型別正確、陣列長度 |
| 資源清理 | 驗證洩漏偵測差值（前後 count 差值 = 0），用差值而非絕對值 |
9 類型問題依問題本質分為兩族（partition，互斥）：
此分族與斷言品質三問為不同視角：三問是快速分流入口（任一否即識別問題族群）；分族是依問題本質歸類（幫助理解根因、選擇對應設計原則）。
| 類型 | 問題本質 | 識別信號 | 設計原則 | 來源 |
|---|---|---|---|---|
| 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 輪審查）
