Skip to content

Commit 2b2ee58

Browse files
committed
fix(maestro): refresh target after selector miss
1 parent 80b4769 commit 2b2ee58

13 files changed

Lines changed: 140 additions & 8 deletions

File tree

‎packages/contracts/src/facades/interaction.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ export {
7272
INTERACTION_GUARANTEES,
7373
INTERACTION_PATH_IDS,
7474
} from '../interaction-guarantees.ts';
75+
export { INTERACTION_ERROR_REASONS } from '../interaction-error.ts';
7576
export type {
7677
GuaranteeEnforcement,
7778
InteractionGuarantee,
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/** Machine-readable `error.details.reason` values shared by interaction producers and adapters. */
2+
export const INTERACTION_ERROR_REASONS = {
3+
selectorNotFound: 'selector_not_found',
4+
} as const;

‎packages/maestro/src/internal/support-matrix.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
export const MAESTRO_COMPAT_SUPPORTED_CAPABILITIES = [
22
'Flows: launchApp; runFlow file/inline with platform, visibility, and limited boolean conditions; onFlowStart/onFlowComplete; repeat.times and retry.',
3-
'Interactions: tapOn, doubleTapOn, longPressOn, inputText, eraseText, openLink, hideKeyboard, basic pressKey, and back; targets support index, childOf, label, points, and optional.',
3+
'Interactions: tapOn, doubleTapOn, longPressOn, inputText on the focused element, eraseText, openLink, hideKeyboard, basic pressKey, and back; tap targets poll until available and support index, childOf, label, points, and optional.',
44
'Assertions and navigation: assertVisible, assertNotVisible, extendedWaitUntil, scroll, scrollUntilVisible, absolute/percentage/target swipe, takeScreenshot, waitForAnimationToEnd, and stopApp.',
55
'Scripts: ordered runScript file/env scripts with http.post, json, and output variables.',
66
] as const;

‎src/cli-schema/cli-help-command-usage.test.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -240,6 +240,7 @@ test('command usage describes delayed typing flags', async () => {
240240
assert.match(typeHelp, /--delay-ms <ms>/);
241241
assert.match(fillHelp, /--delay-ms <ms>/);
242242
assert.match(fillHelp, /--record-as <VAR>/);
243+
assert.match(fillHelp, /label="Email" editable=true/);
243244
});
244245

245246
test('snapshot command usage documents diff alias', async () => {

‎src/cli-schema/cli-help-topics.test.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,8 @@ test('usageForCommand resolves Maestro compatibility help topic', async () => {
103103
assert.match(help, /Supported subset:/);
104104
assert.match(help, /runFlow file\/inline/);
105105
assert.match(help, /tapOn, doubleTapOn, longPressOn/);
106+
assert.match(help, /inputText on the focused element/);
107+
assert.match(help, /tap targets poll until available/);
106108
assert.match(help, /Boundaries:/);
107109
assert.match(help, /iOS and Android only/);
108110
assert.match(help, /AD_VAR_\* overrides it/);
@@ -474,6 +476,8 @@ test('usageForCommand resolves manual QA help topic', async () => {
474476
assert.match(help, /A bare screenshot\/snapshot is not verification/);
475477
assert.match(help, /use fill <target> <text> --settle to replace/);
476478
assert.match(help, /use type only to append to an already-focused field/);
479+
assert.match(help, /label="Email" editable=true/);
480+
assert.match(help, /press 'label="Follow"' --settle/);
477481
assert.match(help, /Do not use placeholders such as @ref/);
478482
assert.match(help, /wait_target_absent: a readable capture ran and found no match/);
479483
assert.match(help, /wait_capture_stalled: no readable capture finished before the deadline/);

‎src/cli-schema/cli-help.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,14 +89,14 @@ Command shapes:
8989
agent-device open https://example.com/deep-link
9090
agent-device snapshot -i
9191
agent-device press @e12 --settle
92-
agent-device press 'label="Follow"'
92+
agent-device press 'label="Follow"' --settle
9393
agent-device fill @e13 "[email protected]" --settle
9494
agent-device wait text "Order placed" 3000
9595
agent-device close
9696
--relaunch forces fresh app state; a deep link/URL open does not need it. Labels with an apostrophe or quote (label="Don't leave") are shell-quoting hazards: prefer the @ref from the latest snapshot/settle output over quoting the literal label.
9797
9898
Targets:
99-
Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow".
99+
Prefer refs from the latest snapshot -i or settled diff. Use durable selectors when the label/id is known: label="Search", id="submit", role=button label="Follow". If label text matches both a field and its caption, target the field with label="Email" editable=true.
100100
For text fields, use fill <target> <text> --settle to replace the field value; use type only to append to an already-focused field.
101101
Do not use placeholders such as @ref, @eN, <button>, or <selector> in a final command plan. If the ref is unknown, first run snapshot -i.
102102
Coordinates are fallback-only after refs/selectors fail or accessibility omits the target; use screenshot or snapshot -i --json to choose a visible center point.

‎src/commands/interaction/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,8 @@ const fillCommandFacet = defineCommandFacet({
248248
name: 'fill',
249249
text: {
250250
summary: 'Replace text in a UI input',
251+
cliDetail:
252+
'When visible label text also matches a non-input element, constrain the target with editable=true, for example fill \'label="Email" editable=true\' "[email protected]".',
251253
},
252254
metadata: metadata('fill'),
253255
definition: fillCommandDefinition,

‎src/commands/interaction/runtime/resolution.test.ts‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import {
1010
import { resolveRecordedTarget } from '@agent-device/selectors';
1111
import { makeSnapshotState } from '../../../__tests__/test-utils/index.ts';
1212
import type { Point } from '@agent-device/kernel/snapshot';
13+
import { INTERACTION_ERROR_REASONS } from '@agent-device/contracts/interaction';
1314
import {
1415
clickRefE2,
1516
coveredByTabBarSnapshot,
@@ -87,6 +88,21 @@ test('runtime selector interactions fall back to a full snapshot when interactiv
8788
]);
8889
});
8990

91+
test('runtime selector misses carry a structured reason for retrying adapters', async () => {
92+
const device = createInteractionDevice(makeSnapshotState([]));
93+
94+
await assert.rejects(
95+
() => device.interactions.press(selector('id="profile-button"'), { session: 'default' }),
96+
(error: unknown) => {
97+
assert.equal(
98+
(error as { details?: Record<string, unknown> }).details?.reason,
99+
INTERACTION_ERROR_REASONS.selectorNotFound,
100+
);
101+
return true;
102+
},
103+
);
104+
});
105+
90106
test('runtime press refuses a selector that resolves to an off-screen element', async () => {
91107
// Closed-drawer shape: the only match sits fully left of the viewport. The
92108
// @ref path already refuses this; the selector path must not silently tap

‎src/commands/interaction/runtime/resolution.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@ import type {
4848
ResolutionDisclosure,
4949
ResolvedInteractionTarget,
5050
} from '@agent-device/contracts/interaction';
51+
import { INTERACTION_ERROR_REASONS } from '@agent-device/contracts/interaction';
5152
import type {
5253
BackendActionResult,
5354
BackendCommandContext,
@@ -437,7 +438,10 @@ async function selectorInteractionFailure(params: {
437438
return new AppError(
438439
'COMMAND_FAILED',
439440
formatSelectorFailure(selectorExpression, diagnostics, { unique: true }),
440-
{ hint: selectorFailureHint(diagnostics) },
441+
{
442+
reason: INTERACTION_ERROR_REASONS.selectorNotFound,
443+
hint: selectorFailureHint(diagnostics),
444+
},
441445
);
442446
}
443447

‎src/commands/interaction/runtime/selector-read.ts‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ import type {
2828
ResolvedTarget,
2929
SelectorTarget,
3030
} from '@agent-device/contracts/interaction';
31+
import { INTERACTION_ERROR_REASONS } from '@agent-device/contracts/interaction';
3132
import type { RuntimeCommand } from '../../runtime-types.ts';
3233
import { assertExpectedResolvedTarget, type ExpectedResolvedTarget } from './resolution.ts';
3334
import {
@@ -346,7 +347,7 @@ export const isCommand: RuntimeCommand<IsCommandOptions, IsCommandResult> = asyn
346347
formatSelectorFailure(selectorExpression, [], { unique: true }),
347348
{
348349
command: 'is',
349-
reason: 'selector_not_found',
350+
reason: INTERACTION_ERROR_REASONS.selectorNotFound,
350351
predicate: predicate,
351352
selector: selectorExpression,
352353
hint: selectorFailureHint([]),

0 commit comments

Comments
 (0)