Community程式設計與開發github.com

單元測試

設計、編寫、審查及改善語言無關的單元測試之準則:測試案例、邊界情況、測試替身(模擬、樁、假物件)、不穩定或脆弱的測試、遺漏情境。每當使用者要求新增、修復、審查或擴充測試、為函式加上測試,或回報不穩定或失敗的測試時使用,即使他們沒有明確說出「單元測試」。如果存在語言特定的單元測試技能,請與此技能一同使用。不適用於端對端、效能或基礎設施測試。

單元測試 是什麼?

此技能提供撰寫可靠、易讀且可維護的單元測試之全面準則,重點在於驗證可觀察的行為而非實作細節。它定義了核心原則,如測試行為而非實作、從合約而非程式碼推導預期結果、保持測試隔離與確定性,並提供結構化的工作流程,用於從初始分析到報告的測試開發與審查。此技能涵蓋測試設計、情境檢查清單、測試替身的適當使用(偏好假物件而非模擬,除非互動是合約的一部分)、具體的斷言,以及避免反模式,如測試 getter/setter 或使用 sleep 進行同步。它還包括審查現有測試的準則,並對例如修改產品程式碼僅為使測試通過等事項設定限制。此技能旨在與語言特定的技能搭配使用,並透過詳細的清單提供驗證步驟,以檢查測試敏感度(手動突變測試)、可靠性(重複執行及順序)以及根本原因分析。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lukeweb/ai-coding-agent-skills/tree/HEAD/skills/unit-testing

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

單元測試 是做什麼的?

目的

確保單元測試可靠、易讀、可維護,並驗證可觀察的行為。

這是基礎技能。語言特定技能可以加入框架、命名和工具細節,但不得與本技能的核心原則或限制條件衝突。

範圍

包含在內:

  • 設計測試案例。
  • 撰寫新的單元測試。
  • 改善與審查現有的單元測試。

不包含在內:

  • 端對端測試。
  • 效能測試。
  • 基礎設施測試。

單元測試應在與不受控制的外部系統和副作用隔離的環境中,驗證一個聚焦的行為單元。

單元測試不應依賴即時網路服務、共享資料庫、外部基礎設施或不受控制的時鐘時間。

受控的記憶體內實作、臨時資源和確定性的本機相依項是可接受的,前提是它們有助於在不影響隔離性或可靠性的情況下驗證單元的行為。

如果使用者要求需要即時外部系統的測試,請說明此測試超出本技能範圍,並建議改用整合測試。

依賴全域狀態或單例且沒有測試接縫的程式碼,透過限制條件處理:應回報該問題,而非繞過它(例如透過修補全域變數)。

優先順序

當指示衝突時,依此順序套用:

  1. 明確的使用者指示。
  2. 本技能的核心原則與限制條件。
  3. 現有事業慣例與工具(框架、命名、結構、輔助函式)。
  4. 語言特定技能。
  5. 本技能中的測試設計指引。

事業慣例永遠不得凌駕於核心原則或限制條件之上(例如,驗證每個模擬呼叫的慣例並不能證明測試實作細節是合理的)。

核心原則

測試行為,而非實作

驗證可觀察的合約:回傳值、透過公開 API 可見的狀態變更、錯誤,以及屬於合約一部分的副作用(例如,已發布的事件、已儲存的記錄)。

測試必須在實作被重構而未改變行為時仍然有效。

請勿直接測試私有成員;應透過公開 API 驗證其行為。

從合約而非程式碼推導預期結果

預期行為必須主要從明確的需求、驗收標準和權威文件推導出來。

使用公開 API、方法名稱、簽章和現有測試作為輔助證據,而非作為最終規格。

將當前實作視為實際行為的證據,而非預期行為的來源。

如果實作與既定合約矛盾,請回報差異,而非將不正確的行為編碼到測試中。

如果預期行為不明確:

  • 如果模糊性影響多個測試或重要情境的結果,且使用者可被詢問,請在撰寫這些測試前先詢問。
  • 否則,選擇最保守的解釋,使用簡短註解標記測試說明假設,並在報告中列出該假設。

如果不存在合約(舊有程式碼)且使用者明確要求在重構前鎖定當前行為,請撰寫特徵化測試:將其命名或標記為此類,並在報告中說明它們記錄的是實際行為,而非經過驗證的行為。

