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-stale-after-dispatch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@e2e-dev/mobile": patch
---

A stale-ref refusal that cannot prove nothing was dispatched is now `ACTION_MAY_HAVE_COMMITTED` instead of retryable `NODE_STALE`, so a tap that already reached the app (a drawer toggle, with the stale report arriving during the post-tap settle) is never sent again and the step fails at once instead of re-resolving until `LOCATOR_NOT_FOUND`. Only refusals with `dispatched: no` stay retryable.
32 changes: 24 additions & 8 deletions packages/mobile/src/errors.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@
* | SESSION_NOT_FOUND, or a session-or-device-selector refusal | INVALID_STATE |
* | UNSUPPORTED_OPERATION, NOT_IMPLEMENTED, UNSUPPORTED_PLATFORM | UNSUPPORTED_CAPABILITY |
* | "not supported on this device" under any code | UNSUPPORTED_CAPABILITY |
* | a stale-ref refusal by `details.reason` (action paths only) | NODE_STALE (retryable) |
* | a stale-ref refusal, `dispatched: no` (action paths only) | NODE_STALE (retryable) |
* | a stale-ref refusal with dispatch unproven (action paths) | ACTION_MAY_HAVE_COMMITTED |
* | target_still_moving with `details.dispatched: no` | NODE_STALE (retryable) |
* | 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 |
Expand Down Expand Up @@ -280,17 +281,32 @@ export async function runCommand<T>(label: string, work: () => Promise<T>, signa

/**
* Like translateError, but a ref agent-device refused as stale becomes
* retryable `NODE_STALE`: nothing was dispatched, so the harness may
* re-observe and re-resolve the node instead of failing the action. Existing
* 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.
* retryable `NODE_STALE` only when it proves nothing was dispatched
* (`details.dispatched: 'no'`): the ref was refused at admission, before the
* gesture, so the harness may re-observe and re-resolve the node instead of
* failing the action. A stale-ref refusal that cannot prove that is
* `ACTION_MAY_HAVE_COMMITTED`: the gesture may already have landed (a tap
* that opened a drawer, with the stale report arriving during the post-tap
* settle), so the harness must not send it again. That includes the Android
* dialog-recovery shape, a drag refused before the gesture but reported as
* `dispatched: 'unknown'`: the engine cannot prove the drag never ran, so it
* fails closed the same way. A `target_still_moving` refusal additionally
* requires `dispatched: no`; missing or unknown dispatch is not retryable.
*/
export function staleOr(cause: unknown, operation: string, where?: string): Error {
if (isClassified(cause)) return cause;
const { reason, dispatched } = details(cause);
if ((typeof reason === 'string' && STALE_REF_REASONS.has(reason)) ||
(reason === 'target_still_moving' && dispatched === 'no')) {
if (typeof reason === 'string' && STALE_REF_REASONS.has(reason)) {
if (dispatched === 'no') {
return new EngineError('NODE_STALE', `${operation}: ${message(cause)}`, { retryable: true, cause });
}
return new EngineError(
'ACTION_MAY_HAVE_COMMITTED',
`${operation}: ${message(cause)}; the action may already have reached the device, so it was not sent again`,
{ retryable: false, cause },
);
}
if (reason === 'target_still_moving' && dispatched === 'no') {
return new EngineError('NODE_STALE', `${operation}: ${message(cause)}`, { retryable: true, cause });
}
return translateError(cause, operation, where);
Expand Down
15 changes: 14 additions & 1 deletion packages/mobile/tests/unit/engine.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1372,7 +1372,7 @@ describe('perform', () => {
]);
});

it('refuses what a device surface cannot express, and reports daemon ref misses as retryable', async () => {
it('refuses what a device surface cannot express, and classifies daemon ref misses by whether the press was sent', async () => {
const h = harness();
await openAttempt(h);
const about = await observed(h, 'About');
Expand Down Expand Up @@ -1406,13 +1406,26 @@ describe('perform', () => {
code: 'NODE_STALE',
retryable: true,
});
// A stale ref reported after the press was sent: the tap may have landed
// (a drawer toggle, with the stale report arriving during the post-tap
// settle), so the engine reports the action as possibly committed and the
// runner never sends it again.
h.fake.respond('interactions.press', () => {
throw new AppError('COMMAND_FAILED', 'Ref @e4 belongs to an expired ref frame', { reason: 'ref_frame_expired', dispatched: 'unknown' });
});
await expect(h.engine.perform!(about.ref, { kind: 'tap' }, operation())).rejects.toMatchObject({
code: 'ACTION_MAY_HAVE_COMMITTED',
retryable: false,
});
h.fake.respond('interactions.press', () => {
throw new AppError('COMMAND_FAILED', 'XCTest lost the runner');
});
await expect(h.engine.perform!(about.ref, { kind: 'tap' }, operation())).rejects.toMatchObject({
code: 'ENGINE_FAILURE',
retryable: false,
});
// One press per perform: the engine never retries a possibly committed tap itself.
expect(h.fake.methods().filter((method) => method === 'interactions.press')).toHaveLength(3);
});
});

Expand Down
32 changes: 29 additions & 3 deletions packages/mobile/tests/unit/errors.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -71,21 +71,47 @@ describe('error translation', () => {
});

// Each refusal as agent-device 0.21.21 sends it: the typed reason, and the message the reason replaces.
// Only a refusal that proves nothing reached the device (`dispatched: 'no'`)
// is a retryable stale node: the ref was refused at admission, before the gesture.
it.each([
['ref_not_found', 'Ref @e12 not found', 'no'],
['ref_frame_expired', 'Ref @e12 belongs to an expired ref frame — a device action since the snapshot invalidated it', 'no'],
['ref_generation_mismatch', 'Ref @e12 was minted from a superseded snapshot generation', 'no'],
['plain_ref_requires_complete_frame', 'Ref @e12 needs a complete snapshot — the current frame only authorizes its emitted refs', 'no'],
['ref_not_issued', 'Ref @e12 was not issued by the current ref frame', 'no'],
// After Android blocking-dialog recovery, a drag refuses its stale ref before the gesture but reports it as `unknown`.
['ref_frame_expired', 'Ref @e12 belongs to an expired ref frame — a device action since the snapshot invalidated it', 'unknown'],
] as const)('maps the stale-ref refusal %s (dispatched: %s) to retryable NODE_STALE', (reason, text, dispatched) => {
] as const)('maps the stale-ref refusal %s (dispatched: no) to retryable NODE_STALE', (reason, text, dispatched) => {
const refused = new AppError('COMMAND_FAILED', text, { reason, dispatched });
expect(staleOr(refused, 'perform tap')).toMatchObject({ code: 'NODE_STALE', retryable: true, message: `perform tap: ${text}` });
// Outside an action path the same refusal stays an engine failure.
expect(translateError(refused, 'observe')).toMatchObject({ code: 'ENGINE_FAILURE' });
});

// A stale-ref refusal that cannot prove nothing was dispatched is a possibly
// committed action, never a retryable stale node: the gesture may already
// have landed (a tap that opened a drawer, with the stale report arriving
// during the post-tap settle), so the harness must not send it again.
// That includes the Android blocking-dialog recovery shape, a drag refused
// before the gesture but reported as `dispatched: unknown`: the engine
// cannot prove the drag never ran, so it fails closed the same way.
it.each([
['ref_frame_expired', 'Ref @e12 belongs to an expired ref frame — a device action since the snapshot invalidated it', 'unknown'],
['ref_generation_mismatch', 'Ref @e12 was minted from a superseded snapshot generation', undefined],
] as const)(
'reports a stale-ref refusal with unproven dispatch as ACTION_MAY_HAVE_COMMITTED (%s, %s)',
(reason, text, dispatched) => {
const refused = new AppError('COMMAND_FAILED', text, {
reason,
...(dispatched === undefined ? {} : { dispatched }),
});
expect(staleOr(refused, 'perform tap')).toMatchObject({
code: 'ACTION_MAY_HAVE_COMMITTED',
retryable: false,
cause: refused,
message: `perform tap: ${text}; the action may already have reached the device, so it was not sent again`,
});
},
);

it.each(['no', 'unknown', undefined] as const)('retries a moving target only when no input was dispatched (%s)', (dispatched) => {
const cause = new AppError('COMMAND_FAILED', 'Target position was not confirmed', {
reason: 'target_still_moving',
Expand Down
Loading