Back to Details

dx-devops-test-suite-run

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Run a DevOps Center Test Suite

运行DevOps Center测试套件

Triggers a DevOps Center test suite execution and watches it to completion. Running and polling are two halves of one operation — never poll without first having (or being handed) a 
runId
.
API version: All DevOps testing system calls target Salesforce API v67.0 (minimum required).
Important: All DevOps Center data lives in the Salesforce org — NOT the local repo. Always query the org with 
sf data query
or 
sf api request rest
.
触发DevOps Center测试套件执行并监控直至完成。运行和轮询是同一操作的两个部分——绝不要在未获取（或未被提供）
runId
的情况下进行轮询。
**API版本：**所有DevOps测试系统调用均针对Salesforce API v67.0（最低要求版本）。
**重要提示：**所有DevOps Center数据均存储在Salesforce组织中——而非本地仓库。请始终使用
sf data query
或
sf api request rest
查询组织数据。

Prerequisites

前提条件

Run the prerequisite checks in 
references/prerequisite-checks.md
— Prerequisites 1–4 and Prerequisite 5 (stage), since this skill operates on a specific stage. You need the confirmed 
doce-org-alias
, 
pipelineId
, and 
stageId
.
运行
references/prerequisite-checks.md
中的前提条件检查——前提条件1–4 以及前提条件5（阶段），因为此技能针对特定阶段运行。您需要已确认的
doce-org-alias
、
pipelineId
和
stageId
。

Inputs required

所需输入

InputHow to obtain
pipelineId
Prerequisite 4 (pipeline selection)
stageId
Prerequisite 5 (pipeline stage confirmation)
event
Confirm with user: 
Pre-Promote
, 
Post-Promote
, or 
Review
testSuiteIds
Confirmed suite IDs from selection or recommendation
doce-org-alias
Prerequisite 1
输入项获取方式
pipelineId
前提条件4（流水线选择）
stageId
前提条件5（流水线阶段确认）
event
与用户确认：
Pre-Promote
、
Post-Promote
或
Review
testSuiteIds
从选择或推荐中获取已确认的套件ID
doce-org-alias
前提条件1

Step 1 — Trigger execution

步骤1 — 触发执行

Confirmation gate

确认环节

This call mutates org state — do not proceed without explicit user confirmation. Before calling the API, show:
"I'm about to run tests with the following configuration:
  • Pipeline: 
    <pipelineName>
  • Stage: 
    <stageName>
  • Event: 
    <event>
  • Suite(s): 
    <suiteName(s)>
  • Org: 
    <doce-org-alias>
Shall I proceed?"
Do not make the API call until the user confirms.
**此调用会修改组织状态——未获得用户明确确认请勿继续。**调用API前，请展示以下内容：
"我即将按以下配置运行测试：
  • 流水线：
    <pipelineName>
  • 阶段：
    <stageName>
  • 事件：
    <event>
  • 测试套件：
    <suiteName(s)>
  • 组织：
    <doce-org-alias>
是否继续？"
获得用户确认后再进行API调用。

API call

API调用

bash
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>
FieldTypeDescription
stageId
stringThe ID of the pipeline stage to execute tests on
event
string
Pre-Promote
, 
Post-Promote
, or 
Review
testSuiteIds
string[]One or more test suite IDs to execute
bash
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
字符串要执行测试的流水线阶段ID
event
字符串
Pre-Promote
、
Post-Promote
或
Review
testSuiteIds
字符串数组要执行的一个或多个测试套件ID

On success

执行成功

Extract the 
runId
(execution ID) from the response. Inform the user:
"Tests are running in 
<doce-org-alias>
. I'll update you when results are ready."
Then proceed immediately to Step 2 (polling) with the 
runId
.
从响应中提取
runId
（执行ID）。告知用户：
"测试正在
<doce-org-alias>
中运行。结果就绪后我会通知您。"
随后立即使用
runId
进入步骤2（轮询）。

On error

执行失败

See 
references/error-handling.md
. If the org rejects execution (e.g. 
environmentId: null
, or 
classIdList is null or empty — no tests to execute
), read the actual error, explain the root cause and required fix in plain language, and finish cleanly. Do not retry in a loop and do not fabricate a 
runId
or results.
请查看
references/error-handling.md
。如果组织拒绝执行（例如
environmentId: null
，或
classIdList is null or empty — no tests to execute
），请读取实际错误信息，用通俗易懂的语言解释根本原因和所需修复措施，然后干净地结束流程。请勿循环重试，也不要伪造
runId
或测试结果。

Step 2 — Poll until completion

步骤2 — 轮询直至完成

Confirmation required: No — polling is automatic and read-only.
Poll the execution record by 
runId
at the provider-appropriate interval. Full intervals, timeout behavior, and the poll query are in 
references/polling-configuration.md
.
Summary of the loop (the 
runId
is a 
DevopsTestSuiteExecution
Id — poll that object, not 
DevopsTestExecution
):
  • Query 
    DevopsTestSuiteExecution
    by 
    runId
    each interval for 
    Status, Coverage, SuccessCount, FailureCount, QualityGateStatus
    .
  • InProgress
    → wait and poll again.
  • Passed
    / 
    Failed
    → surface 
    Coverage
    , 
    SuccessCount
    , 
    FailureCount
    , and 
    QualityGateStatus
    inline (no raw JSON). If 
    FailureCount > 0
    , fetch the child 
    DevopsTestExecution
    failure rows and hand off to 
    dx-devops-test-failures-analyze
    .
  • Error
    → the run itself errored (not test failures); surface 
    ResultDetails
    /
    Message
    in plain language and offer retry or skip.
  • Timeout → surface the 
    runId
    , do NOT auto-retry, wait for user instruction.
**是否需要确认：**否——轮询是自动且只读的。
按供应商指定的间隔通过
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
    ，请勿自动重试，等待用户指令。

Retrigger mode (re-running a quality gate)

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

Use when a promotion was blocked by a gate failure and the coverage gap has since been addressed. All preconditions, gate, and the retrigger API call are in 
references/retrigger-mode.md
. Key rule: do not retrigger unless the latest 
Coverage
meets or exceeds the 
DevopsQualityGateRule
threshold. After the retrigger returns a new 
runId
, hand it to Step 2 (polling).
当推广因质量门失败而被阻止，且覆盖率缺口已得到解决时使用此模式。**所有前置条件、确认环节和重新触发API调用请参见
references/retrigger-mode.md
。**核心规则：仅当最新的
Coverage
达到或超过
DevopsQualityGateRule
阈值时，才可重新触发。重新触发返回新的
runId
后，将其移交至步骤2（轮询）。

Related skills

相关技能

  • dx-devops-test-failures-analyze
     — receives the failure payload on completion; can also create a fix work item.
  • dx-devops-test-suite-assignments-configure
     — recommend which suites to run, or assign a suite to the stage if it isn't linked yet.
  • dx-devops-test-pipeline-configure
     — configure a new quality gate or threshold (this skill only re-runs existing gates).
  • dx-devops-test-failures-analyze
     — 在测试完成时接收失败负载；还可创建修复工作项。
  • dx-devops-test-suite-assignments-configure
     — 推荐应运行的测试套件，或在测试套件未关联至阶段时将其分配给该阶段。
  • dx-devops-test-pipeline-configure
     — 配置新的质量门或阈值（本技能仅重新运行现有质量门）。