From 944b08ff9934144f2117e7ce9de3182750a9b7fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E8=B5=B5=E6=A1=82=E9=9B=84?= Date: Mon, 23 Nov 2026 00:25:31 +0800 Subject: [PATCH] docs(commands): verify a coordinate press with a screenshot diff Co-Authored-By: Claude Code --- website/docs/docs/commands.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index b976c831e5..1b4f4a662b 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -1020,6 +1020,16 @@ A successful `click` or `press` means the action was sent to where the command f After an action that animated the screen, a `click` or `press` on a ref or selector waits for the target to come to rest. If it does not, the command refuses with `target_still_moving` and nothing is pressed. Run `wait ` on the target and retry, or add `--settle`. A refused `@ref` press needs a new `snapshot -i`, because the wait retires the ref. Presses at raw coordinates, and `click @ref` on the web, skip this check. +A raw-coordinate press has no ref to wait on and skips that check. To confirm that a coordinate press changed the screen, capture before and after, then diff: + +```bash +agent-device screenshot --out before.png +agent-device press 201 500 +agent-device diff screenshot --baseline before.png --out diff.png --json +``` + +`diff screenshot` ranks the changed regions and writes the tinted diff PNG. Before you retry a coordinate press that produced no change, see [Screenshots](#media-and-logs). + On iOS, a press on a control nested inside a larger touch control, such as a swipe action beside its row, refuses with `target_not_hittable` when the platform reports the control as not hittable. Reveal the control, for example by swiping its row, and take a new `snapshot -i`. A comma-separated ref plan, such as `press @e13,@e14`, presses 2 to 16 refs as one command. Run `snapshot -i` first and copy the refs exactly. A refusal after the first press reports `details.dispatchedSteps`; plan again from a new `snapshot -i`. While script recording is armed, a plan needs `--no-record`. See `agent-device help press`.