mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-08-01 12:20:24 +08:00
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# 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.
|