保持測試隔離

每個測試必須獨立於執行順序和共享的可變狀態。

每個測試應建立並清理其自身所需的狀態和資源。

測試不得依賴其他測試的副作用。

保持測試確定性

測試必須產生可預測且可重現的結果,無論執行順序、機器或環境為何。

控制非確定性的來源:

  • 當前時間與日期。
  • 隨機數產生器。
  • UUID 和 ID 產生。
  • 外部服務。
  • 環境相關配置。
  • 映射和集合的迭代順序。
  • 時區與地區設定。
  • 浮點數比較。
  • 執行緒或任務排程。

偏好依賴注入,以使非確定性依賴項可控。

僅當產生器被注入到單元中,且測試斷言不依賴特定生成值的行為時,才可接受固定的種子。

對於確定性、快速、程序內協作者,在不影響測試隔離或可靠性的前提下,優先使用真實實作。

當依賴項引入不受控制的副作用、外部狀態、非確定性或不必要的複雜性時,應使用適當的測試替身。

工作流程

在撰寫或改善單元測試時:

  1. 如果存在語言特定的單元測試技能,請在開始前閱讀它。
  2. 閱讀被測單元、其公開 API 和文件,以識別預期的合約。
  3. 審查現有測試:框架、命名、結構、慣例和可用的輔助函式。
  4. 執行相關的現有測試以建立基準線。記錄任何既存的失敗;不要將其歸因於你的變更,也不要修復它們,除非被要求。
  5. 識別被測單元的職責和依賴項。
  6. 決定哪些依賴項應保持真實,哪些需要測試替身。
  7. 識別相關情境,並優先考慮那些可能實際發生故障的情境。
  8. 遵循事業慣例實作測試。
  9. 執行下面的驗證步驟。
  10. 回報結果、假設和未解決的問題。

當被要求審查現有測試時,請遵循「審查現有測試」。

測試設計

情境檢查清單

在相關時考慮以下情境:

  • 正常執行路徑。
  • 邊界條件(空值、零值、單一值、最大值、差一錯誤的情況)。
  • 無效輸入。
  • 錯誤處理與失敗路徑。
  • 重要的狀態轉換。
  • 有意義的條件組合。
  • 必須始終成立的重要不變量。當專案工具支援時,基於屬性的測試非常適合不變量。

請勿僅為了提高程式碼覆蓋率數字而添加測試。

對於錯誤修正,首先撰寫一個能重現該錯誤的測試,並確認它因正確原因而失敗。如果修正屬於範圍內,請確認測試之後通過。如果未獲授權修改產品程式碼,請回報重現器而非留下未宣告的失敗測試,並詢問是否保留它。

測試替身

審慎使用測試替身,並為情境選擇適當的類型:

  • 樁物件為依賴項呼叫提供受控回應。
  • 假物件提供簡化的運作實作。
  • 模擬驗證與依賴項的預期互動。
  • 間諜記錄互動以供後續驗證。

當依賴項具有可由輕量級實作表示的意義行為時,偏好使用假物件(簡單的記憶體內實作)而非模擬。

僅當互動本身是預期合約的一部分時才斷言互動,例如必須發送通知或呼叫必須不發生。

除非呼叫次數或順序明確屬於預期行為的一部分,否則不要斷言它們。

當在邊界處存在現有包裝器或假物件時,請勿模擬不屬於你的類型。在產品程式碼中建立新的包裝器需要使用者核准(請參閱限制條件)。

切勿模擬被測單元。

斷言

斷言具體的結果,而不僅僅是執行完成且沒有錯誤,或結果不為 null。

斷言應驗證可觀察的行為,並區分正確與不正確的結果。

對於錯誤,請斷言相關的錯誤合約:類型、類別、程式碼或其他穩定的錯誤屬性。

僅當訊息內容是預期行為的一部分,或提供穩定、有意義的保證時,才斷言訊息內容。

避免那些即使行為錯誤仍能通過的斷言(例如,僅檢查結果的長度)。

除非記錄是預期合約的一部分,否則不要斷言記錄輸出。

結構與命名

每個測試應專注於一個邏輯情境或行為。

當多個斷言驗證同一行為的不同面向時,是可以接受的。

按情境和預期結果命名測試,例如 rejects_expired_token,而非 test1 或 testValidate。命名風格僅供說明;請遵循事業慣例。

