platform-apex-test-run

platform-apex-test-run：Salesforce 測試執行與覆蓋率分析

當使用者需要 Apex 測試執行與失敗分析時使用此技能：執行測試、檢查覆蓋率、解讀失敗原因、改善覆蓋率，以及管理 Salesforce 程式碼的結構化測試修復循環。

此技能負責的任務

當工作涉及以下項目時，使用 platform-apex-test-run：

• sf apex run test 工作流程
• Apex 單元測試失敗
• 程式碼覆蓋率分析
• 找出未覆蓋的行與遺漏的測試情境
• Apex 程式碼的結構化測試修復循環

當使用者正在進行以下工作時，請委派給其他技能：

• 撰寫或重構正式 Apex 程式碼 → platform-apex-generate 技能
• 測試 Agentforce 代理 → agentforce-test 技能
• 使用 Jest 測試 LWC → experience-lwc-generate

---

需先收集的必要背景資訊

詢問或推斷：

• 目標組織別名
• 期望的測試範圍：單一類別、特定方法、測試套件或本地測試
• 覆蓋率門檻期望值
• 使用者只需要診斷，還是需要測試修復循環
• 是否已有相關的測試資料工廠

---

建議工作流程

1. 探索測試範圍

找出：

• 現有的測試類別
• 目標正式類別
• 測試資料工廠 / 設定輔助程式

2. 先執行最小有用的測試集

除錯失敗時先從窄範圍開始；待修復穩定後再擴大範圍。

3. 分析結果

專注於：

• 失敗的方法
• 例外類型與堆疊追蹤
• 未覆蓋的行 / 覆蓋率薄弱區域
• 失敗是否源於不良測試資料、脆弱的斷言，或損壞的正式邏輯

4. 執行結構化修復循環

當問題出在程式碼或測試品質時：

• 必要時將程式碼修復委派給 platform-apex-generate 技能
• 新增或改善測試
• 在進行更廣泛的回歸測試前，先重新執行聚焦的測試

5. 有目的地改善覆蓋率

涵蓋：

• 正向路徑
• 負向 / 例外路徑
• 大量路徑（適當時使用 251 筆以上記錄）
• 相關的呼叫或非同步路徑

---

高訊號規則

規則	理由
預設使用 SeeAllData=false	確保測試隔離；避免依賴組織特定資料
每個測試都必須斷言有意義的結果	沒有斷言的測試無法證明任何事，並帶來虛假信心
使用 251 筆以上記錄測試大量行為	觸發以 200 筆為批次的處理流程；251 筆記錄跨越邊界
當有助於提升清晰度時，使用工廠 / @TestSetup	在單一位置建立一致的資料；測試方法之間會回滾
將 Test.startTest() 與 Test.stopTest() 配對使用於非同步測試	確保非同步操作（佇列、未來方法）在斷言前完成
不要在測試中隱藏不穩定的組織依賴	避免因組織狀態導致間歇性失敗

---

常見陷阱

問題	解決方式
測試在本機通過但在 CI 組織失敗	檢查是否使用了 SeeAllData=true 或未宣告的組織特定記錄依賴
重構後覆蓋率意外下降	先執行聚焦的類別層級測試，再擴大至 RunLocalTests 以確認
呼叫測試中出現「未提交的工作待處理」錯誤	在相同測試情境中，DML 與 HTTP 呼叫不能混合使用，需用 Test.startTest() 包覆
測試中 Mock 未生效	確保在執行呼叫的程式碼之前已呼叫 Test.setMock()
測試方法中缺少 @TestSetup 資料	@TestSetup 資料會為每個測試方法提交——請重新查詢；不要儲存在靜態變數中

---

輸出格式

完成時，依此順序報告：

1. 執行了哪些測試
2. 通過/失敗摘要
3. 覆蓋率結果
4. 根本原因發現
5. 修復或下次執行建議

建議格式：

測試執行：<範圍>
組織：<別名>
結果：<通過 / 部分通過 / 失敗>
覆蓋率：<百分比 / 關鍵類別>
問題：<最高訊號的失敗>
下一步：<修復類別、新增測試、重新執行範圍或擴大回歸>

---

跨技能整合

需求	委派給	原因
修復正式程式碼或撰寫測試類別	platform-apex-generate 技能	程式碼產生與修復
建立大量 / 邊界案例測試資料	platform-data-manage	真實的測試資料集
將更新後的測試部署至組織	platform-metadata-deploy	部署工作流程
檢查詳細的執行時期日誌	platform-apex-logs-debug	更深入的失敗分析

---

參考檔案索引

檔案	何時閱讀
references/cli-commands.md	所有 sf apex run test 命令旗標、輸出格式、非同步執行與覆蓋率命令
references/test-patterns.md	測試類別範本——基本、大量（251+）、模擬呼叫與資料工廠模式
references/testing-best-practices.md	核心測試原則——AAA 模式、命名慣例、大量、負向與模擬策略
references/test-fix-loop.md	代理測試修復循環實作與失敗分析決策樹
references/mocking-patterns.md	HttpCalloutMock、DML 模擬、StubProvider 與選擇器模擬模式
references/performance-optimization.md	減少測試執行時間的技巧——DML 模擬、SOQL 模擬、迴圈最佳化
assets/basic-test.cls	範本：標準測試類別，包含 @TestSetup、正向 / 負向 / 大量 / 邊界案例方法
assets/bulk-test.cls	範本：大量測試，使用 251 筆以上記錄，跨越 200 筆記錄的觸發批次邊界
assets/mock-callout-test.cls	範本：使用 HttpCalloutMock 的 HTTP 呼叫模擬
assets/test-data-factory.cls	範本：可重複使用的 TestDataFactory，包含建立與插入輔助方法
assets/dml-mock.cls	範本：IDML 介面 + DMLMock 實作，用於無資料庫的單元測試
assets/stub-provider-example.cls	範本：基於 StubProvider 的依賴注入樁
scripts/parse-test-results.py	後置工具鉤子——解析 sf apex run test 的 JSON 輸出，並格式化失敗資訊供自動修復循環使用

---

評分指南

分數	意義
108+	強大的正式等級測試信心
96–107	良好的測試套件，有輕微缺口
84–95	可接受，但需加強覆蓋率 / 斷言
< 84	低於標準；在依賴之前請先修正