api wait
Poll by re-issuing the last API request until a JSON path matches
Re-issue the last completed API request until a gjson path equals the expected value (or timeout). Authors usually api get the status URL first, then wait.
Syntax
And I api wait until json path "<path>" be "<expected>"Forms
| Form | Meaning |
|---|---|
api wait until json path "<path>" be "<expected>" | Poll last request until path string equals expected |
Qualifiers
| Qualifier | Role |
|---|---|
until json path | gjson-style path to poll ($.status, …) |
be | Expected string value (resolved) |
Requirements
| Item | Contract |
|---|---|
| Element / control shape | None — HTTP session (Platform: api) |
| How the label binds | Path / body / headers are payloads ($ENV, slots expand) |
| Qualifiers that change resolve | See this command’s Qualifiers table |
| Platform | Platform: api only — requires $API_BASE_URL (and auth env as needed) |
| Wrong shape → use instead | UI XHR wait → wait for response. Browser UI → web commands |
See also UI contracts and Platform: api.
Examples
When I api post "/jobs" with body '{"type":"export"}'
Then I api should status "202"
When I store "@job-id" from api json "$.id"
When I api get "/jobs/@job-id"
And I api wait until json path "$.status" be "ready"
Then I api should json path "$.status" be "ready"Notes
- Each poll tick replays the last request (same method, path, and body or multipart snapshot) and updates the last response.
- Timeout is about 30s; interval matches other assertion polls (~250ms).
- On timeout, the error includes the last observed path value when the path exists.
- Distinct from one-shot api should
json path … be(no polling) and from UIwait for response(browser XHR).