Skip to content

Commit d3db992

Browse files
committed
docs(interaction): explain dispatched and the runner refusal reasons
1 parent 465ed16 commit d3db992

2 files changed

Lines changed: 10 additions & 1 deletion

File tree

‎website/docs/docs/client-api.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -234,6 +234,8 @@ Use `client.command.<method>()` for command-level device actions. It uses the sa
234234

235235
Results are daemon-shaped objects with typed known fields, so command semantics stay aligned with the CLI.
236236

237+
A failed interaction rejects with the same error the CLI prints. Read `error.details.dispatched` before you retry; [Commands](./commands.md) explains the three values.
238+
237239
```ts
238240
await client.command.wait({
239241
text: 'Continue',

‎website/docs/docs/commands.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -454,6 +454,7 @@ agent-device alert dismiss
454454
- Use `alert get` for an immediate cheap check. Use `alert wait <short-ms>` only when a prompt may appear after async work.
455455
- Within an iOS XCTest execution, `accept` and `dismiss` activate the selected button once, then only observe until the alert disappears, its presentation changes, or the deadline expires. A shared button label never triggers a second coordinate tap. A changed presentation can be an updated original alert or a replacement; it does not prove a permission was granted. Verify the application outcome separately.
456456
- An unreadable or ambiguous post-action capture fails with `error.details.runnerErrorCode: ALERT_CONFIRMATION_UNAVAILABLE`; an expired runner deadline uses `ALERT_DEADLINE_EXCEEDED` (the outer command watchdog can also report a timeout). Neither proves absence or that no action occurred. Identical-looking alerts remain unconfirmed. Inspect the current alert before deciding whether to act again.
457+
- iOS runner refusals carry `error.details.reason`: `runner_busy` means the runner was still finishing an earlier command and ran nothing (`dispatched: no`); `runner_main_thread_timeout` means the runner gave up waiting on the app, and the action may still land (`dispatched: unknown`).
457458
- Android support is snapshot-derived. If `alert` reports no alert but a sheet is visible, treat it as app-owned UI and use `snapshot -i` plus `press` by visible label/ref.
458459
- If an iOS permission sheet is visible in `snapshot` or `screenshot` but `alert accept` reports no alert, fall back to a scoped `snapshot -i -s "<visible label>"` plus `press @ref`; not every simulator permission surface is exposed as a native XCTest alert.
459460
@@ -488,7 +489,13 @@ agent-device gesture transform 200 420 80 -40 2 35 700 # combined pan, zoom, and
488489
```
489490
490491
`fill` clears then types. `type` does not clear.
491-
A failed interaction carries `error.details.dispatched` when its producer could classify it: `no` means the action provably never reached the device, `yes` means it executed and failed, and `unknown` means it may have landed, so observe the screen before retrying; a failure without the field was not classified.
492+
When an interaction fails, read `error.details.dispatched` before you retry:
493+
494+
- `no`: the action never reached the device. Retry it as it is.
495+
- `yes`: the action ran on the device and failed after that. Take a snapshot and decide from what you see.
496+
- `unknown`: the action may have landed. Take a snapshot before you retry; a blind retry can tap, type, or navigate twice.
497+
498+
A failure without `dispatched` gives no such guarantee. Treat it as `unknown`.
492499
`type` accepts text only. Do not pass `@ref` to `type`; use `fill @ref "text"` to target a field directly, or `press @ref` then `type "text"` to append in the focused field.
493500
If `type` reports `TEXT_INPUT_NOT_FOCUSED`, focus a visible text input and retry; when accessibility does not expose the input, use a coordinate focus command before typing.
494501
On iOS, if `type "\n"` reports `TEXT_INPUT_SYNTHESIS_UNAVAILABLE` after tapping a field while the software keyboard is hidden, show the software keyboard, then retry. The runner reports this error instead of risking input through an unreliable text-entry path.

0 commit comments

Comments
 (0)