@e2e-dev/mobile 0.12.2 → 0.12.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/.build.json CHANGED
@@ -1 +1 @@
1
- {"version":"0.12.2"}
1
+ {"version":"0.12.3"}
package/dist/errors.d.ts CHANGED
@@ -43,6 +43,12 @@ export declare function isRunnerFailure(error: unknown): boolean;
43
43
  * is safe and usually enough.
44
44
  */
45
45
  export declare function isSnapshotPresentationFailure(error: unknown): boolean;
46
+ /**
47
+ * True for a translated snapshot agent-device took on Android but found too
48
+ * little foreground content in to read. The screen is still arriving, so a
49
+ * caller that polls may read it as nothing there yet.
50
+ */
51
+ export declare function isUnreadableCapture(error: unknown): boolean;
46
52
  /**
47
53
  * Runs one agent-device command under an abort signal and translates its
48
54
  * failure onto the engine taxonomy: the one boundary every command crosses.
package/dist/errors.js CHANGED
@@ -135,6 +135,19 @@ const PRESENTATION = {
135
135
  headline: 'the iOS automation runner could not present the accessibility snapshot',
136
136
  firstMove: 'Rerun.',
137
137
  };
138
+ /**
139
+ * The `details.androidSnapshotHelperFailureReason` values agent-device gives
140
+ * up on a capture with when the foreground holds too little to read: the
141
+ * helper returned nothing, only a system window, or an app window with almost
142
+ * no content. A cold-starting app on a slow emulator does this until it
143
+ * renders. Mirrors agent-device's `isUnreadableCaptureContentError`, which
144
+ * its root entry does not export (0.21.25).
145
+ */
146
+ const UNREADABLE_CAPTURE_REASONS = new Set([
147
+ 'empty-helper-output',
148
+ 'system-window-only',
149
+ 'content-poor-app-window',
150
+ ]);
138
151
  const RUNNER_RECOVERY = 'If the next run meets it again, stop the daemon (`npx agent-device daemon stop`) and reboot the simulator (`xcrun simctl shutdown <udid>`, then `boot`).';
139
152
  /** The runner-state entry for a failure, by top-level code or the folded runner wire code. */
