Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/mobile-window-origin-not-actionable.md
Original file line number Diff line number Diff line change
@@ -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.
36 changes: 25 additions & 11 deletions packages/mobile/src/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -94,13 +95,24 @@ const STALE_REF_REASONS: ReadonlySet<string> = 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<string> = new Set(['target_covered', 'tap_keyboard_occludes_target']);
const NOT_ACTIONABLE_REASONS: ReadonlyMap<string, string | undefined> = 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
Expand Down Expand Up @@ -295,9 +307,9 @@ export async function runCommand<T>(label: string, work: () => Promise<T>, 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;
Expand All @@ -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);
}
14 changes: 14 additions & 0 deletions packages/mobile/tests/unit/errors.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down
Loading