當有助於提高可讀性時,使用「安排 / 執行 / 斷言」模式。

保持預期值為字面值且明確。切勿在測試中計算預期值,尤其是透過重複使用實作的邏輯。

迴圈僅在迭代明確的案例表格時,或在框架的參數化或基於屬性的機制內部時,才是可接受的。如果測試主體根據案例欄位(例如,錯誤 vs. 成功)分支,且分支增長,則應拆分為單獨的測試或表格。

使測試資料不言自明。對於意義不明顯的值,請命名或加上註解。

使用合成的測試資料。切勿使用真實的憑證、個人資料或產品傾印。

當多個案例共享相同結構時,使用專案的參數化機制;否則,保持案例分開。

在測試中,偏好少量重複勝過隱藏測試意圖的抽象。

在能改善清晰度和一致性的情況下,重複使用現有事業輔助函式。

僅對非顯而易見的行為或測試決策添加註解。

未在上方涵蓋的反模式

  • 測試第三方或框架程式碼,而非被測單元自身的行為。
  • 測試沒有邏輯的瑣碎 getter 或 setter。
  • 使用 sleep 來同步並行程式碼,而非控制時間或使用明確的同步機制。

審查現有測試

當被要求審查而非撰寫測試時:

  1. 建立被測單元的合約(請參閱核心原則)。
  2. 根據核心原則和測試設計檢查每個測試。透過在可能的情況下執行測試(例如,針對疑似不穩定性進行重複執行)來確認可疑問題,而非猜測。
  3. 首先依優先順序回報發現:
    • 高:測試通過時行為已損壞、編碼了錯誤、不穩定或依賴順序。
    • 中:與實作耦合、遺漏重要情境。
    • 低:命名、可讀性、重複。
  4. 分別列出遺漏的情境。
  5. 除非使用者直接要求修復,否則在回報發現後才修改測試。

限制條件

  • 請勿僅為使測試通過而修改產品程式碼。如果被測單元難以測試(例如,沒有時間、隨機性或依賴項的接縫),請回報問題並提出最小的必要變更。僅在獲得使用者明確核准後才套用它。

  • 現有測試可以被重構或改善,但絕不能最終驗證得比先前更少。請勿刪除、停用或削弱測試以獲得通過的套件。

  • 除非需求已合法變更,否則請勿更改現有斷言的預期值;請在報告中解釋此類變更。允許使斷言更嚴格或更精確。

  • 當現有事業工具足夠時,請勿引入新的測試框架或依賴項。

驗證

  1. 使用專案自己的測試命令執行新的或修改過的測試。

  2. 執行周圍套件或模組的測試,然後執行完整測試套件,除非它太慢。如果跳過完整套件,請在報告中說明。

  3. 檢查測試敏感度。

    重要的測試是那些涵蓋條件邏輯、錯誤路徑和邊界值的測試;排除瑣碎的映射或直通測試。

    對於每個重要的測試,至少識別一個產品行為中的實際變更,該變更會使其失敗(條件翻轉、邊界偏移、移除錯誤處理)。如果無法做到,請加強斷言。

    如果專案中已配置突變測試工具,請在變更的程式碼上執行它。

    僅當所觸及的檔案沒有未提交的變更(或工作在 disposable copy 或 worktree 中完成)且原始檔案之後被完全還原時,才允許對產品程式碼進行手動突變。否則跳過它,並在報告中說明。切勿覆蓋或還原與此無關的使用者變更。

  4. 檢查可靠性。

    驗證測試在重複執行以及隨機或反向順序下是否通過(當工具支援時)。

    檢查是否有遺留的狀態、資源或副作用。

  5. 調查失敗。

    識別根本原因,並將每個失敗分類為測試缺陷或產品缺陷。

    切勿僅為使測試通過而修改斷言。

    回報未解決的失敗及其可能原因。

報告

提供一個包含以下內容的簡潔摘要:

  • 建立或修改的測試。
  • 執行的命令及其結果。
  • 觀察到的既存失敗(非由你的變更引起)。
  • 發現的可疑產品缺陷。
  • 關於預期行為所做的假設。
  • 跳過或無法執行的驗證步驟及其原因。除非測試已被執行,否則切勿將測試報告為通過。
  • 未解決的失敗或限制。

相關技能