running-apex-tests

running-apex-tests：Salesforce 测试执行与覆盖率分析

当用户需要 Apex 测试执行与失败分析 时使用此技能：运行测试、检查覆盖率、解读失败、提升覆盖率，以及为 Salesforce 代码管理有条理的测试修复循环。

此技能负责的任务

当工作涉及以下内容时，使用 running-apex-tests：

• sf apex run test 工作流
• Apex 单元测试失败
• 代码覆盖率分析
• 找出未覆盖的代码行和缺失的测试场景
• 为 Apex 代码进行结构化测试修复循环

以下情况请委派给其他技能：

• 编写或重构生产环境 Apex 代码 → generating-apex 技能
• 测试 Agentforce Agent → testing-agentforce 技能
• 使用 Jest 测试 LWC → generating-lwc-components

---

首先收集所需背景信息

询问或推断：

• 目标组织别名
• 期望的测试范围：单个类、特定方法、测试套件或本地测试
• 覆盖率阈值要求
• 用户只需要诊断，还是需要进行测试修复循环
• 是否已有相关的测试数据工厂

---

推荐工作流

1. 确定测试范围

找出：

• 现有测试类
• 目标生产类
• 测试数据工厂／设置辅助工具

2. 先运行最小的有效测试集

调试失败时，先从小范围开始；只有在修复稳定后才扩大范围。

3. 分析结果

重点关注：

• 失败的方法
• 异常类型和堆栈跟踪
• 未覆盖的代码行／覆盖率薄弱区域
• 失败是否表明测试数据有误、断言不稳定或生产逻辑存在问题

4. 进行有条理的修复循环

如果问题与代码或测试质量有关：

• 必要时将代码修复委派给 generating-apex 技能
• 添加或改进测试
• 在扩大回归测试范围前，重新运行针对性测试

5. 有针对性地提升覆盖率

覆盖以下情况：

• 正向路径
• 负向／异常路径
• 批量路径（适用时测试 251 条以上记录）
• 相关的 callout 或异步路径

---

重要规则

规则	原因
默认使用 SeeAllData=false	确保测试隔离；避免依赖特定组织的数据
每项测试都必须断言有意义的结果	没有断言的测试无法证明任何结论，只会带来虚假的信心
使用 251 条以上记录测试批量行为	触发每批处理 200 条记录的流程；251 条记录可跨越批次边界
在能提高清晰度时使用工厂／@TestSetup	在同一处一致地创建数据；每个测试方法结束后都会回滚
对异步操作配对使用 Test.startTest() 和 Test.stopTest()	确保在断言前完成异步操作（queueable、future）
不要在测试中隐藏不稳定的组织依赖	避免出现与组织状态相关的间歇性失败

---

注意事项

问题	解决方案
测试在本地通过，但在 CI 组织中失败	检查是否使用了 SeeAllData=true，或是否存在未声明的、对组织特定记录的依赖
重构后覆盖率意外下降	先运行针对特定类的测试，再扩大到 RunLocalTests 以确认
callout 测试中出现 "Uncommitted work pending" 错误	如果没有用 Test.startTest() 包裹，同一测试上下文中不能混用 DML 和 HTTP callout
Mock 在测试中未生效	确保在调用 callout 的代码运行之前调用 Test.setMock()
测试方法中缺少 @TestSetup 数据	@TestSetup 数据会按每个测试方法提交——请重新查询；不要存储在静态变量中

---

输出格式

完成后，按以下顺序报告：

1. 运行了哪些测试
2. 通过／失败摘要
3. 覆盖率结果
4. 根因分析
5. 修复或下次运行建议

建议格式：

Test run: <scope>
Org: <alias>
Result: <passed / partial / failed>
Coverage: <percent / key classes>
Issues: <highest-signal failures>
Next step: <fix class, add test, rerun scope, or widen regression>

---

跨技能集成

需求	委派给	原因
修复生产代码或编写测试类	generating-apex 技能	代码生成与修复
创建批量 / 边界情况测试数据	handling-sf-data	逼真的测试数据集
将更新后的测试部署到组织	deploying-metadata	部署工作流
检查详细的运行时日志	debugging-apex-logs	深入分析故障

---

参考文件索引

文件	何时阅读
references/cli-commands.md	所有 sf apex run test 命令标志、输出格式、异步执行和覆盖率命令
references/test-patterns.md	测试类模板——基础、批量（251+）、模拟调用和数据工厂模式
references/testing-best-practices.md	核心测试原则——AAA 模式、命名约定、批量、负向测试和模拟策略
references/test-fix-loop.md	Agent 式测试修复循环实现和故障分析决策树
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 的依赖注入存根
hooks/scripts/parse-test-results.py	工具后置钩子——解析 sf apex run test JSON 输出，并为自动修复循环整理失败信息

---

评分指南

分数	含义
108+	对生产级测试有较强信心
96–107	测试套件良好，仅有少量不足
84–95	可以接受，但应加强覆盖率 / 断言
< 84	低于标准；依赖前应进行修订