swift-testing-expert

Swift Testing

概述

使用此技能來撰寫、審查、遷移及除錯採用現代 Swift Testing API 的 Swift 測試。優先考慮可讀性高的測試、穩健的平行執行、清晰的診斷資訊，以及必要時從 XCTest 逐步遷移。

代理人行為合約（請遵守以下規則）

1. 對於 Swift 單元測試與整合測試，優先使用 Swift Testing，但 UI 自動化（XCUIApplication）、效能指標（XCTMetric）以及僅限 Objective-C 的測試程式碼則保留使用 XCTest。
2. 將 #expect 視為預設的斷言，而當後續程式碼依賴某個必要值時，則使用 #require。
3. 預設提供平行安全的指引。如果測試未隔離，應先建議修正共享狀態，再考慮使用 .serialized。
4. 優先使用特徵來表達行為與中繼資料（.enabled、.disabled、.timeLimit、.bug、標籤），而非依賴命名慣例或臨時註解。
5. 當多個測試共用邏輯且僅輸入值不同時，建議使用參數化測試。
6. 針對作業系統版本限制的行為，在測試函數上使用 @available，而非在測試主體內使用執行階段的 #available 檢查；切勿在套件類型上標註 @available。
7. 遷移建議應逐步進行：先轉換斷言，再組織套件，最後引入參數化與特徵。
8. 僅在測試目標中匯入 Testing，絕對不要在應用程式/函式庫/二進位目標中匯入。

前 60 秒（分流範本）

• 釐清目標：新測試、遷移、不穩定的失敗、效能、CI 過濾，或非同步等待。
• 收集最少的事實：
  • Xcode/Swift 版本與平台目標
  • 測試目前使用 XCTest、Swift Testing 或兩者並用
  • 失敗是確定性還是偶發性
  • 測試是否存取共享資源（資料庫、檔案、網路、全域狀態）
• 快速分流：
  • 重複的測試 -> 參數化測試
  • 雜訊多或偶發性失敗 -> 已知問題處理與測試隔離
  • 遷移問題 -> XCTest 對應與共存策略
  • 非同步回呼複雜度 -> continuation/await 模式

路由地圖（快速找到正確的參考文件）

• 測試建構區塊與套件組織 -> references/fundamentals.md
• #expect、#require 與拋出期望 -> references/expectations.md
• 特徵、標籤與 Xcode 測試計畫過濾 -> references/traits-and-tags.md
• 參數化測試設計與組合 -> references/parameterized-testing.md
• 預設平行執行、.serialized、隔離策略 -> references/parallelization-and-isolation.md
• 測試速度、確定性與防止不穩定 -> references/performance-and-best-practices.md
• 非同步等待與回呼橋接 -> references/async-testing-and-waiting.md
• XCTest 共存與遷移工作流程 -> references/migration-from-xctest.md
• 測試導覽器/報告工作流程與診斷 -> references/xcode-workflows.md
• 索引與快速導覽 -> references/_index.md

常見陷阱 -> 下一步最佳行動

• 重複的 testFooCaseA/testFooCaseB/... 方法 -> 取代為一個參數化的 @Test(arguments:)。
• 隱藏在後續斷言中的失敗可選前提 -> 使用 try #require(...) 然後對解包後的值進行斷言。
• 共享資料庫上不穩定的整合測試 -> 隔離相依性或使用記憶體儲存庫；僅將 .serialized 作為過渡步驟。
• 被停用且默默腐化的測試 -> 優先使用 withKnownIssue 處理暫時已知的失敗，以保留訊號。
• 複雜型別的不明確失敗值 -> 讓型別符合 CustomTestStringConvertible 以獲得聚焦的測試診斷。
• 依名稱包含/排除測試計畫 -> 改用標籤與基於標籤的過濾器。

驗證檢查清單

• 確認每個測試都有單一明確的行為，並在必要時提供具表達力的顯示名稱。
• 確認前提使用 #require，以便在失敗時停止測試。
• 確認重複的邏輯已參數化而非複製貼上。
• 確認測試是平行安全的，或是有意序列化並附上理由。
• 確認非同步程式碼已 await，且回呼 API 已安全橋接。
• 確認遷移時，不支援的 XCTest 專用情境仍保留在 XCTest 上。

參考文件

• references/_index.md
• references/fundamentals.md
• references/expectations.md
• references/traits-and-tags.md
• references/parameterized-testing.md
• references/parallelization-and-isolation.md
• references/performance-and-best-practices.md
• references/async-testing-and-waiting.md
• references/migration-from-xctest.md
• references/xcode-workflows.md