Skip to content

Commit 5c8f01c

Browse files
committed
docs(selectors): qualify which fields refuse find focus
Refs #3734
1 parent 6af2648 commit 5c8f01c

2 files changed

Lines changed: 3 additions & 3 deletions

File tree

‎packages/command-surface/src/interaction/metadata.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,7 @@ const interactionCommandDescriptions = {
7777
'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, or where a settle observation or a replay already owns that observation.',
7878
get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
7979
is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, settled, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
80-
find: 'Find by text/label/value/role/id and run action; the action defaults to click. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window. The focus and type actions aim at a text field: the match or the field holding it, even beside other fields, or else the one enabled on-screen field inside the match. Several fields inside the match refuse with AMBIGUOUS_MATCH and the field candidates, and a disabled field refuses with reason target_disabled. Web text boxes are not recognized as text fields.',
80+
find: 'Find by text/label/value/role/id and run action; the action defaults to click. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window. The focus and type actions aim at a text field: the match or the field holding it, even beside other fields, or else the one enabled on-screen field inside the match. Several enabled on-screen fields inside the match refuse with AMBIGUOUS_MATCH and the field candidates, and a disabled target refuses with reason target_disabled. Web text boxes are not recognized as text fields.',
8181
gesture:
8282
'Perform a structured pan, fling, swipe, pinch, rotate, transform, tap, or drag gesture. Select the gesture kind, then provide only the inputs that apply to that kind. A tap touches 2 to 5 points at once; repeat it with count and pauseMs.',
8383
} as const;

‎website/docs/docs/selectors.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,8 @@ Tips:
5656
- Pair `find` with a scoped snapshot (`snapshot -s "<label>"`) for speed.
5757
- [Android] If the matched node is not hittable, agent-device clicks or focuses the nearest hittable ancestor.
5858
- `find ... focus` and `find ... type` aim at a text field. If the match is a field or sits inside one, that field is the target, even when it is not hittable or has other fields beside it. Otherwise the target is the one enabled on-screen field inside the match.
59-
- Several fields inside the match refuse with `AMBIGUOUS_MATCH` and the field candidates.
60-
- A disabled field refuses with `COMMAND_FAILED` and reason `target_disabled`.
59+
- Several enabled on-screen fields inside the match refuse with `AMBIGUOUS_MATCH` and the field candidates.
60+
- A disabled target refuses with `COMMAND_FAILED` and reason `target_disabled`. This includes a match whose only on-screen fields are disabled.
6161
- A match or field covered by another visible element refuses with `COMMAND_FAILED`.
6262
- Web text boxes are not recognized as text fields, so a web match keeps its own aim.
6363
- Use `fill` to find a field and replace its text in one step. To append to the text in the focused field, use `click` or `press`, then `type`.

0 commit comments

Comments
 (0)