Skip to content

performUntil retries a tap that already reached the app after NODE_STALE, then fails with LOCATOR_NOT_FOUND after the full timeout #1637

Open

Description

@arekkubaczkowski

Summary

LocatorEngine.performUntil (e2e 0.18.0, dist/locator/engine.js) retries a tap after session.perform rejects with a retryable NODE_STALE, even when the tap was already dispatched and reached the app. If that tap changes the screen so the target is no longer present (a toggle that opens a drawer over it, a button that navigates away), the retry calls resolveExactlyOne again for a node that is gone. It then waits the whole action timeout and fails with LOCATOR_NOT_FOUND, although the action succeeded.

Where

async performUntil(expression, action, deadline) {
  for (;;) {
    const ref = await this.resolveExactlyOne(expression, deadline);
    ...
    try { await this.session.perform(ref, resolved, this.operationWithin(deadline)); return; }
    catch (cause) {
      const engineError = asEngineError(cause);
      if (engineError?.code === 'NODE_STALE' && engineError.retryable && !deadline.expired()) continue;   // <- also after a dispatched tap
      throw translateLocatorError(cause, expression);
    }
  }
}

Observed (iOS simulator, a drawer-toggle button)

  • The app's own log shows the tap was received (the drawer-open action fires 71–86 ms after the tap, the same as in passing runs).
  • The step then fails exactly actionTimeout (60 s) later with LOCATOR_NOT_FOUND ... within getByRole("button", { name: /^Menu$/ }): the button is now behind the open drawer.
  • Rate in our runs: from about 1 in 15 runs to 4 in 6, depending on host load (the window between dispatch and the stale report).

Expected

A NODE_STALE that arrives after the action was dispatched should not cause a blind second resolve + perform of the same action. Options:

  1. distinguish "stale before dispatch" (safe to retry) from "stale after dispatch" (report as done, or as a distinct error the caller can check), or
  2. let the caller pass a post-condition (until) that is checked before any retry.

Workaround we use

A wrapper that taps once with a short timeout and, on NODE_STALE, checks the step's own post-condition (for example, the drawer is visible) before retrying; it never taps a landed toggle twice.

Activity

  1. Varshith-Kali commented on Nov 8, 2026

    @Varshith-Kali
    Contributor

    Hi, I would like to take this one on. I can reproduce the performUntil retry-after-NODE_STALE behaviour and fix it so a tap that already reached the app is not retried into a LOCATOR_NOT_FOUND failure, with regression tests. Could you please assign it to me?

  2. okwasniewski commented on Nov 8, 2026

    @okwasniewski
    Member

    Automated review.

    Thanks for the detailed report. Checked against main (f6aba9725):

    • The retry in performUntil (packages/e2e/src/locator/engine.ts) is still the same as in 0.18.0.
    • The retry is safe only if the engine keeps its contract. docs/reference/engine.mdx says perform throws a retryable NODE_STALE only when the ref no longer binds and nothing was dispatched, and ACTION_MAY_HAVE_COMMITTED when input may have reached the app. The runner never repeats the second one.
    • The mobile engine breaks that contract. staleOr (packages/mobile/src/errors.ts:234) wraps the whole perform call (packages/mobile/src/surface.ts:1186). It turns any agent-device error that matches a "ref ... not found / stale / unknown" text pattern into NODE_STALE, including errors raised after the press was sent (for example, during the post-tap settle).

    So the fix should be in @e2e-dev/mobile: classify a stale ref as NODE_STALE only before dispatch, and report ACTION_MAY_HAVE_COMMITTED once the press has been sent. Adding a caller post-condition to performUntil would only work around the engine bug.

    To confirm, could you share:

    1. Your e2e, @e2e-dev/mobile and agent-device versions (0.18.0 is several releases old).
    2. The full NODE_STALE message from the failing step (in the trace or the --reporter json details). It shows which agent-device error was reclassified.

    @Varshith-Kali: you can pick this up. Please put the fix in the mobile engine, as described above. A regression test should cover an agent-device press that fails after dispatch with a stale-ref message: it must come back as ACTION_MAY_HAVE_COMMITTED and must not be retried.

  3. added
    bugSomething isn't working
    mobileMobile engine (@e2e-dev/mobile)
    P2Improvement / follow-up
    on Nov 8, 2026
  4. okwasniewski commented on Nov 9, 2026

    @okwasniewski
    Member

    Automated review (agent-run triage).

    Correction to my earlier comment: the root cause I gave was wrong.

    • staleOr classifies by agent-device's typed details.reason, not by message text (since e2e 0.17).
    • agent-device raises every stale-ref reason at admission, before the gesture, and marks press/fill refusals dispatched: 'no'. So on current agent-device a NODE_STALE from a tap should mean the tap was not sent.
    • That doesn't match your app log, where the tap clearly landed. Something else is going on.

    @arekkubaczkowski could you share:

    1. The exact NODE_STALE message (the full error, or the trace.md step) from a failing run.
    2. Your agent-device version (npm ls agent-device) and @e2e-dev/mobile version.
    3. Whether the app log shows the tap once or twice in a failing run.

    With that we can tell if this is a lost reply/replay in agent-device or something on our side. #1638 is on hold until then.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Improvement / follow-upbugSomething isn't workingmobileMobile engine (@e2e-dev/mobile)

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions