From 7ae01f93f91c1bcdea7a7b898d0143cee3fbe9df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 16:41:00 +0100 Subject: [PATCH 1/8] fix(wait): ignore an editable field's typed value in wait text After fill, wait text matched the field's own value and passed before the app stored anything. An editable node now satisfies wait text only by its identifier or by a label distinct from its value, in the snapshot path and the iOS runner's native findText, pinned by one golden table. Fixes #4479 Co-Authored-By: Claude Opus 5.5 --- .../RunnerTests+Interaction.swift | 20 +++++- .../RunnerTests+InteractionTests.swift | 40 +++++++++++ contracts/fixtures/wait-text-policy.json | 60 +++++++++++++++++ .../commands/interaction/runtime/wait-text.ts | 4 +- packages/command-surface/src/capture/wait.ts | 2 +- packages/contracts/src/wait.test.ts | 32 +++++++++ packages/contracts/src/wait.ts | 17 +++++ .../provider-scenarios/android-find.test.ts | 11 +++- .../provider-scenarios/android-world.ts | 2 +- .../ios-wait-selector.test.ts | 66 +++++++++++++++++++ website/docs/docs/commands.md | 3 +- 11 files changed, 250 insertions(+), 7 deletions(-) create mode 100644 contracts/fixtures/wait-text-policy.json create mode 100644 packages/contracts/src/wait.test.ts diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift index 2080a023e9..39ac2d53ce 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift @@ -190,8 +190,26 @@ extension RunnerTests { #endif } + /// The `wait text` rule for native `findText`, pinned to `contracts/fixtures/wait-text-policy.json`. + /// A text-entry element's value is typed content, so it matches only by identifier or by a + /// label distinct from its value. The types are the ones the snapshot marks editable. + static func findTextPredicate(_ text: String) -> NSPredicate { + let editableTypes = [ + XCUIElement.ElementType.textField, + .secureTextField, + .searchField, + .textView, + ].map(\.rawValue) + return NSPredicate( + format: "identifier CONTAINS[c] %@" + + " OR (NOT (elementType IN %@) AND (label CONTAINS[c] %@ OR value CONTAINS[c] %@))" + + " OR (elementType IN %@ AND label CONTAINS[c] %@ AND label != value)", + text, editableTypes, text, text, editableTypes, text + ) + } + func findElement(app: XCUIApplication, text: String) throws -> XCUIElement? { - let predicate = NSPredicate(format: "label CONTAINS[c] %@ OR identifier CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text, text) + let predicate = Self.findTextPredicate(text) return try elementQueries(app: app, matching: .any) .lazy .map { $0.matching(predicate).firstMatch } diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift index f610e44596..70fc114879 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift @@ -23,6 +23,46 @@ extension RunnerTests { XCTAssertEqual(events.count, 1) XCTAssertEqual(events.first?.vertical, -200) } + + func testFindTextPredicateMatchesWaitTextGoldenTable() throws { + struct Case: Decodable { + struct Node: Decodable { + let editable: Bool? + let label: String? + let value: String? + let identifier: String? + } + let name: String + let text: String + let node: Node + let expected: Bool + } + let fixtureURL = URL(fileURLWithPath: #filePath) + .deletingLastPathComponent() // UnitTests + .deletingLastPathComponent() // AgentDeviceRunnerUITests + .deletingLastPathComponent() // AgentDeviceRunner + .deletingLastPathComponent() // runner + .deletingLastPathComponent() // apple + .deletingLastPathComponent() // repo root + .appendingPathComponent("contracts/fixtures/wait-text-policy.json") + let cases = try JSONDecoder().decode([Case].self, from: Data(contentsOf: fixtureURL)) + XCTAssertFalse(cases.isEmpty, "wait text policy table must not be empty") + + let editableTypes: [XCUIElement.ElementType] = [.textField, .secureTextField, .searchField, .textView] + for fixture in cases { + for type in fixture.node.editable == true ? editableTypes : [.staticText, .other] { + var attributes: [String: Any] = ["elementType": type.rawValue] + attributes["label"] = fixture.node.label + attributes["value"] = fixture.node.value + attributes["identifier"] = fixture.node.identifier + XCTAssertEqual( + Self.findTextPredicate(fixture.text).evaluate(with: attributes), + fixture.expected, + "\(fixture.name) (elementType \(type.rawValue))" + ) + } + } + } } #endif diff --git a/contracts/fixtures/wait-text-policy.json b/contracts/fixtures/wait-text-policy.json new file mode 100644 index 0000000000..6347cb5f37 --- /dev/null +++ b/contracts/fixtures/wait-text-policy.json @@ -0,0 +1,60 @@ +[ + { + "name": "static text matches by label, case-insensitively", + "text": "saved", + "node": { "label": "Name Saved" }, + "expected": true + }, + { + "name": "a non-editable value still matches", + "text": "bench-ad", + "node": { "label": "Device name", "value": "bench-ad" }, + "expected": true + }, + { + "name": "an editable field's typed value does not match", + "text": "benchad", + "node": { "editable": true, "label": "First name", "value": "benchad" }, + "expected": false + }, + { + "name": "part of an editable field's typed value does not match", + "text": "bench", + "node": { "editable": true, "label": "First name", "value": "benchad" }, + "expected": false + }, + { + "name": "an editable field still matches by its label", + "text": "first name", + "node": { "editable": true, "label": "First name", "value": "benchad" }, + "expected": true + }, + { + "name": "an editable field whose label repeats its typed value does not match", + "text": "bench-ad", + "node": { + "editable": true, + "label": "bench-ad", + "value": "bench-ad", + "identifier": "android:id/edit" + }, + "expected": false + }, + { + "name": "an editable field still matches by its identifier", + "text": "id/edit", + "node": { + "editable": true, + "label": "bench-ad", + "value": "bench-ad", + "identifier": "android:id/edit" + }, + "expected": true + }, + { + "name": "an empty editable field matches by its hint label", + "text": "device name", + "node": { "editable": true, "label": "Device name", "value": "" }, + "expected": true + } +] diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts index 70732cff07..615988e7e3 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts @@ -5,7 +5,7 @@ import type { WaitCommandOptions, WaitCommandResult, } from './selector-wait.ts'; -import { findNodeByLabel } from './selector-read-utils.ts'; +import { matchesWaitText } from '@agent-device/contracts/wait'; import { SELECTOR_PIPELINE_POLICIES } from '@agent-device/selectors/selector-pipeline-policy'; import { createWaitPolling, type WaitPollDeadline, waitTimeoutError } from './wait-polling.ts'; @@ -57,7 +57,7 @@ async function snapshotContainsText( updateSession: true, includeHiddenContentHints: false, }); - return Boolean(findNodeByLabel(capture.snapshot.nodes, text)); + return capture.snapshot.nodes.some((node) => matchesWaitText(node, text)); } function backendContext( diff --git a/packages/command-surface/src/capture/wait.ts b/packages/command-surface/src/capture/wait.ts index 2840e68202..8d0014735a 100644 --- a/packages/command-surface/src/capture/wait.ts +++ b/packages/command-surface/src/capture/wait.ts @@ -59,7 +59,7 @@ export const WAIT_COMMAND_OUTPUT_SCHEMAS = { } satisfies Pick, 'wait'>; const waitCommandDescription = - 'Wait for a duration, text, snapshot ref, selector to appear, selector to be strictly absent, or stable UI. Use the strict absence target when zero selector matches are required; stable waits until the UI stays quiet for the requested window.'; + 'Wait for a duration, text, snapshot ref, selector to appear, selector to be strictly absent, or stable UI. Text matches a label, identifier, or value, but never the typed value of an editable field, so it confirms text the app shows rather than your own input. Use the strict absence target when zero selector matches are required; stable waits until the UI stays quiet for the requested window.'; const waitCommandMetadata = defineFieldCommandMetadata(WAIT_COMMAND_NAME, waitCommandDescription, { kind: enumField(WAIT_KIND_VALUES), diff --git a/packages/contracts/src/wait.test.ts b/packages/contracts/src/wait.test.ts new file mode 100644 index 0000000000..22e90b8529 --- /dev/null +++ b/packages/contracts/src/wait.test.ts @@ -0,0 +1,32 @@ +import { test } from 'vitest'; +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { matchesWaitText } from './wait.ts'; + +// Golden `wait text` table: the Swift runner's native findText predicate is asserted against the +// same JSON (RunnerTests+WaitTextPolicyTests.swift). +type WaitTextCase = { + name: string; + text: string; + node: { editable?: boolean; label?: string; value?: string; identifier?: string }; + expected: boolean; +}; + +const TABLE_PATH = path.resolve( + import.meta.dirname, + '..', + '..', + '..', + 'contracts', + 'fixtures', + 'wait-text-policy.json', +); + +test('wait text matches visible text but not an editable field’s typed content', () => { + const cases = JSON.parse(fs.readFileSync(TABLE_PATH, 'utf8')) as WaitTextCase[]; + assert.ok(cases.length > 0, 'wait text policy table must not be empty'); + for (const fixture of cases) { + assert.equal(matchesWaitText(fixture.node, fixture.text), fixture.expected, fixture.name); + } +}); diff --git a/packages/contracts/src/wait.ts b/packages/contracts/src/wait.ts index 9528c11f22..4b715039e4 100644 --- a/packages/contracts/src/wait.ts +++ b/packages/contracts/src/wait.ts @@ -1,3 +1,5 @@ +import { matchesSnapshotScope, type SnapshotScopeCandidate } from './snapshot-scope.ts'; + /** * Machine-readable wait failure taxonomy. These values are carried in * `error.details.reason`; callers should branch on them instead of parsing @@ -59,3 +61,18 @@ export type WaitCommandResult = { hint?: string; warning?: string; }; + +/** + * The `wait text` match rule: the snapshot scope rule minus typed content. An editable node's + * value is what the user typed, and Android also reports that text as the node's label, so an + * editable node matches only by its identifier or by a label distinct from its value. The Swift + * runner's native `findText` is pinned to the same table, `contracts/fixtures/wait-text-policy.json`. + */ +export function matchesWaitText( + node: SnapshotScopeCandidate & { editable?: boolean }, + text: string, +): boolean { + if (node.editable !== true) return matchesSnapshotScope(node, text); + const label = node.label === node.value ? undefined : node.label; + return matchesSnapshotScope({ identifier: node.identifier, label }, text); +} diff --git a/test/integration/provider-scenarios/android-find.test.ts b/test/integration/provider-scenarios/android-find.test.ts index 333ec1a6f1..c12306a20e 100644 --- a/test/integration/provider-scenarios/android-find.test.ts +++ b/test/integration/provider-scenarios/android-find.test.ts @@ -3,7 +3,8 @@ import { test } from 'vitest'; import { ANDROID_IME_HELPER_FIXTURE_ARTIFACT } from '../../../src/__tests__/test-utils/android-ime-helper.ts'; import { ANDROID_SNAPSHOT_HELPER_FIXTURE_ARTIFACT } from '../../../src/__tests__/test-utils/android-snapshot-helper.ts'; import type { AndroidAdbProvider } from '@agent-device/platform-android/mechanics'; -import { arrayEqual, assertCommandCall } from './assertions.ts'; +import { WAIT_REASONS } from '@agent-device/contracts/wait'; +import { arrayEqual, assertCommandCall, assertRpcOk } from './assertions.ts'; import { androidSettingsXml, androidSnapshotHelperOutput } from './android-world.ts'; import { androidImeClearTextBroadcast, @@ -114,6 +115,14 @@ test('Provider-backed integration Android find flow covers refs, wait, ambiguity }); assert.equal(filled.text, 'Network'); + // The field's own typed value is not app text: only its identifier satisfies `wait text`. + const typedWait = await daemon.callCommand('wait', ['text', 'Network', '100'], selection); + assert.equal(typedWait.json?.error?.data?.details?.reason, WAIT_REASONS.targetAbsent); + assert.equal( + assertRpcOk(await daemon.callCommand('wait', ['text', 'id/search', '100'], selection)).text, + 'id/search', + ); + const waitForApps = await client.interactions.find({ locator: 'label', query: 'Apps', diff --git a/test/integration/provider-scenarios/android-world.ts b/test/integration/provider-scenarios/android-world.ts index e1016997ab..ab372abf7c 100644 --- a/test/integration/provider-scenarios/android-world.ts +++ b/test/integration/provider-scenarios/android-world.ts @@ -747,7 +747,7 @@ export function androidSettingsXml( '', ' ', ' ', - ` `, + ` `, ...(options.duplicateAppsRow ? [ ' ', diff --git a/test/integration/provider-scenarios/ios-wait-selector.test.ts b/test/integration/provider-scenarios/ios-wait-selector.test.ts index 92cfe8a903..bec41aad4a 100644 --- a/test/integration/provider-scenarios/ios-wait-selector.test.ts +++ b/test/integration/provider-scenarios/ios-wait-selector.test.ts @@ -3,6 +3,7 @@ import fs from 'node:fs'; import path from 'node:path'; import { test } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; +import { WAIT_REASONS } from '@agent-device/contracts/wait'; import { mkdtempForTestSync } from '@agent-device/test-kit'; import { PROVIDER_SCENARIO_IOS_SIMULATOR } from './fixtures.ts'; import { assertRpcOk } from './assertions.ts'; @@ -109,3 +110,68 @@ test.each([ await daemon.close(); } }); + +test('Apple wait text ignores a text field’s typed value but matches its label', async () => { + const appleTool = createRecordingAppleToolProvider({ + simctl: async (args) => { + if (args[0] === 'list') { + return { + stdout: JSON.stringify({ + devices: { + 'iOS 18.5': [{ udid: PROVIDER_SCENARIO_IOS_SIMULATOR.id, state: 'Booted' }], + }, + }), + stderr: '', + exitCode: 0, + }; + } + if (args[0] === 'launch') return { stdout: '', stderr: '', exitCode: 0 }; + throw new Error(`Unexpected Apple simulator call: ${args.join(' ')}`); + }, + }); + const daemon = await createProviderScenarioHarness({ + deviceInventoryProvider: async () => [PROVIDER_SCENARIO_IOS_SIMULATOR], + appleToolProvider: () => appleTool.provider, + appleRunnerProvider: () => ({ + hasLiveSession: () => true, + runCommand: async (_device, command) => { + if (command.command === 'findText') return { found: false }; + assert.equal(command.command, 'snapshot'); + return { + nodes: [ + { + index: 0, + type: 'Application', + label: 'Contacts', + rect: { x: 0, y: 0, width: 393, height: 852 }, + }, + { + index: 1, + parentIndex: 0, + type: 'TextField', + label: 'First name', + value: 'benchad', + rect: { x: 16, y: 200, width: 361, height: 44 }, + }, + ], + }; + }, + }), + }); + try { + await daemon.client().apps.open({ + app: 'com.apple.MobileAddressBook', + platform: 'ios', + udid: PROVIDER_SCENARIO_IOS_SIMULATOR.id, + }); + const flags = { platform: 'ios' as const }; + const typed = await daemon.callCommand('wait', ['text', 'benchad', '1000'], flags); + assert.equal(typed.json?.error?.data?.details?.reason, WAIT_REASONS.targetAbsent); + assert.equal( + assertRpcOk(await daemon.callCommand('wait', ['text', 'First name', '100'], flags)).text, + 'First name', + ); + } finally { + await daemon.close(); + } +}); diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 03ccafee12..e8053e7940 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -430,7 +430,8 @@ agent-device alert dismiss - `wait` accepts a millisecond duration, `text `, a snapshot ref (`@eN`), a selector, or strict `absent `. Every form except a plain duration takes an optional `[timeoutMs]`. Selector waits, including those inside `replay`, poll snapshot captures with the same backend and recovery as `is`. `wait` resolves selectors the same way as `click`, `fill`, `get`, and `is`. - `wait absent ` is strict absence, not a visibility check: it passes only when a complete, readable capture has zero matches, so hidden or off-screen matches keep it pending. It rejects `--scope` and `--depth`. Sparse, truncated, incomplete, and Android unreadable-content captures never satisfy it. -- `wait @ref` needs a snapshot from a prior `snapshot` command. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. +- `wait text ` matches a node whose label, identifier, or value contains the text, ignoring case. An editable field's own value, the text you typed, never matches, and neither does a field label that only repeats it, so `wait text` after `fill` waits until the app shows that text elsewhere, for example after Save. To check the field itself, use `is text ` or `get text`. +- `wait @ref` needs a snapshot from a prior `snapshot` command. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. It uses the same text rule. - Wait failures carry `error.details.reason` in `--json` output: - `wait_target_absent`: a positive wait never found a match. - `wait_target_present`: strict `wait absent` reached its deadline with valid captures that still contained matches. From 1dcee88522b3e68abf79cece52b19517cf64c4ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 16:57:27 +0100 Subject: [PATCH 2/8] fix(wait): resolve wait text editability through the selector owner Move the wait text rule beside checkWaitText and decide editability with isNodeEditable, so an Android EditText without an editable fact (fallback or Appium) is covered and a disabled field's value still matches. A field whose value equals its placeholder is showing its hint, so it matches like any node; iOS reports an empty field that way. The runner predicate and the golden table follow. Co-Authored-By: Claude Opus 5.5 --- .../RunnerTests+Interaction.swift | 24 ++++-- .../RunnerTests+InteractionTests.swift | 12 ++- contracts/fixtures/wait-text-policy.json | 76 +++++++++++++++++-- .../commands/interaction/runtime/wait-text.ts | 6 +- packages/command-surface/src/capture/wait.ts | 2 +- packages/contracts/src/wait.ts | 17 ----- packages/selectors/src/index.ts | 2 + .../src/internal/wait-text.test.ts} | 16 +++- packages/selectors/src/internal/wait-text.ts | 23 ++++++ .../provider-scenarios/android-find.test.ts | 3 +- .../provider-scenarios/android-world.ts | 2 +- website/docs/docs/commands.md | 2 +- 12 files changed, 143 insertions(+), 42 deletions(-) rename packages/{contracts/src/wait.test.ts => selectors/src/internal/wait-text.test.ts} (60%) create mode 100644 packages/selectors/src/internal/wait-text.ts diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift index 39ac2d53ce..0cc89a7b01 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift @@ -191,8 +191,9 @@ extension RunnerTests { } /// The `wait text` rule for native `findText`, pinned to `contracts/fixtures/wait-text-policy.json`. - /// A text-entry element's value is typed content, so it matches only by identifier or by a - /// label distinct from its value. The types are the ones the snapshot marks editable. + /// An enabled text-entry element's value is typed content unless it is the placeholder, so such + /// an element matches only by identifier or by a label that is not its value. The types are the + /// ones the snapshot marks editable. static func findTextPredicate(_ text: String) -> NSPredicate { let editableTypes = [ XCUIElement.ElementType.textField, @@ -200,12 +201,21 @@ extension RunnerTests { .searchField, .textView, ].map(\.rawValue) - return NSPredicate( - format: "identifier CONTAINS[c] %@" - + " OR (NOT (elementType IN %@) AND (label CONTAINS[c] %@ OR value CONTAINS[c] %@))" - + " OR (elementType IN %@ AND label CONTAINS[c] %@ AND label != value)", - text, editableTypes, text, text, editableTypes, text + let typed = NSPredicate( + format: "elementType IN %@ AND enabled == YES AND value != placeholderValue", + editableTypes ) + return NSCompoundPredicate(orPredicateWithSubpredicates: [ + NSPredicate(format: "identifier CONTAINS[c] %@", text), + NSCompoundPredicate(andPredicateWithSubpredicates: [ + NSCompoundPredicate(notPredicateWithSubpredicate: typed), + NSPredicate(format: "label CONTAINS[c] %@ OR value CONTAINS[c] %@", text, text), + ]), + NSCompoundPredicate(andPredicateWithSubpredicates: [ + typed, + NSPredicate(format: "label CONTAINS[c] %@ AND label != value", text), + ]), + ]) } func findElement(app: XCUIApplication, text: String) throws -> XCUIElement? { diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift index 70fc114879..f21a60d2d2 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift @@ -28,11 +28,14 @@ extension RunnerTests { struct Case: Decodable { struct Node: Decodable { let editable: Bool? + let enabled: Bool? let label: String? let value: String? let identifier: String? + let placeholder: String? } let name: String + let platform: String? let text: String let node: Node let expected: Bool @@ -49,12 +52,17 @@ extension RunnerTests { XCTAssertFalse(cases.isEmpty, "wait text policy table must not be empty") let editableTypes: [XCUIElement.ElementType] = [.textField, .secureTextField, .searchField, .textView] - for fixture in cases { + // Android-only rows pin the TS twin; the runner sees Apple element types only. + for fixture in cases where fixture.platform == nil { for type in fixture.node.editable == true ? editableTypes : [.staticText, .other] { - var attributes: [String: Any] = ["elementType": type.rawValue] + var attributes: [String: Any] = [ + "elementType": type.rawValue, + "enabled": fixture.node.enabled ?? true, + ] attributes["label"] = fixture.node.label attributes["value"] = fixture.node.value attributes["identifier"] = fixture.node.identifier + attributes["placeholderValue"] = fixture.node.placeholder XCTAssertEqual( Self.findTextPredicate(fixture.text).evaluate(with: attributes), fixture.expected, diff --git a/contracts/fixtures/wait-text-policy.json b/contracts/fixtures/wait-text-policy.json index 6347cb5f37..f416004253 100644 --- a/contracts/fixtures/wait-text-policy.json +++ b/contracts/fixtures/wait-text-policy.json @@ -2,31 +2,48 @@ { "name": "static text matches by label, case-insensitively", "text": "saved", - "node": { "label": "Name Saved" }, + "node": { + "label": "Name Saved" + }, "expected": true }, { "name": "a non-editable value still matches", "text": "bench-ad", - "node": { "label": "Device name", "value": "bench-ad" }, + "node": { + "label": "Device name", + "value": "bench-ad" + }, "expected": true }, { "name": "an editable field's typed value does not match", "text": "benchad", - "node": { "editable": true, "label": "First name", "value": "benchad" }, + "node": { + "editable": true, + "label": "First name", + "value": "benchad" + }, "expected": false }, { "name": "part of an editable field's typed value does not match", "text": "bench", - "node": { "editable": true, "label": "First name", "value": "benchad" }, + "node": { + "editable": true, + "label": "First name", + "value": "benchad" + }, "expected": false }, { "name": "an editable field still matches by its label", "text": "first name", - "node": { "editable": true, "label": "First name", "value": "benchad" }, + "node": { + "editable": true, + "label": "First name", + "value": "benchad" + }, "expected": true }, { @@ -54,7 +71,54 @@ { "name": "an empty editable field matches by its hint label", "text": "device name", - "node": { "editable": true, "label": "Device name", "value": "" }, + "node": { + "editable": true, + "label": "Device name", + "value": "" + }, "expected": true + }, + { + "name": "a hint reported as both label and value still matches as the placeholder", + "text": "device name", + "node": { + "editable": true, + "label": "Device name", + "value": "Device name", + "placeholder": "Device name" + }, + "expected": true + }, + { + "name": "an empty field whose value is its placeholder matches by that placeholder", + "text": "last name", + "node": { + "editable": true, + "value": "Last name", + "placeholder": "Last name" + }, + "expected": true + }, + { + "name": "a disabled field's value is app text and matches", + "text": "bench-ad", + "node": { + "editable": true, + "enabled": false, + "label": "Name", + "value": "bench-ad" + }, + "expected": true + }, + { + "name": "an Android EditText without an editable fact is editable by its class", + "platform": "android", + "text": "bench-ad", + "node": { + "type": "android.widget.EditText", + "label": "bench-ad", + "value": "bench-ad" + }, + "expected": false } ] diff --git a/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts b/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts index 615988e7e3..d69f9ea0f4 100644 --- a/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts +++ b/packages/command-runtime/src/commands/interaction/runtime/wait-text.ts @@ -5,7 +5,7 @@ import type { WaitCommandOptions, WaitCommandResult, } from './selector-wait.ts'; -import { matchesWaitText } from '@agent-device/contracts/wait'; +import { matchesWaitText } from '@agent-device/selectors'; import { SELECTOR_PIPELINE_POLICIES } from '@agent-device/selectors/selector-pipeline-policy'; import { createWaitPolling, type WaitPollDeadline, waitTimeoutError } from './wait-polling.ts'; @@ -57,7 +57,9 @@ async function snapshotContainsText( updateSession: true, includeHiddenContentHints: false, }); - return capture.snapshot.nodes.some((node) => matchesWaitText(node, text)); + return capture.snapshot.nodes.some((node) => + matchesWaitText(node, text, runtime.backend.platform), + ); } function backendContext( diff --git a/packages/command-surface/src/capture/wait.ts b/packages/command-surface/src/capture/wait.ts index 8d0014735a..f2a1f777e6 100644 --- a/packages/command-surface/src/capture/wait.ts +++ b/packages/command-surface/src/capture/wait.ts @@ -59,7 +59,7 @@ export const WAIT_COMMAND_OUTPUT_SCHEMAS = { } satisfies Pick, 'wait'>; const waitCommandDescription = - 'Wait for a duration, text, snapshot ref, selector to appear, selector to be strictly absent, or stable UI. Text matches a label, identifier, or value, but never the typed value of an editable field, so it confirms text the app shows rather than your own input. Use the strict absence target when zero selector matches are required; stable waits until the UI stays quiet for the requested window.'; + 'Wait for a duration, text, snapshot ref, selector to appear, selector to be strictly absent, or stable UI. Text matches a label, identifier, or value; an editable field never matches by its current value or by a label that only repeats it, so text you typed does not satisfy it. Use the strict absence target when zero selector matches are required; stable waits until the UI stays quiet for the requested window.'; const waitCommandMetadata = defineFieldCommandMetadata(WAIT_COMMAND_NAME, waitCommandDescription, { kind: enumField(WAIT_KIND_VALUES), diff --git a/packages/contracts/src/wait.ts b/packages/contracts/src/wait.ts index 4b715039e4..9528c11f22 100644 --- a/packages/contracts/src/wait.ts +++ b/packages/contracts/src/wait.ts @@ -1,5 +1,3 @@ -import { matchesSnapshotScope, type SnapshotScopeCandidate } from './snapshot-scope.ts'; - /** * Machine-readable wait failure taxonomy. These values are carried in * `error.details.reason`; callers should branch on them instead of parsing @@ -61,18 +59,3 @@ export type WaitCommandResult = { hint?: string; warning?: string; }; - -/** - * The `wait text` match rule: the snapshot scope rule minus typed content. An editable node's - * value is what the user typed, and Android also reports that text as the node's label, so an - * editable node matches only by its identifier or by a label distinct from its value. The Swift - * runner's native `findText` is pinned to the same table, `contracts/fixtures/wait-text-policy.json`. - */ -export function matchesWaitText( - node: SnapshotScopeCandidate & { editable?: boolean }, - text: string, -): boolean { - if (node.editable !== true) return matchesSnapshotScope(node, text); - const label = node.label === node.value ? undefined : node.label; - return matchesSnapshotScope({ identifier: node.identifier, label }, text); -} diff --git a/packages/selectors/src/index.ts b/packages/selectors/src/index.ts index c49b28bce8..7396fefe78 100644 --- a/packages/selectors/src/index.ts +++ b/packages/selectors/src/index.ts @@ -24,6 +24,7 @@ import { normalizeIsPositionals, } from './internal/predicates.ts'; import { selectorFailureHint, STALE_REF_HINT } from './internal/resolve.ts'; +import { matchesWaitText } from './internal/wait-text.ts'; import { findBestMatchesByLocator, checkFindArgs, @@ -70,6 +71,7 @@ export { isRoleHintWord, isSelectorToken, isValidSelectorExpression, + matchesWaitText, normalizeIsPositionals, normalizeSelectorText, parseFindArgs, diff --git a/packages/contracts/src/wait.test.ts b/packages/selectors/src/internal/wait-text.test.ts similarity index 60% rename from packages/contracts/src/wait.test.ts rename to packages/selectors/src/internal/wait-text.test.ts index 22e90b8529..728afb493f 100644 --- a/packages/contracts/src/wait.test.ts +++ b/packages/selectors/src/internal/wait-text.test.ts @@ -2,14 +2,16 @@ import { test } from 'vitest'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; -import { matchesWaitText } from './wait.ts'; +import type { SnapshotNode } from '@agent-device/kernel/snapshot'; +import { matchesWaitText } from './wait-text.ts'; // Golden `wait text` table: the Swift runner's native findText predicate is asserted against the -// same JSON (RunnerTests+WaitTextPolicyTests.swift). +// same JSON (UnitTests/RunnerTests+InteractionTests.swift). type WaitTextCase = { name: string; + platform?: 'android'; text: string; - node: { editable?: boolean; label?: string; value?: string; identifier?: string }; + node: Omit; expected: boolean; }; @@ -18,6 +20,7 @@ const TABLE_PATH = path.resolve( '..', '..', '..', + '..', 'contracts', 'fixtures', 'wait-text-policy.json', @@ -27,6 +30,11 @@ test('wait text matches visible text but not an editable field’s typed content const cases = JSON.parse(fs.readFileSync(TABLE_PATH, 'utf8')) as WaitTextCase[]; assert.ok(cases.length > 0, 'wait text policy table must not be empty'); for (const fixture of cases) { - assert.equal(matchesWaitText(fixture.node, fixture.text), fixture.expected, fixture.name); + const node = { index: 0, ref: 'e1', type: 'StaticText', ...fixture.node }; + assert.equal( + matchesWaitText(node, fixture.text, fixture.platform ?? 'ios'), + fixture.expected, + fixture.name, + ); } }); diff --git a/packages/selectors/src/internal/wait-text.ts b/packages/selectors/src/internal/wait-text.ts new file mode 100644 index 0000000000..c95617472c --- /dev/null +++ b/packages/selectors/src/internal/wait-text.ts @@ -0,0 +1,23 @@ +import type { Platform, PublicPlatform } from '@agent-device/kernel/device'; +import type { SnapshotNode } from '@agent-device/kernel/snapshot'; +import { matchesSnapshotScope } from '@agent-device/contracts/snapshot'; +import { isNodeEditable } from './node.ts'; + +/** + * The `wait text` match rule: the snapshot scope rule minus typed content. An editable node's + * value is what the user typed, and Android also reports that text as the node's label, so an + * editable node matches only by its identifier or by a label that is not its value. A value equal + * to the placeholder is the field's hint, not typed text. The Swift runner's native `findText` is + * pinned to the same table, `contracts/fixtures/wait-text-policy.json`. + */ +export function matchesWaitText( + node: SnapshotNode, + text: string, + platform: Platform | PublicPlatform, +): boolean { + if (!isNodeEditable(node, platform) || node.value === node.placeholder) { + return matchesSnapshotScope(node, text); + } + const label = node.label === node.value ? undefined : node.label; + return matchesSnapshotScope({ identifier: node.identifier, label }, text); +} diff --git a/test/integration/provider-scenarios/android-find.test.ts b/test/integration/provider-scenarios/android-find.test.ts index c12306a20e..59bbb1491e 100644 --- a/test/integration/provider-scenarios/android-find.test.ts +++ b/test/integration/provider-scenarios/android-find.test.ts @@ -115,7 +115,8 @@ test('Provider-backed integration Android find flow covers refs, wait, ambiguity }); assert.equal(filled.text, 'Network'); - // The field's own typed value is not app text: only its identifier satisfies `wait text`. + // The field's label repeats its typed value (no editable fact: the EditText class decides), + // so only its identifier satisfies `wait text`. const typedWait = await daemon.callCommand('wait', ['text', 'Network', '100'], selection); assert.equal(typedWait.json?.error?.data?.details?.reason, WAIT_REASONS.targetAbsent); assert.equal( diff --git a/test/integration/provider-scenarios/android-world.ts b/test/integration/provider-scenarios/android-world.ts index ab372abf7c..e1016997ab 100644 --- a/test/integration/provider-scenarios/android-world.ts +++ b/test/integration/provider-scenarios/android-world.ts @@ -747,7 +747,7 @@ export function androidSettingsXml( '', ' ', ' ', - ` `, + ` `, ...(options.duplicateAppsRow ? [ ' ', diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index e8053e7940..1f9d74493d 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -430,7 +430,7 @@ agent-device alert dismiss - `wait` accepts a millisecond duration, `text `, a snapshot ref (`@eN`), a selector, or strict `absent `. Every form except a plain duration takes an optional `[timeoutMs]`. Selector waits, including those inside `replay`, poll snapshot captures with the same backend and recovery as `is`. `wait` resolves selectors the same way as `click`, `fill`, `get`, and `is`. - `wait absent ` is strict absence, not a visibility check: it passes only when a complete, readable capture has zero matches, so hidden or off-screen matches keep it pending. It rejects `--scope` and `--depth`. Sparse, truncated, incomplete, and Android unreadable-content captures never satisfy it. -- `wait text ` matches a node whose label, identifier, or value contains the text, ignoring case. An editable field's own value, the text you typed, never matches, and neither does a field label that only repeats it, so `wait text` after `fill` waits until the app shows that text elsewhere, for example after Save. To check the field itself, use `is text ` or `get text`. +- `wait text ` matches a node whose label, identifier, or value contains the text, ignoring case. An enabled editable field never matches by its current value, or by a label that only repeats that value (a label equal to its placeholder still matches). Its identifier, or a label distinct from the value, still can. So `wait text` after `fill` waits until the app shows that text elsewhere, for example after Save. To check the field itself, use `is text ` or `get text`. - `wait @ref` needs a snapshot from a prior `snapshot` command. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. It uses the same text rule. - Wait failures carry `error.details.reason` in `--json` output: - `wait_target_absent`: a positive wait never found a match. From 2e67104ce6f5adc25019a3d78d2c9aab130b7201 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 17:02:12 +0100 Subject: [PATCH 3/8] docs(wait): describe the placeholder case of wait text Co-Authored-By: Claude Opus 5.5 --- website/docs/docs/commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 1f9d74493d..24ee261b3b 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -430,7 +430,7 @@ agent-device alert dismiss - `wait` accepts a millisecond duration, `text `, a snapshot ref (`@eN`), a selector, or strict `absent `. Every form except a plain duration takes an optional `[timeoutMs]`. Selector waits, including those inside `replay`, poll snapshot captures with the same backend and recovery as `is`. `wait` resolves selectors the same way as `click`, `fill`, `get`, and `is`. - `wait absent ` is strict absence, not a visibility check: it passes only when a complete, readable capture has zero matches, so hidden or off-screen matches keep it pending. It rejects `--scope` and `--depth`. Sparse, truncated, incomplete, and Android unreadable-content captures never satisfy it. -- `wait text ` matches a node whose label, identifier, or value contains the text, ignoring case. An enabled editable field never matches by its current value, or by a label that only repeats that value (a label equal to its placeholder still matches). Its identifier, or a label distinct from the value, still can. So `wait text` after `fill` waits until the app shows that text elsewhere, for example after Save. To check the field itself, use `is text ` or `get text`. +- `wait text ` matches a node whose label, identifier, or value contains the text, ignoring case. An enabled editable field never matches by its current value, or by a label that only repeats that value. Its identifier, a label distinct from the value, or the placeholder an empty field shows still match. So `wait text` after `fill` waits until the app shows that text elsewhere, for example after Save. To check the field itself, use `is text ` or `get text`. - `wait @ref` needs a snapshot from a prior `snapshot` command. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. It uses the same text rule. - Wait failures carry `error.details.reason` in `--json` output: - `wait_target_absent`: a positive wait never found a match. From f1c0a01d934ac56d35e5a698844f55fffc741874 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 17:04:51 +0100 Subject: [PATCH 4/8] fix(selectors): treat web textbox and searchbox nodes as fillable Web captures publish no editable fact, so isFillableType decided and answered false for ARIA text inputs: editable=true missed web fields, fill warned it was attempting anyway, and wait text matched a web field's typed value. Co-Authored-By: Claude Opus 5.5 --- .../UnitTests/RunnerTests+InteractionTests.swift | 2 +- contracts/fixtures/wait-text-policy.json | 11 +++++++++++ packages/contracts/src/snapshot-text.test.ts | 6 ++++++ packages/contracts/src/snapshot-text.ts | 2 ++ packages/selectors/src/internal/wait-text.test.ts | 2 +- 5 files changed, 21 insertions(+), 2 deletions(-) diff --git a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift index f21a60d2d2..05bb33f0ec 100644 --- a/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift +++ b/apple/runner/AgentDeviceRunner/AgentDeviceRunnerUITests/UnitTests/RunnerTests+InteractionTests.swift @@ -52,7 +52,7 @@ extension RunnerTests { XCTAssertFalse(cases.isEmpty, "wait text policy table must not be empty") let editableTypes: [XCUIElement.ElementType] = [.textField, .secureTextField, .searchField, .textView] - // Android-only rows pin the TS twin; the runner sees Apple element types only. + // Android and web rows pin the TS twin; the runner sees Apple element types only. for fixture in cases where fixture.platform == nil { for type in fixture.node.editable == true ? editableTypes : [.staticText, .other] { var attributes: [String: Any] = [ diff --git a/contracts/fixtures/wait-text-policy.json b/contracts/fixtures/wait-text-policy.json index f416004253..7f154fa3ff 100644 --- a/contracts/fixtures/wait-text-policy.json +++ b/contracts/fixtures/wait-text-policy.json @@ -120,5 +120,16 @@ "value": "bench-ad" }, "expected": false + }, + { + "name": "a web textbox without an editable fact is editable by its role", + "platform": "web", + "text": "bench-ad", + "node": { + "type": "textbox", + "label": "Device name", + "value": "bench-ad" + }, + "expected": false } ] diff --git a/packages/contracts/src/snapshot-text.test.ts b/packages/contracts/src/snapshot-text.test.ts index 332c5d6a8e..1370f5e92b 100644 --- a/packages/contracts/src/snapshot-text.test.ts +++ b/packages/contracts/src/snapshot-text.test.ts @@ -19,3 +19,9 @@ test('unknown fillable type does not establish Android field content', () => { expect(isFillableType('', 'android')).toBe(true); expect(androidFieldValue({ type: '', text: 'Static label' })).toBeUndefined(); }); + +test('a web text input is fillable by its ARIA role, a button is not', () => { + expect(isFillableType('textbox', 'web')).toBe(true); + expect(isFillableType('searchbox', 'web')).toBe(true); + expect(isFillableType('button', 'web')).toBe(false); +}); diff --git a/packages/contracts/src/snapshot-text.ts b/packages/contracts/src/snapshot-text.ts index c14af4f99c..446575ce0d 100644 --- a/packages/contracts/src/snapshot-text.ts +++ b/packages/contracts/src/snapshot-text.ts @@ -20,6 +20,8 @@ export function isFillableType(type: string, platform: Platform | PublicPlatform if (platform === 'android') { return normalized.includes('edittext') || normalized.includes('autocompletetextview'); } + // Web nodes carry ARIA roles: a text input is a `textbox` or `searchbox`. + if (platform === 'web' && (normalized === 'textbox' || normalized === 'searchbox')) return true; return ( normalized.includes('textfield') || normalized.includes('securetextfield') || diff --git a/packages/selectors/src/internal/wait-text.test.ts b/packages/selectors/src/internal/wait-text.test.ts index 728afb493f..8cc829f038 100644 --- a/packages/selectors/src/internal/wait-text.test.ts +++ b/packages/selectors/src/internal/wait-text.test.ts @@ -9,7 +9,7 @@ import { matchesWaitText } from './wait-text.ts'; // same JSON (UnitTests/RunnerTests+InteractionTests.swift). type WaitTextCase = { name: string; - platform?: 'android'; + platform?: 'android' | 'web'; text: string; node: Omit; expected: boolean; From 1112ae79f2de584e7974eed796e66d68d1a91e13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 17:11:26 +0100 Subject: [PATCH 5/8] refactor(selectors): keep the wait text rule in the node predicate module A separate module added one eagerly evaluated module to every importer of the selectors entry, which the closure budget refuses. matchesWaitText now lives beside isNodeEditable, which the closure already evaluates. Co-Authored-By: Claude Opus 5.5 --- packages/selectors/src/index.ts | 2 +- ...it-text.test.ts => node-wait-text.test.ts} | 2 +- packages/selectors/src/internal/node.ts | 25 ++++++++++++++++++- packages/selectors/src/internal/wait-text.ts | 23 ----------------- 4 files changed, 26 insertions(+), 26 deletions(-) rename packages/selectors/src/internal/{wait-text.test.ts => node-wait-text.test.ts} (95%) delete mode 100644 packages/selectors/src/internal/wait-text.ts diff --git a/packages/selectors/src/index.ts b/packages/selectors/src/index.ts index 7396fefe78..0a27c616d3 100644 --- a/packages/selectors/src/index.ts +++ b/packages/selectors/src/index.ts @@ -24,7 +24,7 @@ import { normalizeIsPositionals, } from './internal/predicates.ts'; import { selectorFailureHint, STALE_REF_HINT } from './internal/resolve.ts'; -import { matchesWaitText } from './internal/wait-text.ts'; +import { matchesWaitText } from './internal/node.ts'; import { findBestMatchesByLocator, checkFindArgs, diff --git a/packages/selectors/src/internal/wait-text.test.ts b/packages/selectors/src/internal/node-wait-text.test.ts similarity index 95% rename from packages/selectors/src/internal/wait-text.test.ts rename to packages/selectors/src/internal/node-wait-text.test.ts index 8cc829f038..a12b8362c1 100644 --- a/packages/selectors/src/internal/wait-text.test.ts +++ b/packages/selectors/src/internal/node-wait-text.test.ts @@ -3,7 +3,7 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; import type { SnapshotNode } from '@agent-device/kernel/snapshot'; -import { matchesWaitText } from './wait-text.ts'; +import { matchesWaitText } from './node.ts'; // Golden `wait text` table: the Swift runner's native findText predicate is asserted against the // same JSON (UnitTests/RunnerTests+InteractionTests.swift). diff --git a/packages/selectors/src/internal/node.ts b/packages/selectors/src/internal/node.ts index c06520fc6a..7fe09fad95 100644 --- a/packages/selectors/src/internal/node.ts +++ b/packages/selectors/src/internal/node.ts @@ -1,6 +1,10 @@ import type { Platform, PublicPlatform } from '@agent-device/kernel/device'; import { formatRole, type SnapshotNode } from '@agent-device/kernel/snapshot'; -import { isFillableType, normalizeType } from '@agent-device/contracts/snapshot'; +import { + isFillableType, + matchesSnapshotScope, + normalizeType, +} from '@agent-device/contracts/snapshot'; export function isNodeVisible(node: SnapshotNode): boolean { if (node.hittable === true) return true; @@ -17,6 +21,25 @@ export function isNodeEditable(node: SnapshotNode, platform: Platform | PublicPl return node.editable ?? isFillableType(node.type ?? '', platform); } +/** + * The `wait text` match rule: the snapshot scope rule minus typed content. An editable node's + * value is what the user typed, and Android also reports that text as the node's label, so an + * editable node matches only by its identifier or by a label that is not its value. A value equal + * to the placeholder is the field's hint, not typed text. The Swift runner's native `findText` is + * pinned to the same table, `contracts/fixtures/wait-text-policy.json`. + */ +export function matchesWaitText( + node: SnapshotNode, + text: string, + platform: Platform | PublicPlatform, +): boolean { + if (!isNodeEditable(node, platform) || node.value === node.placeholder) { + return matchesSnapshotScope(node, text); + } + const label = node.label === node.value ? undefined : node.label; + return matchesSnapshotScope({ identifier: node.identifier, label }, text); +} + /** * Every `role=` spelling this node accepts, in ONE place (#3021): the * canonical `kind` vocabulary first, then — during the deprecation window — diff --git a/packages/selectors/src/internal/wait-text.ts b/packages/selectors/src/internal/wait-text.ts deleted file mode 100644 index c95617472c..0000000000 --- a/packages/selectors/src/internal/wait-text.ts +++ /dev/null @@ -1,23 +0,0 @@ -import type { Platform, PublicPlatform } from '@agent-device/kernel/device'; -import type { SnapshotNode } from '@agent-device/kernel/snapshot'; -import { matchesSnapshotScope } from '@agent-device/contracts/snapshot'; -import { isNodeEditable } from './node.ts'; - -/** - * The `wait text` match rule: the snapshot scope rule minus typed content. An editable node's - * value is what the user typed, and Android also reports that text as the node's label, so an - * editable node matches only by its identifier or by a label that is not its value. A value equal - * to the placeholder is the field's hint, not typed text. The Swift runner's native `findText` is - * pinned to the same table, `contracts/fixtures/wait-text-policy.json`. - */ -export function matchesWaitText( - node: SnapshotNode, - text: string, - platform: Platform | PublicPlatform, -): boolean { - if (!isNodeEditable(node, platform) || node.value === node.placeholder) { - return matchesSnapshotScope(node, text); - } - const label = node.label === node.value ? undefined : node.label; - return matchesSnapshotScope({ identifier: node.identifier, label }, text); -} From 1fbe4908c2875a937ea9cf1c4b531d1b0dfd9bbd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 17:12:06 +0100 Subject: [PATCH 6/8] docs(wait): say how wait @ref treats a filled field Co-Authored-By: Claude Opus 5.5 --- website/docs/docs/commands.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/docs/commands.md b/website/docs/docs/commands.md index 24ee261b3b..a82e3681fa 100644 --- a/website/docs/docs/commands.md +++ b/website/docs/docs/commands.md @@ -431,7 +431,7 @@ agent-device alert dismiss - `wait` accepts a millisecond duration, `text `, a snapshot ref (`@eN`), a selector, or strict `absent `. Every form except a plain duration takes an optional `[timeoutMs]`. Selector waits, including those inside `replay`, poll snapshot captures with the same backend and recovery as `is`. `wait` resolves selectors the same way as `click`, `fill`, `get`, and `is`. - `wait absent ` is strict absence, not a visibility check: it passes only when a complete, readable capture has zero matches, so hidden or off-screen matches keep it pending. It rejects `--scope` and `--depth`. Sparse, truncated, incomplete, and Android unreadable-content captures never satisfy it. - `wait text ` matches a node whose label, identifier, or value contains the text, ignoring case. An enabled editable field never matches by its current value, or by a label that only repeats that value. Its identifier, a label distinct from the value, or the placeholder an empty field shows still match. So `wait text` after `fill` waits until the app shows that text elsewhere, for example after Save. To check the field itself, use `is text ` or `get text`. -- `wait @ref` needs a snapshot from a prior `snapshot` command. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. It uses the same text rule. +- `wait @ref` needs a snapshot from a prior `snapshot` command. It resolves the ref to its label or text, then waits for that text, so a duplicate label can match a different element than the original ref. It uses the same text rule, so for a filled field whose text is its typed value it waits for that text to appear elsewhere; to wait for the field itself, use a selector such as `wait 'id="email"'`. - Wait failures carry `error.details.reason` in `--json` output: - `wait_target_absent`: a positive wait never found a match. - `wait_target_present`: strict `wait absent` reached its deadline with valid captures that still contained matches. From b1790c12249d60d967a5e351f404ab81eeaf4d13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 17:20:23 +0100 Subject: [PATCH 7/8] fix(selectors): honor hintShowing before the placeholder fallback in wait text A field that reports its hint hidden holds typed text even when that text equals the placeholder. The placeholder comparison stays the fallback when the producer does not report hint state. Co-Authored-By: Claude Opus 5.5 --- contracts/fixtures/wait-text-policy.json | 14 ++++++++++++++ packages/selectors/src/internal/node.ts | 10 ++++++---- 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/contracts/fixtures/wait-text-policy.json b/contracts/fixtures/wait-text-policy.json index 7f154fa3ff..8ef6a481d5 100644 --- a/contracts/fixtures/wait-text-policy.json +++ b/contracts/fixtures/wait-text-policy.json @@ -99,6 +99,20 @@ }, "expected": true }, + { + "name": "typed text equal to the placeholder does not match when the field reports its hint is hidden", + "platform": "android", + "text": "device name", + "node": { + "type": "android.widget.EditText", + "editable": true, + "hintShowing": false, + "label": "Device name", + "value": "Device name", + "placeholder": "Device name" + }, + "expected": false + }, { "name": "a disabled field's value is app text and matches", "text": "bench-ad", diff --git a/packages/selectors/src/internal/node.ts b/packages/selectors/src/internal/node.ts index 7fe09fad95..6ef0aa8689 100644 --- a/packages/selectors/src/internal/node.ts +++ b/packages/selectors/src/internal/node.ts @@ -24,16 +24,18 @@ export function isNodeEditable(node: SnapshotNode, platform: Platform | PublicPl /** * The `wait text` match rule: the snapshot scope rule minus typed content. An editable node's * value is what the user typed, and Android also reports that text as the node's label, so an - * editable node matches only by its identifier or by a label that is not its value. A value equal - * to the placeholder is the field's hint, not typed text. The Swift runner's native `findText` is - * pinned to the same table, `contracts/fixtures/wait-text-policy.json`. + * editable node matches only by its identifier or by a label that is not its value. A field showing + * its hint (the `hintShowing` fact, else a value equal to the placeholder) holds no typed text. + * The Swift runner's native `findText` is pinned to the same table, + * `contracts/fixtures/wait-text-policy.json`. */ export function matchesWaitText( node: SnapshotNode, text: string, platform: Platform | PublicPlatform, ): boolean { - if (!isNodeEditable(node, platform) || node.value === node.placeholder) { + const showsHint = node.hintShowing ?? node.value === node.placeholder; + if (!isNodeEditable(node, platform) || showsHint) { return matchesSnapshotScope(node, text); } const label = node.label === node.value ? undefined : node.label; From aa5c21bced94f75841ad1b16de39773d7b46a68c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Pierzcha=C5=82a?= Date: Thu, 12 Nov 2026 17:24:48 +0100 Subject: [PATCH 8/8] test(selectors): pin the hintShowing true side of the wait text rule Co-Authored-By: Claude Opus 5.5 --- contracts/fixtures/wait-text-policy.json | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/contracts/fixtures/wait-text-policy.json b/contracts/fixtures/wait-text-policy.json index 8ef6a481d5..17a3adc41d 100644 --- a/contracts/fixtures/wait-text-policy.json +++ b/contracts/fixtures/wait-text-policy.json @@ -113,6 +113,19 @@ }, "expected": false }, + { + "name": "a field that reports its hint showing matches by that hint even without a placeholder", + "platform": "android", + "text": "device name", + "node": { + "type": "android.widget.EditText", + "editable": true, + "hintShowing": true, + "label": "Device name", + "value": "Device name" + }, + "expected": true + }, { "name": "a disabled field's value is app text and matches", "text": "bench-ad",