Skip to content

forcedotcom/sf-skills / plugins/builder/dx-devops/skills/dx-devops-test-suite-run

dx-devops-test-suite-run

Verified

Runs DevOps Center test suites on a pipeline stage (Pre-Promote, Post-Promote, or Review event) end to end: triggers async execution via the Connect API after an explicit confirmation gate, then polls by runId at provider-specific intervals until it completes, fails, or times out, and hands results to failure analysis. Also retriggers a quality gate after fixes, but only once coverage meets the threshold. Use this skill when a user wants to run, kick off, or launch test suites on a stage, re-run a quality gate, or watch an in-progress run to completion. TRIGGER when: the user wants to run/launch suites on a stage, execute tests before or after promotion, re-run a quality gate after fixing failures, unblock a blocked promotion after adding tests, or poll/watch an in-progress run. DO NOT TRIGGER when: running sf apex run test directly (use platform-apex-test-run), or configuring a NEW gate or threshold (use dx-devops-test-pipeline-configure).

references/polling-configuration.md

View on GitHub
# Polling Configuration (Step 2)

**Confirmation required:** No — polling is automatic and read-only. No user confirmation gate is needed.

**What it does:** Polls the DevOps Center org for the status of an async test execution until it completes, times out, or fails.

## Prerequisites

You need an active `runId` (from Step 1, the execute call) and the confirmed `doce-org-alias`. If org context is not yet established, run Prerequisites 1–3 (`references/prerequisite-checks.md`).

## Inputs

| Input | Source |
|---|---|
| `runId` | Returned by the Step 1 execute call (or supplied by the user for an in-progress run) |
| `testType` | Derived from the suite's test provider (Apex, Code Analyzer, UI/Provar, Flow) |
| `doce-org-alias` | Established via prerequisites |

If the user is watching an already-running execution, resolve the `runId` by querying the most recent `DevopsTestExecution` for the relevant trigger, or use the runId the user provides.

## Polling intervals

| Test type | Poll interval | Max wait | Timeout action |
|---|---|---|---|
| Apex unit tests | 15 seconds | 5 minutes | Surface runId, offer retry |
| Code Analyzer | 10 seconds | 3 minutes | Surface runId, offer retry |
| UI tests (Provar) | 60 seconds | 20 minutes | Surface runId, mark as pending |
| Flow tests | 20 seconds | 8 minutes | Surface runId, offer retry |

## Object model — read the right object

The `runId` returned by the execute call is a **`DevopsTestSuiteExecution`** record Id (the suite-level run). Poll *that* object — it holds the status and the aggregate results. Per-test detail lives on child `DevopsTestExecution` records linked by `DevopsTestSuiteExecutionId`.

| Object | Role | Key fields |
|---|---|---|
| `DevopsTestSuiteExecution` (poll this) | Suite-level run = the `runId` | `Status`, `Coverage`, `SuccessCount`, `FailureCount`, `SuccessRate`, `FailureRate`, `QualityGateStatus`, `ExecutionEndTime`, `ResultDetails`, `ReportUrl` |
| `DevopsTestExecution` (per-test detail) | One row per test, linked via `DevopsTestSuiteExecutionId` | `Status`, `Message`, `Severity`, `ResultDetails`, `DevopsTestId` |

> Do NOT query `TestsRan`, `TestsPassed`, `TestsFailed`, or `CoveragePercentage` — those fields do not exist on either object and the query will fail with `INVALID_FIELD`. Use the field names in the table above.

## Poll query

Query the suite execution record by `runId` on each interval:

```bash
sf data query \
  --query "SELECT Id, Status, Coverage, SuccessCount, FailureCount, QualityGateStatus FROM DevopsTestSuiteExecution WHERE Id = '<runId>' LIMIT 1" \
  --target-org <doce-org-alias> \
  --json
```

Check the `Status` picklist on each poll (valid values: `Passed`, `Failed`, `InProgress`, `Error`):
- `InProgress` → wait and poll again
- `Passed` → run completed successfully; surface results
- `Failed` → run completed with test failures; surface results, then fetch per-test detail (below) and hand off to analysis
- `Error` → the run itself errored (not a test failure); surface the `ResultDetails`/`Message` in plain language and offer retry or skip

## On timeout

Surface the `runId` to the user:
> "The test run is taking longer than expected. Your run ID is `<runId>`. You can check the status manually in DevOps Center, or I can keep waiting — what would you prefer?"

Do not automatically retry after timeout. Wait for user instruction.

## On completion

When `Status` is `Passed` or `Failed`, surface `Coverage`, `SuccessCount`, `FailureCount`, and `QualityGateStatus` from the `DevopsTestSuiteExecution` record inline (no raw JSON).

If `FailureCount > 0` (or `Status = Failed`), fetch the per-test failure detail from the child `DevopsTestExecution` records, then pass that payload to the **`dx-devops-test-failures-analyze`** skill:

```bash
sf data query \
  --query "SELECT Id, Status, Message, Severity, ResultDetails, DevopsTestId FROM DevopsTestExecution WHERE DevopsTestSuiteExecutionId = '<runId>' AND Status = 'Failed'" \
  --target-org <doce-org-alias> \
  --json
```

**Empty / no-data case:** If no `DevopsTestSuiteExecution` record matches the runId, report that clearly and do NOT fabricate a runId, status, or result values.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall