From c076670cb081d5604834d6bfad67f61785339e69 Mon Sep 17 00:00:00 2001 From: Tim Shamilov Date: Tue, 20 Oct 2026 18:32:24 -0400 Subject: [PATCH 1/3] fix(mobile): reject stale refs after transition refresh --- .changeset/mobile-stale-transition-ref.md | 5 ++++ docs/reference/mobile.mdx | 4 +++ packages/mobile/src/surface.ts | 9 ++++-- packages/mobile/tests/unit/engine.test.ts | 35 +++++++++++++++++++++-- 4 files changed, 48 insertions(+), 5 deletions(-) create mode 100644 .changeset/mobile-stale-transition-ref.md diff --git a/.changeset/mobile-stale-transition-ref.md b/.changeset/mobile-stale-transition-ref.md new file mode 100644 index 0000000000..c9f9ac3a03 --- /dev/null +++ b/.changeset/mobile-stale-transition-ref.md @@ -0,0 +1,5 @@ +--- +"@e2e-dev/mobile": patch +--- + +Re-resolve a locator when its target changes during the transition wait, instead of tapping a stale native reference that may now identify another control. diff --git a/docs/reference/mobile.mdx b/docs/reference/mobile.mdx index eac41a0249..e548769080 100644 --- a/docs/reference/mobile.mdx +++ b/docs/reference/mobile.mdx @@ -227,6 +227,10 @@ readonly transition?: number | undefined; mobile({ platform: 'ios', transition: 800 }); // default: 500 ``` +If the refreshed snapshot no longer matches the control, the action re-resolves +its locator within the existing timeout before sending input. It never uses a +reference from the earlier snapshot when that match is lost. + `back`, `home`, `alert`, `dismissKeyboard`, `setOrientation`, and `fold` on [`device`](#device) change the screen, so they count as actions for this budget the way a tap does. A control that arrives with the screen they reveal diff --git a/packages/mobile/src/surface.ts b/packages/mobile/src/surface.ts index 55fe403c1e..c7870c0639 100644 --- a/packages/mobile/src/surface.ts +++ b/packages/mobile/src/surface.ts @@ -1152,11 +1152,16 @@ export class AgentDeviceSurface { return this.relocated(entry, operation); } - /** The same control in a fresh snapshot; the binding as it was when the snapshot no longer lists it. */ + /** The same control in a fresh snapshot; otherwise re-resolve before sending input. */ private async relocated(entry: NodeBinding, operation: OperationContext): Promise { const projected = this.project(await this.snapshotOrEmpty(operation, false)); const found = this.refind(entry, projected.index); - return found === undefined ? entry : this.bind(found, projected.index); + // A fresh snapshot can assign the old numeric ref to a different control. + // Let the locator re-resolve instead of dispatching input to that ref. + if (found === undefined) { + throw new EngineError('NODE_STALE', 'target changed during transition; re-resolve', { retryable: true }); + } + return this.bind(found, projected.index); } /** diff --git a/packages/mobile/tests/unit/engine.test.ts b/packages/mobile/tests/unit/engine.test.ts index e978d642e7..cf157c403a 100644 --- a/packages/mobile/tests/unit/engine.test.ts +++ b/packages/mobile/tests/unit/engine.test.ts @@ -2279,13 +2279,42 @@ describe('deterministic actions', () => { await h.engine.perform!(inFlight.ref, { kind: 'tap' }, test()); expect(h.fake.lastArgs('interactions.press')).toEqual({ ref: '@e42' }); - // A control the fresh snapshot no longer lists is acted on as it was. + // A missing control must be resolved again before any input is dispatched. + h.fake.respond('capture.snapshot', () => SETTINGS_SNAPSHOT); await h.engine.perform!((await observed(h, 'Back')).ref, { kind: 'tap' }, test()); h.fake.respond('capture.snapshot', () => submit(600, '@e42')); const landed = await observed(h, 'Submit'); h.fake.respond('capture.snapshot', () => SETTINGS_SNAPSHOT); - await h.engine.perform!(landed.ref, { kind: 'tap' }, test()); - expect(h.fake.lastArgs('interactions.press')).toEqual({ ref: '@e42' }); + const presses = h.fake.methods().filter((method) => method === 'interactions.press').length; + await expect(h.engine.perform!(landed.ref, { kind: 'tap' }, test())).rejects.toMatchObject({ code: 'NODE_STALE', retryable: true }); + expect(h.fake.methods().filter((method) => method === 'interactions.press')).toHaveLength(presses); + }); + + it('does not tap a recycled ref when a native button becomes a tab during relocation', async () => { + autoAdvanceTimers(); + const h = harness({ transition: 120 }); + await openAttempt(h); + await h.engine.perform!((await observed(h, 'Back')).ref, { kind: 'tap' }, test()); + h.fake.respond('capture.snapshot', () => ({ + ...SETTINGS_SNAPSHOT, + nodes: [...SETTINGS_NODES, { ref: '@e11', index: 10, parentIndex: 0, depth: 1, type: 'button', label: 'Chat' }], + })); + const chat = await observed(h, 'Chat'); + h.fake.respond('capture.snapshot', () => ({ + ...SETTINGS_SNAPSHOT, + nodes: [ + ...SETTINGS_NODES, + { ref: '@e10', index: 10, parentIndex: 0, depth: 1, type: 'tab-bar' }, + { ref: '@e12', index: 11, parentIndex: 10, depth: 2, type: 'button', label: 'Chat' }, + { ref: '@e11', index: 12, parentIndex: 10, depth: 2, type: 'button', label: 'Orders' }, + ], + })); + const presses = h.fake.methods().filter((method) => method === 'interactions.press').length; + await expect(h.engine.perform!(chat.ref, { kind: 'tap' }, test())).rejects.toMatchObject({ code: 'NODE_STALE', retryable: true }); + expect(h.fake.methods().filter((method) => method === 'interactions.press')).toHaveLength(presses); + + await h.engine.perform!((await observed(h, 'Chat')).ref, { kind: 'tap' }, test()); + expect(h.fake.lastArgs('interactions.press')).toEqual({ ref: '@e12' }); }); it('acts on the duplicate nearest where the control was when a fresh snapshot lists several alike', async () => { From ce2aabfe9223ce8ae7e52b6d436c64627c348b42 Mon Sep 17 00:00:00 2001 From: Tim Shamilov Date: Sun, 25 Oct 2026 22:20:53 -0400 Subject: [PATCH 2/3] docs(mobile): clarify locator retry after transition refresh --- docs/reference/mobile.mdx | 4 +--- packages/mobile/src/surface.ts | 9 ++++----- 2 files changed, 5 insertions(+), 8 deletions(-) diff --git a/docs/reference/mobile.mdx b/docs/reference/mobile.mdx index e548769080..99aa5801b3 100644 --- a/docs/reference/mobile.mdx +++ b/docs/reference/mobile.mdx @@ -227,9 +227,7 @@ readonly transition?: number | undefined; mobile({ platform: 'ios', transition: 800 }); // default: 500 ``` -If the refreshed snapshot no longer matches the control, the action re-resolves -its locator within the existing timeout before sending input. It never uses a -reference from the earlier snapshot when that match is lost. +If the control changes during the wait, the action finds it again within its timeout before tapping. `back`, `home`, `alert`, `dismissKeyboard`, `setOrientation`, and `fold` on [`device`](#device) change the screen, so they count as actions for this diff --git a/packages/mobile/src/surface.ts b/packages/mobile/src/surface.ts index c7870c0639..8a98093cec 100644 --- a/packages/mobile/src/surface.ts +++ b/packages/mobile/src/surface.ts @@ -1127,8 +1127,9 @@ export class AgentDeviceSurface { * present at the same place in the snapshot the last action was resolved * from is not in transition and is acted on at once; anything else waits * out the remainder of the transition budget since that action and is then - * found again in a fresh snapshot. The budget is the only signal that the - * transition is over, since the tree cannot tell a sliding control from a + * found again in a fresh snapshot. If it no longer lists the control, a + * retryable stale error lets the locator resolve again. The budget is the + * only signal that the transition is over, since the tree cannot tell a sliding control from a * landed one; the fresh snapshot is where the control landed. Android * reports a window's frames while it slides in, so a ref resolved * mid-flight would send the action where the control was: below the @@ -1152,12 +1153,10 @@ export class AgentDeviceSurface { return this.relocated(entry, operation); } - /** The same control in a fresh snapshot; otherwise re-resolve before sending input. */ + /** The same control in a fresh snapshot; retryable NODE_STALE when it no longer lists it, so the locator resolves again. */ private async relocated(entry: NodeBinding, operation: OperationContext): Promise { const projected = this.project(await this.snapshotOrEmpty(operation, false)); const found = this.refind(entry, projected.index); - // A fresh snapshot can assign the old numeric ref to a different control. - // Let the locator re-resolve instead of dispatching input to that ref. if (found === undefined) { throw new EngineError('NODE_STALE', 'target changed during transition; re-resolve', { retryable: true }); } From 1454929f42e405ff99823c89163abe7e6cf8146d Mon Sep 17 00:00:00 2001 From: Tim Shamilov Date: Sun, 25 Oct 2026 22:32:41 -0400 Subject: [PATCH 3/3] docs(mobile): cover all targeted transition actions --- docs/reference/mobile.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/mobile.mdx b/docs/reference/mobile.mdx index 99aa5801b3..42062d746a 100644 --- a/docs/reference/mobile.mdx +++ b/docs/reference/mobile.mdx @@ -227,7 +227,7 @@ readonly transition?: number | undefined; mobile({ platform: 'ios', transition: 800 }); // default: 500 ``` -If the control changes during the wait, the action finds it again within its timeout before tapping. +If the control changes during the wait, the action finds it again within its timeout before acting. `back`, `home`, `alert`, `dismissKeyboard`, `setOrientation`, and `fold` on [`device`](#device) change the screen, so they count as actions for this