@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 +1 -1
- package/dist/errors.d.ts +6 -0
- package/dist/errors.js +24 -0
- package/dist/locate.js +26 -3
- package/dist/nodes.d.ts +8 -5
- package/dist/nodes.js +21 -11
- package/dist/surface.d.ts +8 -0
- package/dist/surface.js +22 -2
- package/package.json +3 -3
package/dist/.build.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":"0.12.
|
|
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
|
|
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 &&
|
|
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
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
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
|
|
508
|
-
*
|
|
509
|
-
*
|
|
510
|
-
*
|
|
511
|
-
*
|
|
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
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
71
|
+
"e2e": "0.21.2",
|
|
72
72
|
"typescript": "7.0.2",
|
|
73
73
|
"vitest": "5.0.1"
|
|
74
74
|
},
|