diff --git a/.changeset/mobile-stale-after-dispatch.md b/.changeset/mobile-stale-after-dispatch.md new file mode 100644 index 0000000000..5b22d38457 --- /dev/null +++ b/.changeset/mobile-stale-after-dispatch.md @@ -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. diff --git a/packages/mobile/src/errors.ts b/packages/mobile/src/errors.ts index 32bb364ab8..736f3e267f 100644 --- a/packages/mobile/src/errors.ts +++ b/packages/mobile/src/errors.ts @@ -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 | @@ -280,17 +281,32 @@ export async function runCommand(label: string, work: () => Promise, 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); diff --git a/packages/mobile/tests/unit/engine.test.ts b/packages/mobile/tests/unit/engine.test.ts index 0de7659a81..a1c21a9787 100644 --- a/packages/mobile/tests/unit/engine.test.ts +++ b/packages/mobile/tests/unit/engine.test.ts @@ -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'); @@ -1406,6 +1406,17 @@ 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'); }); @@ -1413,6 +1424,8 @@ describe('perform', () => { 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); }); }); diff --git a/packages/mobile/tests/unit/errors.test.ts b/packages/mobile/tests/unit/errors.test.ts index dbed01e094..dc1316c393 100644 --- a/packages/mobile/tests/unit/errors.test.ts +++ b/packages/mobile/tests/unit/errors.test.ts @@ -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',