140
153
  function runnerState(cause) {
@@ -204,6 +217,17 @@ export function isRunnerFailure(error) {
204
217
  export function isSnapshotPresentationFailure(error) {
205
218
  return error instanceof Error && isPresentationFailure(error.cause);
206
219
  }
220
+ /**
221
+ * True for a translated snapshot agent-device took on Android but found too
222
+ * little foreground content in to read. The screen is still arriving, so a
223
+ * caller that polls may read it as nothing there yet.
224
+ */
225
+ export function isUnreadableCapture(error) {
226
+ if (!(error instanceof Error))
227
+ return false;
228
+ const reason = details(error.cause).androidSnapshotHelperFailureReason;
229
+ return typeof reason === 'string' && UNREADABLE_CAPTURE_REASONS.has(reason);
230
+ }
207
231
  /**
208
232
  * Runs one agent-device command under an abort signal and translates its
209
233
  * failure onto the engine taxonomy: the one boundary every command crosses.
package/dist/locate.js CHANGED
@@ -12,7 +12,10 @@ export function resolveExpression(expression, index, platform) {
12
12
  switch (expression.kind) {
13
13
  case 'query': {
14
14
  const candidates = expression.scope === undefined ? index : descendantsOf(resolveExpression(expression.scope, index, platform), index);
15
- const matches = candidates.filter((entry) => matchesQuery(entry, expression.query));
15
+ const full = candidates.filter((entry) => matchesQuery(entry, expression.query, false));
16
+ const matches = full.length === 0 && platform === 'android' && expression.query.kind === 'testId'
17
+ ? candidates.filter((entry) => matchesQuery(entry, expression.query, true))
18
+ : full;
16
19
  return ECHOED_QUERY_KINDS.has(expression.query.kind) ? innermostOnly(matches) : matches;
17
20
  }
18
21
  case 'filter': {
@@ -42,6 +45,24 @@ export function resolveExpression(expression, index, platform) {
42
45
  });
43
46
  }
44
47
  }
48
+ /**
49
+ * An Android resource id without its `<package>:id/` prefix. UIAutomator
50
+ * reports a native `android:id` with the package of the resource table, the
51
+ * build's namespace even when `applicationIdSuffix` renames the app, and a
52
+ * .NET MAUI `AutomationId` as `<package>:id/<AutomationId>`. React Native,
53
+ * Flutter, and Compose report the id the app set, and iOS never prefixes one,
54
+ * so a test names its views by that id on both platforms. A query tries the
55
+ * short form only when nothing matches the full id, so an app's own `clock`
56
+ * wins over the status bar's `com.android.systemui:id/clock`. The framework's
57
+ * own ids (`android:id/content`) keep their prefix, and two prefixed ids with
58
+ * the same name are ambiguous to the runner's strictness check.
59
+ */
60
+ const ANDROID_RESOURCE_ID = /^([A-Za-z][\w.]*):id\/(.+)$/;
61
+ /** Whether a test id matches `pattern` once its Android package prefix is left off. */
62
+ function matchesWithoutPackage(testId, pattern) {
63
+ const match = ANDROID_RESOURCE_ID.exec(testId);
64
+ return match !== null && match[1] !== 'android' && match[2] !== undefined && matchesText(match[2], pattern);
65
+ }
45
66
  /** The query kinds a device answers with the innermost match, because it echoes what they match on up the tree. */
46
67
  const ECHOED_QUERY_KINDS = new Set(['text', 'label']);
47
68
  /**
@@ -74,8 +95,9 @@ const STATE_KEYS = ['checked', 'disabled', 'selected', 'expanded', 'pressed'];
74
95
  * browser's role query does; the other kinds
75
96
  * answer with every node and leave visibility to the action or assertion,
76
97
  * unless the query says `visible`, which drops hidden nodes for every kind.
98
+ * `withoutPackage` matches a test id by its short form (`ANDROID_RESOURCE_ID`).
77
99
  */
78
- function matchesQuery(entry, query) {
100
+ function matchesQuery(entry, query, withoutPackage) {
79
101
  const node = entry.node;
80
102
  if (query.visible === true && node.states?.hidden === true)
81
103
  return false;
@@ -113,6 +135,7 @@ function matchesQuery(entry, query) {
113
135
  case 'displayValue':
114
136
  return node.value !== undefined && matchesText(node.value, query.value);
115
137
  case 'testId':
116
- return node.testId !== undefined && matchesText(node.testId, query.value);
138
+ return (node.testId !== undefined &&
139
+ (withoutPackage ? matchesWithoutPackage(node.testId, query.value) : matchesText(node.testId, query.value)));
117
140
  }
118
141
  }
package/dist/nodes.d.ts CHANGED
@@ -64,11 +64,14 @@ export declare const ROOT_ID = "root";
64
64
  */
65
65
  export declare function screenRoot(roots: readonly SemanticNode[], viewport: ViewportSize): SemanticNode;
66
66
  /**
67
- * The visible screen's title: the navigation bar's (iOS) or toolbar's
68
- * (Android) own label, else the first text inside it, else its identifier
69
- * (UIKit names the bar after its title). Undefined when the screen has no
70
- * title bar, which is the honest answer for a launch screen, a full-screen
71
- * sheet, or Android's Settings home.
67
+ * The visible screen's title. On iOS, the navigation bar's identifier when a
68
+ * text inside the bar shows it: UIKit and SwiftUI put the title in both, while
69
+ * the bar's label is the back button on a pushed screen and an untitled
70
+ * screen's identifier is a class name with no such text. On Android, the
71
+ * toolbar's own label, else the first text inside it. A toolbar's resource id
72
+ * is never a title. Undefined when the screen has no title bar, which is the
73
+ * honest answer for a launch screen, a full-screen sheet, or Android's
74
+ * Settings home.
72
75
  */
73
76
  export declare function screenTitle(snapshot: ProjectedSnapshot): string | undefined;
74
77
  /** True when `entry` is a strict descendant of `ancestor`. */
package/dist/nodes.js CHANGED
@@ -504,23 +504,33 @@ export function screenRoot(roots, viewport) {
504
504
  };
505
505
  }
506
506
  /**
507
- * The visible screen's title: the navigation bar's (iOS) or toolbar's
508
- * (Android) own label, else the first text inside it, else its identifier
509
- * (UIKit names the bar after its title). Undefined when the screen has no
510
- * title bar, which is the honest answer for a launch screen, a full-screen
511
- * sheet, or Android's Settings home.
507
+ * The visible screen's title. On iOS, the navigation bar's identifier when a
508
+ * text inside the bar shows it: UIKit and SwiftUI put the title in both, while
509
+ * the bar's label is the back button on a pushed screen and an untitled
510
+ * screen's identifier is a class name with no such text. On Android, the
511
+ * toolbar's own label, else the first text inside it. A toolbar's resource id
512
+ * is never a title. Undefined when the screen has no title bar, which is the
513
+ * honest answer for a launch screen, a full-screen sheet, or Android's
514
+ * Settings home.
512
515
  */
513
516
  export function screenTitle(snapshot) {
514
517
  const bar = snapshot.index.find((entry) => entry.kind === 'navigation-bar') ??
515
518
  snapshot.index.find((entry) => ANDROID_TITLE_IDS.some((suffix) => entry.raw.identifier?.endsWith(suffix) === true));
516
519
  if (bar === undefined)
517
520
  return undefined;
518
- if (bar.raw.label !== undefined && bar.raw.label.trim() !== '')
519
- return bar.raw.label;
520
- const text = snapshot.index.find((entry) => entry.node.role === 'text' && entry.raw.label !== undefined && entry.raw.label.trim() !== '' && isWithin(entry, bar));
521
- if (text !== undefined)
522
- return text.raw.label;
523
- return bar.raw.identifier === undefined || bar.raw.identifier.trim() === '' ? undefined : bar.raw.identifier;
521
+ // Whitespace is not a title. Trimming stays here: nonEmpty feeds every node's name.
522
+ const textOf = (value) => (value === undefined || value.trim() === '' ? undefined : value);
523
+ if (bar.kind === 'navigation-bar') {
524
+ const identifier = textOf(bar.raw.identifier);
525
+ const shown = identifier !== undefined &&
526
+ snapshot.index.some((entry) => entry.node.role === 'text' && entry.raw.label === identifier && isWithin(entry, bar));
527
+ return shown ? identifier : undefined;
528
+ }
529
+ const label = textOf(bar.raw.label);
530
+ if (label !== undefined)
531
+ return label;
532
+ const text = snapshot.index.find((entry) => entry.node.role === 'text' && textOf(entry.raw.label) !== undefined && isWithin(entry, bar));
533
+ return text?.raw.label;
524
534
  }
525
535
  /** True when `entry` is a strict descendant of `ancestor`. */
526
536
  export function isWithin(entry, ancestor) {
package/dist/surface.d.ts CHANGED
@@ -263,6 +263,14 @@ export declare class AgentDeviceSurface {
263
263
  * move is the open tool, and failing the step would take that move away.
264
264
  */
265
265
  private snapshotOrEmpty;
266
+ /**
267
+ * Snapshot for a locate; undefined for a screen agent-device could not read
268
+ * yet (an app still on its splash). The harness polls a locate until its
269
+ * deadline, so that screen matches nothing and the poll waits for it to
270
+ * render. A capture that leaves no budget for another poll fails with the
271
+ * reason instead, so a wait that ends on an unreadable screen says so.
272
+ */
273
+ private locateSnapshot;
266
274
  private project;
267
275
  /**
268
276
  * The viewport of a snapshot: its own geometry, else the last one this
package/dist/surface.js CHANGED
@@ -15,7 +15,7 @@ import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, w
15
15
  import { tmpdir } from 'node:os';
16
16
  import path from 'node:path';
17
17
  import { EngineError, KEY_NAMES, parseKey, raceAbort, rejectUnknownKeys, stopProviderRecording, withinCleanupBudget, ConfigurationError, TestError, } from 'e2e/engine';
18
- import { isSnapshotPresentationFailure, runCommand, staleOr } from './errors.js';
18
+ import { isSnapshotPresentationFailure, isUnreadableCapture, runCommand, staleOr } from './errors.js';
19
19
  import { pointerInteraction, DEFAULT_LONG_PRESS_MS } from './actions.js';
20
20
  import { resolveExpression } from './locate.js';
21
21
  import { isWithin, normalizeKind, projectSnapshot, ROOT_ID, screenRoot, screenTitle, } from './nodes.js';
@@ -675,6 +675,24 @@ export class AgentDeviceSurface {
675
675
  throw cause;
676
676
  }
677
677
  }
678
+ /**
679
+ * Snapshot for a locate; undefined for a screen agent-device could not read
680
+ * yet (an app still on its splash). The harness polls a locate until its
681
+ * deadline, so that screen matches nothing and the poll waits for it to
682
+ * render. A capture that leaves no budget for another poll fails with the
683
+ * reason instead, so a wait that ends on an unreadable screen says so.
684
+ */
685
+ async locateSnapshot(operation) {
686
+ const startedMs = Date.now();
687
+ try {
688
+ return await this.snapshotOrEmpty(operation, false);
689
+ }
690
+ catch (cause) {
691
+ if (operation.signal.aborted || !isUnreadableCapture(cause) || Date.now() - startedMs >= operation.timeoutMs)
692
+ throw cause;
693
+ return undefined;
694
+ }
695
+ }
678
696
  project(raw) {
679
697
  const projected = projectSnapshot(raw.nodes ?? [], {
680
698
  mintId: () => {
@@ -730,7 +748,9 @@ export class AgentDeviceSurface {
730
748
  }
731
749
  /** Retains only action bindings for matches, independently of the observation generation. */
732
750
  async locate(expression, operation) {
733
- const raw = await this.snapshotOrEmpty(operation, false);
751
+ const raw = await this.locateSnapshot(operation);
752
+ if (raw === undefined)
753
+ return [];
734
754
  const projected = this.project(raw);
735
755
  this.traceScreen(raw, projected);
736
756
  const matches = resolveExpression(expression, projected.index, this.options.platform);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@e2e-dev/mobile",
3
- "version": "0.12.2",
3
+ "version": "0.12.3",
4
4
  "description": "Mobile engine (iOS and Android) for e2e agentic end-to-end testing, built on agent-device",
5
5
  "keywords": [
6
6
  "e2e",
@@ -51,7 +51,7 @@
51
51
  "NOTICE"
52
52
  ],
53
53
  "dependencies": {
54
- "agent-device": "0.21.25",
54
+ "agent-device": "0.21.28",
55
55
  "pngjs": "7.0.0",
56
56
  "zod": "4.6.1"
57
57
  },
@@ -68,7 +68,7 @@
68
68
  "@types/node": "26.6.2",
69
69
  "@types/pngjs": "6.0.5",
70
70
  "ai": "7.0.107",
71
- "e2e": "0.21.1",
71
+ "e2e": "0.21.2",
72
72
  "typescript": "7.0.2",
73
73
  "vitest": "5.0.1"
74
74
  },