diff --git a/.changeset/mobile-window-origin-not-actionable.md b/.changeset/mobile-window-origin-not-actionable.md new file mode 100644 index 000000000..57bda687e --- /dev/null +++ b/.changeset/mobile-window-origin-not-actionable.md @@ -0,0 +1,5 @@ +--- +'@e2e-dev/mobile': patch +--- + +An iOS action on a node that agent-device refuses with `window-origin-unknown` now fails as `ACTION_FAILED` (`NOT_ACTIONABLE`) instead of an infrastructure `ENGINE_FAILURE`. agent-device sent nothing, and for a tap the message names `screen.tapAt()`, which agent-device still takes. diff --git a/packages/mobile/src/errors.ts b/packages/mobile/src/errors.ts index cc37936d2..637e7c539 100644 --- a/packages/mobile/src/errors.ts +++ b/packages/mobile/src/errors.ts @@ -11,6 +11,7 @@ * | a stale-ref refusal by `details.reason` (action paths only) | NODE_STALE (retryable) | * | target_still_moving with `details.dispatched: no` | NODE_STALE (retryable) | * | a covered or keyboard-occluded target, `dispatched: no` | NOT_ACTIONABLE, with the hint | + * | a target with no screen origin to aim at, `dispatched: no` | NOT_ACTIONABLE, with the hint | * | the iOS runner busy, wedged, or past its watchdog | ENGINE_FAILURE, naming the | * | a snapshot the iOS runner acquired but could not present | runner and the recovery | * | anything else, agent-device's own timeouts included | ENGINE_FAILURE with the text | @@ -94,13 +95,24 @@ const STALE_REF_REASONS: ReadonlySet = new Set([ ]); /** - * The `details.reason` values agent-device refuses an action with when - * something else is drawn where the touch would land: an overlay its - * occlusion scan found over the target (`coveredBy` names it), or the soft - * keyboard over the target's touch point. Nothing was sent, and the app is - * fine; the test has to move the cover or the target first. + * The `details.reason` values agent-device refuses an action with, nothing + * sent, on a healthy device, each with the hint the failure carries: + * `undefined` keeps agent-device's own, and a string replaces it. + * + * - `target_covered`, `tap_keyboard_occludes_target`: an overlay its + * occlusion scan found over the target (`coveredBy` names it), or the soft + * keyboard over the target's touch point. The test has to move the cover + * or the target first, and agent-device's hint says how. + * - `window-origin-unknown` (0.21.37): the capture the ref came from could not + * place its window on the screen. agent-device's hint names its CLI + * (`snapshot`, `screenshot`); a point tap is not aimed from the capture, and + * agent-device takes it. */ -const OCCLUDED_REASONS: ReadonlySet = new Set(['target_covered', 'tap_keyboard_occludes_target']); +const NOT_ACTIONABLE_REASONS: ReadonlyMap = new Map([ + ['target_covered', undefined], + ['tap_keyboard_occludes_target', undefined], + ['window-origin-unknown', 'Nothing was sent. For a tap, tap the point instead with screen.tapAt().'], +]); /** * What the iOS automation runner reported about itself, by the code @@ -295,9 +307,9 @@ export async function runCommand(label: string, work: () => Promise, signa * stale-ref reasons are sufficient on their own: Android dialog recovery can * mark a refused drag as `dispatched: unknown`. A `target_still_moving` refusal * additionally requires `dispatched: no`; missing or unknown dispatch is not retryable. - * A target agent-device refused as covered (`OCCLUDED_REASONS`) with nothing - * dispatched is `NOT_ACTIONABLE`: the test's own failure, with the hint that - * names the cover, never an infrastructure one. + * A target agent-device refused for a reason in `NOT_ACTIONABLE_REASONS` with + * nothing dispatched is `NOT_ACTIONABLE`, with the move that gets past it: an + * action failure on a healthy device, never an infrastructure one. */ export function staleOr(cause: unknown, operation: string, where?: string): Error { if (isClassified(cause)) return cause; @@ -306,8 +318,10 @@ export function staleOr(cause: unknown, operation: string, where?: string): Erro (reason === 'target_still_moving' && dispatched === 'no')) { return new EngineError('NODE_STALE', `${operation}: ${message(cause)}`, { retryable: true, cause }); } - if (typeof reason === 'string' && OCCLUDED_REASONS.has(reason) && dispatched === 'no') { - return new EngineError('NOT_ACTIONABLE', `${operation} failed: ${withHint(cause, message(cause))}`, { retryable: false, cause }); + if (typeof reason === 'string' && NOT_ACTIONABLE_REASONS.has(reason) && dispatched === 'no') { + const hint = NOT_ACTIONABLE_REASONS.get(reason); + const text = hint === undefined ? withHint(cause, message(cause)) : `${message(cause)} Hint: ${hint}`; + return new EngineError('NOT_ACTIONABLE', `${operation} failed: ${text}`, { retryable: false, cause }); } return translateError(cause, operation, where); } diff --git a/packages/mobile/tests/unit/errors.test.ts b/packages/mobile/tests/unit/errors.test.ts index 1e5fb9c1f..20e02b325 100644 --- a/packages/mobile/tests/unit/errors.test.ts +++ b/packages/mobile/tests/unit/errors.test.ts @@ -121,6 +121,20 @@ describe('error translation', () => { }); }); + // As agent-device 0.21.37 sends it for a ref aimed from a capture without the window's screen origin. + it('fails an action agent-device refused as window-origin-unknown with NOT_ACTIONABLE and the tapAt move', () => { + const text = 'Ref @e2 has no established screen-coordinate origin'; + const hint = 'Take a fresh snapshot after the accessibility channel recovers, or use screenshot to choose screen coordinates.'; + const refused = new AppError('COMMAND_FAILED', text, { reason: 'window-origin-unknown', hint, dispatched: 'no' }); + const failure = staleOr(refused, 'perform tap'); + expect(failure).toMatchObject({ code: 'NOT_ACTIONABLE', retryable: false, cause: refused }); + // agent-device's hint names its CLI; the failure names the test's move instead. + expect(failure.message).toBe(`perform tap failed: ${text} Hint: Nothing was sent. For a tap, tap the point instead with screen.tapAt().`); + expect( + staleOr(new AppError('COMMAND_FAILED', text, { reason: 'window-origin-unknown', hint, dispatched: 'unknown' }), 'perform tap'), + ).toMatchObject({ code: 'ENGINE_FAILURE' }); + }); + it('maps the rest to ENGINE_FAILURE with the text, a ref named in a message without a stale reason included', () => { expect(staleOr(new Error('ref @e12 not found in the current snapshot'), 'perform tap')).toMatchObject({ code: 'ENGINE_FAILURE',