dx-devops-test-suite-run

运行 DevOps Center 测试套件

触发 DevOps Center 测试套件执行，并持续监控直至完成。运行和轮询是同一操作的两个部分——除非已获得或有人提供 runId，否则切勿轮询。

API 版本： 所有 DevOps 测试系统调用均针对 Salesforce API v67.0（最低要求）。

重要： 所有 DevOps Center 数据都存储在 Salesforce 组织中，而非本地仓库中。始终使用 sf data query 或 sf api request rest 查询组织。

---

前提条件

运行 references/prerequisite-checks.md 中的前提检查——前提条件 1–4 以及前提条件 5（阶段），因为此技能针对特定阶段运行。你需要已确认的 doce-org-alias、pipelineId 和 stageId。

所需输入

输入	获取方式
pipelineId	前提条件 4（选择管道）
stageId	前提条件 5（确认管道阶段）
event	与用户确认：Pre-Promote、Post-Promote 或 Review
testSuiteIds	从选择或推荐结果中确认套件 ID
doce-org-alias	前提条件 1

---

步骤 1 — 触发执行

确认关卡

此调用会更改组织状态——未经用户明确确认，不要继续。 调用 API 前，向用户展示：

“我即将使用以下配置运行测试：

• 管道：<pipelineName>
• 阶段：<stageName>
• 事件：<event>
• 套件：<suiteName(s)>
• 组织：<doce-org-alias>

要继续吗？”

用户确认后才能调用 API。

API 调用

sf api request rest \
  "/services/data/v67.0/connect/devopstesting/pipeline/<pipelineId>/stage/execute" \
  --method POST \
  --body '{
    "stageId": "<stageId>",
    "event": "<event>",
    "testSuiteIds": ["<suiteId1>", "<suiteId2>"]
  }' \
  --target-org <doce-org-alias>

字段	类型	说明
stageId	string	要在其上执行测试的管道阶段 ID
event	string	Pre-Promote、Post-Promote 或 Review
testSuiteIds	string[]	一个或多个要执行的测试套件 ID

成功时

从响应中提取 runId（执行 ID）。告知用户：

“正在 <doce-org-alias> 中运行测试。结果准备就绪后，我会通知你。”

然后立即携带 runId 进入步骤 2（轮询）。

出错时

参见 references/error-handling.md。如果组织拒绝执行（例如 environmentId: null，或 classIdList is null or empty — no tests to execute），请读取实际错误，用通俗语言说明根本原因和所需修复，然后妥善结束。不要循环重试，也不要伪造 runId 或结果。

---

步骤 2 — 轮询直至完成

需要确认： 不需要——轮询会自动进行，且为只读操作。

按服务提供方适用的时间间隔，通过 runId 轮询执行记录。完整的轮询间隔、超时行为和轮询查询见 references/polling-configuration.md。

轮询循环摘要（runId 是 DevopsTestSuiteExecution 的 ID——轮询该对象，而非 DevopsTestExecution）：

• 每个间隔按 runId 查询 DevopsTestSuiteExecution，获取 Status, Coverage, SuccessCount, FailureCount, QualityGateStatus。
• InProgress → 等待后再次轮询。
• Passed / Failed → 直接展示 Coverage、SuccessCount、FailureCount 和 QualityGateStatus（不要输出原始 JSON）。如果 FailureCount > 0，获取子级 DevopsTestExecution 失败记录，并交由 dx-devops-test-failures-analyze 处理。
• Error → 运行本身出错（并非测试失败）；用通俗语言展示 ResultDetails/Message，并提出重试或跳过。
• 超时 → 展示 runId，不要自动重试，等待用户指示。

---

重新触发模式（重新运行质量关卡）

当推广因关卡失败而受阻，且覆盖率缺口已解决时使用。所有前提条件、关卡和重新触发 API 调用均见 references/retrigger-mode.md。 关键规则：除非最新的 Coverage 达到或超过 DevopsQualityGateRule 阈值，否则不要重新触发。重新触发返回新的 runId 后，将其交给步骤 2（轮询）。

相关技能

• dx-devops-test-failures-analyze — 完成后接收失败负载；也可以创建修复工作项。
• dx-devops-test-suite-assignments-configure — 推荐要运行的套件，或在套件尚未关联时将其分配给阶段。
• dx-devops-test-pipeline-configure — 配置新的质量门禁或阈值（此技能仅重新运行现有门禁）。