@9l/playwright 0.6.0-beta.2 → 0.6.0-beta.4
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/README.md +72 -2
- package/dist/android.d.ts +24 -15
- package/dist/android.js +164 -19
- package/dist/protocol.d.ts +1 -1
- package/dist/protocol.js +1 -1
- package/dist/reporter.js +12 -4
- package/dist/target-setup.js +1 -1
- package/dist/targets.d.ts +55 -3
- package/dist/targets.js +160 -56
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -56,8 +56,78 @@ Natural-language goals use finite observed controls and typed actions, with
|
|
|
56
56
|
budgets and a conservative stop policy. See the
|
|
57
57
|
[goal contract](https://github.com/Quality-Max/9lives-runner/blob/main/docs/goals.md)
|
|
58
58
|
and [SDK bridge](https://github.com/Quality-Max/9lives-runner/blob/main/docs/sdk-bridge.md).
|
|
59
|
-
Live provider accuracy, independent behavioral verification, verified replay
|
|
60
|
-
and
|
|
59
|
+
Live provider accuracy, independent behavioral verification, verified replay,
|
|
60
|
+
iOS and Android devices beyond those listed below are not qualified features.
|
|
61
|
+
|
|
62
|
+
## Android (experimental, 0.6.0-beta releases)
|
|
63
|
+
|
|
64
|
+
The Android target drives an owned emulator or an attached phone through
|
|
65
|
+
Appium 3.8.0 and UiAutomator2 8.7.0, with the same `app` fixture a web
|
|
66
|
+
target uses. It is qualified on API 35 emulators and one Android 17 phone;
|
|
67
|
+
see [Android setup and qualification limits](https://github.com/Quality-Max/9lives-runner/blob/main/docs/android-driver.md).
|
|
68
|
+
|
|
69
|
+
1. Install the matching beta CLI and `@9l/playwright` together (see
|
|
70
|
+
[beta releases](https://github.com/Quality-Max/9lives-runner/blob/main/docs/releases.md#beta-releases)),
|
|
71
|
+
and the pinned automation tooling once, outside your project:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
npm install --prefix ~/.9l/android-tools --save-exact --ignore-scripts \
|
|
75
|
+
appium@3.8.0 appium-uiautomator2-driver@8.7.0
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
For another location, set `NINELIVES_ANDROID_TOOLS`.
|
|
79
|
+
|
|
80
|
+
2. Check the host. Doctor reports Java, the SDK, build-tools, AVDs, devices
|
|
81
|
+
and the pinned tooling, each with a fix:
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
9l doctor --android
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
3. Construct the driver in the shared target fixture and name the Playwright
|
|
88
|
+
project `android:<alias>`:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import {createTargetTest} from '@9l/playwright';
|
|
92
|
+
import {androidTargetDriver} from '@9l/playwright/android';
|
|
93
|
+
|
|
94
|
+
export const test = createTargetTest({
|
|
95
|
+
native: target => androidTargetDriver({
|
|
96
|
+
appId: target.appId, avd: 'Pixel_API_35',
|
|
97
|
+
apk: 'build/app.apk', apkSHA256: '<digest>',
|
|
98
|
+
appPackage: 'com.example.app', activity: '.MainActivity',
|
|
99
|
+
}),
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
// playwright.config.ts
|
|
105
|
+
import {defineConfig} from '@playwright/test';
|
|
106
|
+
|
|
107
|
+
export default defineConfig({
|
|
108
|
+
// A cold emulator boot fits in open()'s 180-second bound, which needs
|
|
109
|
+
// a test timeout above Playwright's 30-second default.
|
|
110
|
+
timeout: 240_000,
|
|
111
|
+
// 9l owns attempts: a Playwright retry is refused.
|
|
112
|
+
retries: 0,
|
|
113
|
+
projects: [{name: 'android:app'}],
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
4. Run through the engine, forwarding the variables the driver relies on.
|
|
118
|
+
`9l run` passes only a fixed environment to tests:
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
9l run tests/login.spec.ts --sdk --target android:app \
|
|
122
|
+
--pass-env ANDROID_HOME,JAVA_HOME,NINELIVES_ANDROID_TOOLS
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Forward `ANDROID_SDK_ROOT`, `ANDROID_AVD_HOME` or `HOMEBREW_PREFIX` too if
|
|
126
|
+
your SDK or AVDs are found through them. `9l doctor --android` says which.
|
|
127
|
+
|
|
128
|
+
The driver holds the device's only UI-automation connection while a session
|
|
129
|
+
is open, so a spec-side `adb shell uiautomator dump` returns nothing. Use the
|
|
130
|
+
fixture's operations instead, and `app.deviceSerial()` for other adb commands.
|
|
61
131
|
|
|
62
132
|
## License
|
|
63
133
|
|
package/dist/android.d.ts
CHANGED
|
@@ -2,21 +2,20 @@ import { type TargetDriver } from './targets';
|
|
|
2
2
|
export { TargetSetupError, type TargetSetupRecord } from './targets';
|
|
3
3
|
export { androidVersions, androidRuntimeType, validAndroidRuntime, type AndroidRuntime } from './android-runtime';
|
|
4
4
|
export { androidDefaults, androidSdkCandidates, androidSdkVariables, androidToolPaths, androidToolingPaths, androidToolsInstall, androidBuildTools, type AndroidDefaults, type AndroidSource } from './android-env';
|
|
5
|
-
/** Explicit aliases for apps without resource IDs.
|
|
6
|
-
*
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
}
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
}) & {
|
|
5
|
+
/** Explicit aliases for apps without resource IDs. Each names exactly one
|
|
6
|
+
* matcher: exact text, an exact accessibility description, a literal
|
|
7
|
+
* description suffix or substring (a merged multi-line label is one
|
|
8
|
+
* description, so either reaches part of it), or an exact input hint. All
|
|
9
|
+
* matches remain strict and scoped to the configured package; arbitrary
|
|
10
|
+
* XPath is not accepted. */
|
|
11
|
+
type AndroidMatcher = 'text' | 'accessibilityId' | 'accessibilityIdSuffix' | 'accessibilityIdContains' | 'hint';
|
|
12
|
+
export type AndroidControl = {
|
|
13
|
+
[K in AndroidMatcher]: {
|
|
14
|
+
[M in K]: string;
|
|
15
|
+
} & {
|
|
16
|
+
[M in Exclude<AndroidMatcher, K>]?: never;
|
|
17
|
+
};
|
|
18
|
+
}[AndroidMatcher] & {
|
|
20
19
|
className?: string;
|
|
21
20
|
selected?: boolean;
|
|
22
21
|
};
|
|
@@ -81,6 +80,15 @@ export type AndroidTargetOptions = {
|
|
|
81
80
|
apk: string;
|
|
82
81
|
headless?: boolean;
|
|
83
82
|
deviceSerial?: never;
|
|
83
|
+
/** Owned emulator only: boot the named snapshot of a dedicated AVD that
|
|
84
|
+
* scripts/prepare-biometric-avd.cjs prepared (a lock screen and an
|
|
85
|
+
* enrolled fingerprint, saved unlocked), still read-only, and offer
|
|
86
|
+
* app.fingerprint(). The driver never sees, sets or enters a PIN; a
|
|
87
|
+
* snapshot that boots locked or without an enrolled fingerprint is a
|
|
88
|
+
* setup mismatch (biometrics-unavailable). */
|
|
89
|
+
biometrics?: {
|
|
90
|
+
snapshot: string;
|
|
91
|
+
};
|
|
84
92
|
} | {
|
|
85
93
|
/** Experimental attachment: installed, single-base APK only. Never resets,
|
|
86
94
|
* reinstalls or terminates the app. Installs the pinned automation helpers. */
|
|
@@ -88,6 +96,7 @@ export type AndroidTargetOptions = {
|
|
|
88
96
|
avd?: never;
|
|
89
97
|
apk?: never;
|
|
90
98
|
headless?: never;
|
|
99
|
+
biometrics?: never;
|
|
91
100
|
});
|
|
92
101
|
/** The host-local lease that gives one owner exclusive use of a device.
|
|
93
102
|
* The driver and installInPlace both take it, so an installation cannot
|
package/dist/android.js
CHANGED
|
@@ -30,6 +30,21 @@ Object.defineProperty(exports, "androidToolPaths", { enumerable: true, get: func
|
|
|
30
30
|
Object.defineProperty(exports, "androidToolingPaths", { enumerable: true, get: function () { return android_env_2.androidToolingPaths; } });
|
|
31
31
|
Object.defineProperty(exports, "androidToolsInstall", { enumerable: true, get: function () { return android_env_2.androidToolsInstall; } });
|
|
32
32
|
Object.defineProperty(exports, "androidBuildTools", { enumerable: true, get: function () { return android_env_2.androidBuildTools; } });
|
|
33
|
+
const matchers = ['text', 'accessibilityId', 'accessibilityIdSuffix', 'accessibilityIdContains', 'hint'];
|
|
34
|
+
/** Test IDs: an app resource entry name, which Android reports as
|
|
35
|
+
* `<package>:id/<id>`, or an identifier a framework reports bare (Flutter's
|
|
36
|
+
* `Semantics(identifier:)`), which may also contain `.` and `-`. */
|
|
37
|
+
const testIdPattern = /^[a-zA-Z0-9_][a-zA-Z0-9_.-]{0,127}$/;
|
|
38
|
+
// UiAutomator2's selector parser unescapes only \" inside a string
|
|
39
|
+
// argument; every other backslash reaches the matcher as written. Text and
|
|
40
|
+
// description aliases holding a backslash are refused, and IDs cannot hold
|
|
41
|
+
// one, so the only backslashes in a selector are \Q and \E.
|
|
42
|
+
const selectorString = (value) => `"${value.replaceAll('"', '\\"')}"`;
|
|
43
|
+
const quoted = (value) => `\\Q${value}\\E`;
|
|
44
|
+
// An XPath 1.0 string literal has no escapes: a value holding both quote
|
|
45
|
+
// characters is assembled with concat().
|
|
46
|
+
const xpathLiteral = (value) => !value.includes('"') ? `"${value}"` : !value.includes("'") ? `'${value}'`
|
|
47
|
+
: `concat(${value.split('"').map(part => `"${part}"`).join(`, '"', `)})`;
|
|
33
48
|
const failure = (reason) => new Error(`9lives Android: ${reason}`);
|
|
34
49
|
// One fixed script per call; every interpolated value is validated by the
|
|
35
50
|
// caller's option checks. The device shell runs it; nothing else does.
|
|
@@ -160,17 +175,21 @@ function androidTargetDriver(options) {
|
|
|
160
175
|
(options.diagnostics !== undefined && (Object.keys(options.diagnostics).some(k => k !== 'gestures') || typeof options.diagnostics.gestures !== 'boolean')))
|
|
161
176
|
throw failure('invalid_configuration');
|
|
162
177
|
const diagnostics = options.diagnostics?.gestures === true;
|
|
178
|
+
const biometrics = options.biometrics;
|
|
179
|
+
if (biometrics !== undefined && (physical || !biometrics || typeof biometrics !== 'object' || Object.keys(biometrics).some(k => k !== 'snapshot') ||
|
|
180
|
+
typeof biometrics.snapshot !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(biometrics.snapshot)))
|
|
181
|
+
throw failure('invalid_configuration');
|
|
163
182
|
const requires = options.requires;
|
|
164
183
|
if (requires !== undefined && (Object.keys(requires).some(k => !['posture', 'minWidthDp'].includes(k)) || Object.keys(requires).length === 0 ||
|
|
165
184
|
(requires.posture !== undefined && !['opened', 'half-opened', 'closed', 'flat'].includes(requires.posture)) ||
|
|
166
185
|
(requires.minWidthDp !== undefined && (!Number.isInteger(requires.minWidthDp) || requires.minWidthDp < 1 || requires.minWidthDp > 10000))))
|
|
167
186
|
throw failure('invalid_configuration');
|
|
168
187
|
for (const [id, control] of Object.entries(controls)) {
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
!/^[^\x00-\x1f\x7f]{1,128}$/.test(
|
|
188
|
+
const declared = control ? matchers.filter(k => control[k] !== undefined) : [];
|
|
189
|
+
const literal = declared.length === 1 ? control[declared[0]] : undefined;
|
|
190
|
+
if (!testIdPattern.test(id) || !control ||
|
|
191
|
+
Object.keys(control).some(k => !matchers.includes(k) && k !== 'className' && k !== 'selected') ||
|
|
192
|
+
typeof literal !== 'string' || !/^[^\x00-\x1f\x7f]{1,128}$/.test(literal) || (declared[0] !== 'hint' && literal.includes('\\')) ||
|
|
174
193
|
(control.className !== undefined && !/^android\.(view|widget)\.[A-Za-z]{1,64}$/.test(control.className)) ||
|
|
175
194
|
(control.selected !== undefined && typeof control.selected !== 'boolean'))
|
|
176
195
|
throw failure('invalid_controls');
|
|
@@ -399,28 +418,67 @@ function androidTargetDriver(options) {
|
|
|
399
418
|
throw failure('session_unavailable');
|
|
400
419
|
return request(`/session/${session}${path}`, c, method, body);
|
|
401
420
|
};
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
421
|
+
// The control as one generated, package-scoped XPath. It finds hint
|
|
422
|
+
// aliases (UiSelector has no hint matcher) and reads content-invalid,
|
|
423
|
+
// which UiAutomator2 exposes in its hierarchy but not as an element attribute.
|
|
424
|
+
const xpathOf = (id) => {
|
|
405
425
|
const control = Object.hasOwn(controls, id) ? controls[id] : undefined;
|
|
406
|
-
let
|
|
407
|
-
if (control)
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
426
|
+
let path = `//*[@package=${xpathLiteral(options.appPackage)}]`;
|
|
427
|
+
if (!control)
|
|
428
|
+
return `${path}[@resource-id=${xpathLiteral(id)} or @resource-id=${xpathLiteral(`${options.appPackage}:id/${id}`)}]`;
|
|
429
|
+
if (control.hint !== undefined)
|
|
430
|
+
path += `[@hint=${xpathLiteral(control.hint)}]`;
|
|
431
|
+
else if (control.text !== undefined)
|
|
432
|
+
path += `[@text=${xpathLiteral(control.text)}]`;
|
|
433
|
+
else if (control.accessibilityId !== undefined)
|
|
434
|
+
path += `[@content-desc=${xpathLiteral(control.accessibilityId)}]`;
|
|
435
|
+
else if (control.accessibilityIdContains !== undefined)
|
|
436
|
+
path += `[contains(@content-desc, ${xpathLiteral(control.accessibilityIdContains)})]`;
|
|
437
|
+
else {
|
|
438
|
+
const suffix = xpathLiteral(control.accessibilityIdSuffix);
|
|
439
|
+
path += `[substring(@content-desc, string-length(@content-desc) - string-length(${suffix}) + 1) = ${suffix}]`;
|
|
440
|
+
}
|
|
441
|
+
if (control.className)
|
|
442
|
+
path += `[@class=${xpathLiteral(control.className)}]`;
|
|
443
|
+
if (control.selected !== undefined)
|
|
444
|
+
path += `[@selected="${control.selected}"]`;
|
|
445
|
+
return path;
|
|
446
|
+
};
|
|
447
|
+
// One fixed query per control. A test ID matches the app's prefixed
|
|
448
|
+
// resource name or the same name reported bare, both in one query, so a
|
|
449
|
+
// control reported both ways is ambiguous rather than a first match.
|
|
450
|
+
// UiSelector regexes match the whole value, across line breaks.
|
|
451
|
+
const query = (id) => {
|
|
452
|
+
const control = Object.hasOwn(controls, id) ? controls[id] : undefined;
|
|
453
|
+
if (control?.hint !== undefined)
|
|
454
|
+
return { using: 'xpath', value: xpathOf(id) };
|
|
455
|
+
let selector = `new UiSelector().packageName(${selectorString(options.appPackage)})`;
|
|
456
|
+
if (!control)
|
|
457
|
+
selector += `.resourceIdMatches(${selectorString(`(?:${quoted(`${options.appPackage}:id/`)})?${quoted(id)}`)})`;
|
|
458
|
+
else {
|
|
459
|
+
if (control.accessibilityIdSuffix !== undefined)
|
|
460
|
+
selector += `.descriptionMatches(${selectorString(`(?s).*${quoted(control.accessibilityIdSuffix)}`)})`;
|
|
461
|
+
else if (control.accessibilityIdContains !== undefined)
|
|
462
|
+
selector += `.descriptionContains(${selectorString(control.accessibilityIdContains)})`;
|
|
412
463
|
else
|
|
413
|
-
selector += control.accessibilityId === undefined ? `.text(${
|
|
464
|
+
selector += control.accessibilityId === undefined ? `.text(${selectorString(control.text)})` : `.description(${selectorString(control.accessibilityId)})`;
|
|
414
465
|
if (control.className)
|
|
415
|
-
selector += `.className(${
|
|
466
|
+
selector += `.className(${selectorString(control.className)})`;
|
|
416
467
|
if (control.selected !== undefined)
|
|
417
468
|
selector += `.selected(${control.selected})`;
|
|
418
469
|
}
|
|
419
|
-
|
|
470
|
+
return { using: '-android uiautomator', value: selector };
|
|
471
|
+
};
|
|
472
|
+
const elements = (result) => {
|
|
420
473
|
if (!Array.isArray(result) || result.length > 512 || result.some(value => typeof value?.[elementKey] !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(value[elementKey])))
|
|
421
474
|
throw failure('invalid_elements');
|
|
422
475
|
return result.map(value => value[elementKey]);
|
|
423
476
|
};
|
|
477
|
+
const matches = async (id, c) => {
|
|
478
|
+
if (!testIdPattern.test(id))
|
|
479
|
+
throw failure('invalid_resource_id');
|
|
480
|
+
return elements(await endpoint('/elements', c, 'POST', query(id)));
|
|
481
|
+
};
|
|
424
482
|
const resolveOne = async (id, c) => {
|
|
425
483
|
const result = await matches(id, c);
|
|
426
484
|
if (result.length !== 1)
|
|
@@ -435,8 +493,15 @@ function androidTargetDriver(options) {
|
|
|
435
493
|
await endpoint(`/element/${ref}/clear`, c, 'POST', {});
|
|
436
494
|
await endpoint(`/element/${ref}/value`, c, 'POST', { text: value });
|
|
437
495
|
},
|
|
496
|
+
// A control that vanished since it was observed is not visible; two
|
|
497
|
+
// matches are still ambiguous.
|
|
438
498
|
visible: async (c) => {
|
|
439
|
-
const
|
|
499
|
+
const found = await matches(id, c);
|
|
500
|
+
if (found.length > 1)
|
|
501
|
+
throw failure('ambiguous_resource_id');
|
|
502
|
+
if (found.length === 0)
|
|
503
|
+
return false;
|
|
504
|
+
const value = await endpoint(`/element/${found[0]}/displayed`, c);
|
|
440
505
|
if (typeof value !== 'boolean')
|
|
441
506
|
throw failure('invalid_property');
|
|
442
507
|
return value;
|
|
@@ -455,6 +520,23 @@ function androidTargetDriver(options) {
|
|
|
455
520
|
throw failure('unavailable_state');
|
|
456
521
|
return value === true || value === 'true';
|
|
457
522
|
},
|
|
523
|
+
// The node's content-invalid flag: an input reporting a validation
|
|
524
|
+
// error. UiAutomator2 reads it only through its hierarchy, so the flag
|
|
525
|
+
// is the set of nodes the same criteria match with it set, and no single
|
|
526
|
+
// request returns both the control and its flag. The read is bracketed:
|
|
527
|
+
// the control resolves to one element before and after it, the same
|
|
528
|
+
// element both times (element IDs are stable per node), and a flagged
|
|
529
|
+
// result is that element. A control that vanished, was replaced or
|
|
530
|
+
// became ambiguous in between is a failed read, never a state.
|
|
531
|
+
invalid: async (c) => {
|
|
532
|
+
disarm();
|
|
533
|
+
const before = await resolveOne(id, c);
|
|
534
|
+
const flagged = elements(await endpoint('/elements', c, 'POST', { using: 'xpath', value: `${xpathOf(id)}[@content-invalid="true"]` }));
|
|
535
|
+
const after = await resolveOne(id, c);
|
|
536
|
+
if (after !== before || flagged.some(ref => ref !== before))
|
|
537
|
+
throw failure('stale_element_reference');
|
|
538
|
+
return flagged.length === 1;
|
|
539
|
+
},
|
|
458
540
|
// One supported UiAutomator2 gesture inside the resolved element; the
|
|
459
541
|
// driver reports whether more content exists, which is not retained.
|
|
460
542
|
scroll: async (direction, percent, c) => {
|
|
@@ -660,7 +742,9 @@ function androidTargetDriver(options) {
|
|
|
660
742
|
if (Buffer.byteLength(consoleSocket) > 103)
|
|
661
743
|
throw failure('scratch_path_too_long');
|
|
662
744
|
const port = await reportedConsole(consoleSocket, c, () => {
|
|
663
|
-
|
|
745
|
+
// A declared biometric snapshot is loaded and never saved, so
|
|
746
|
+
// every test still starts from the same state.
|
|
747
|
+
emulator = (0, node_child_process_1.spawn)(emulatorPath, ['-avd', options.avd, '-read-only', ...(biometrics ? ['-snapshot', biometrics.snapshot, '-no-snapshot-save'] : ['-no-snapshot']), '-no-audio', '-report-console', `unix:${consoleSocket}`, ...(options.headless === false ? [] : ['-no-window']), '-gpu', 'swiftshader_indirect'], { env, stdio: 'ignore' });
|
|
664
748
|
emulator.on('error', () => { });
|
|
665
749
|
return emulator;
|
|
666
750
|
});
|
|
@@ -680,6 +764,23 @@ function androidTargetDriver(options) {
|
|
|
680
764
|
}
|
|
681
765
|
await (0, promises_2.setTimeout)(250, undefined, { signal: c.signal });
|
|
682
766
|
}
|
|
767
|
+
if (biometrics) {
|
|
768
|
+
// The snapshot must resume unlocked with a fingerprint enrolled;
|
|
769
|
+
// the driver has no PIN to unlock it with.
|
|
770
|
+
stage = 'biometrics';
|
|
771
|
+
let state;
|
|
772
|
+
try {
|
|
773
|
+
state = await readDeviceState(c);
|
|
774
|
+
}
|
|
775
|
+
catch (error) {
|
|
776
|
+
if (interrupted(c))
|
|
777
|
+
throw error;
|
|
778
|
+
state = 'unknown';
|
|
779
|
+
}
|
|
780
|
+
const enrolled = [...(await adbRun(shell('dumpsys fingerprint 2>/dev/null | head -c 4096'), c)).matchAll(/"count":([0-9]{1,4})/g)].reduce((sum, m) => sum + Number(m[1]), 0);
|
|
781
|
+
if (state !== 'unlocked' || enrolled < 1)
|
|
782
|
+
throw new targets_1.TargetSetupError({ classification: 'mismatch', reason: 'biometrics-unavailable', stage: 'open' });
|
|
783
|
+
}
|
|
683
784
|
stage = 'displays';
|
|
684
785
|
await readDisplays(c);
|
|
685
786
|
stage = 'apk_install';
|
|
@@ -871,6 +972,50 @@ function androidTargetDriver(options) {
|
|
|
871
972
|
}
|
|
872
973
|
},
|
|
873
974
|
async activate(c) { disarm(); await appCommand('mobile: activateApp', c); },
|
|
975
|
+
// The focused window's package, from the same filtered window dump the
|
|
976
|
+
// baseline reads: the app's, another package's (system UI, a permission
|
|
977
|
+
// controller, Settings) or none. An unreadable dump is not a state.
|
|
978
|
+
async foreground(c) {
|
|
979
|
+
disarm();
|
|
980
|
+
check(c);
|
|
981
|
+
const windows = await readWindows(c);
|
|
982
|
+
if (!windows || windows.focus === 'unknown')
|
|
983
|
+
throw failure('unavailable_state');
|
|
984
|
+
return windows.focus;
|
|
985
|
+
},
|
|
986
|
+
// Owned emulator: the serial its console handshake established; attached
|
|
987
|
+
// phone: the serial the spec configured. Only while the session is open.
|
|
988
|
+
deviceSerial: () => session && !closed ? serial : undefined,
|
|
989
|
+
// The emulator's virtual sensor through its console: a touch, a short
|
|
990
|
+
// hold and a lift. Present only on an owned emulator with biometrics.
|
|
991
|
+
// The console exits 0 even when it refuses a command and prints `KO`.
|
|
992
|
+
...(biometrics && !physical ? { fingerprint: async (finger, c) => {
|
|
993
|
+
disarm();
|
|
994
|
+
check(c);
|
|
995
|
+
if (!Number.isInteger(finger) || finger < 1 || finger > 10)
|
|
996
|
+
throw failure('invalid_value');
|
|
997
|
+
// A prompt drops a touch that arrives while it is still animating in,
|
|
998
|
+
// though the sensor service already reports the session: wait, within
|
|
999
|
+
// the bound, until two captures 250 ms apart are equal. The touch is
|
|
1000
|
+
// made once; it is never repeated.
|
|
1001
|
+
for (let previous = '';;) {
|
|
1002
|
+
if (Date.now() + 1500 >= c.deadlineMs)
|
|
1003
|
+
throw failure('display_not_settled');
|
|
1004
|
+
const current = await screenDigest(c);
|
|
1005
|
+
if (current === previous)
|
|
1006
|
+
break;
|
|
1007
|
+
previous = current;
|
|
1008
|
+
await (0, promises_2.setTimeout)(250, undefined, { signal: c.signal });
|
|
1009
|
+
}
|
|
1010
|
+
const sensor = async (action) => {
|
|
1011
|
+
if (/(^|\n)KO\b/.test(await command(adb, ['-s', serial, 'emu', 'finger', action, String(finger)], c, env, 'both')))
|
|
1012
|
+
throw failure('fingerprint_failed');
|
|
1013
|
+
};
|
|
1014
|
+
await sensor('touch');
|
|
1015
|
+
// Held about as long as a person rests a finger on the sensor.
|
|
1016
|
+
await (0, promises_2.setTimeout)(1000, undefined, { signal: c.signal });
|
|
1017
|
+
await sensor('remove');
|
|
1018
|
+
} } : {}),
|
|
874
1019
|
// After a completed assertion failure: did the phone become unavailable?
|
|
875
1020
|
// Read-only; an owned emulator cannot lock itself. With diagnostics, a
|
|
876
1021
|
// hidden assertion that failed although the app lost a window since the
|
package/dist/protocol.d.ts
CHANGED
|
@@ -2,7 +2,7 @@ export declare const protocolVersion = "9l.engine/1";
|
|
|
2
2
|
export declare const maxFrameBytes: number;
|
|
3
3
|
export declare const maxEvents = 10000;
|
|
4
4
|
export declare const capabilities: readonly ["steps", "artifact-metadata", "terminal-outcomes", "declared-outcomes"];
|
|
5
|
-
export declare const targetVersion = "9l.target/
|
|
5
|
+
export declare const targetVersion = "9l.target/3";
|
|
6
6
|
export declare const targetStepFile: string;
|
|
7
7
|
export declare function selectedTarget(env?: NodeJS.ProcessEnv): {
|
|
8
8
|
name: string;
|
package/dist/protocol.js
CHANGED
|
@@ -12,7 +12,7 @@ exports.protocolVersion = '9l.engine/1';
|
|
|
12
12
|
exports.maxFrameBytes = 16 * 1024;
|
|
13
13
|
exports.maxEvents = 10000;
|
|
14
14
|
exports.capabilities = ['steps', 'artifact-metadata', 'terminal-outcomes', 'declared-outcomes'];
|
|
15
|
-
exports.targetVersion = '9l.target/
|
|
15
|
+
exports.targetVersion = '9l.target/3';
|
|
16
16
|
// Typed target steps carry this module's own location. The reporter counts only
|
|
17
17
|
// those, so a user step titled "9l target ..." stays an ordinary step. Code in the
|
|
18
18
|
// worker can still forge one deliberately; the worker remains trusted.
|
package/dist/reporter.js
CHANGED
|
@@ -13,10 +13,11 @@ function insideAssertion(step) {
|
|
|
13
13
|
return false;
|
|
14
14
|
}
|
|
15
15
|
// A typed target step fails only with "9lives target stopped: <reason>", where
|
|
16
|
-
// the reason is the fixture's own token
|
|
17
|
-
// the
|
|
16
|
+
// the reason is the fixture's own token, optionally followed by the one fixed
|
|
17
|
+
// detail the fixture writes (the accepted range of an invalid timeout). Only
|
|
18
|
+
// the token crosses the bridge; any other error text, or none, sends no reason.
|
|
18
19
|
function targetStopReason(error) {
|
|
19
|
-
return /^(?:Error: )?9lives target stopped: ([a-z_]{1,64})
|
|
20
|
+
return /^(?:Error: )?9lives target stopped: ([a-z_]{1,64})(?: \(accepted 1-[0-9]{1,7} ms\))?$/.exec(error?.message ?? '')?.[1];
|
|
20
21
|
}
|
|
21
22
|
// Worker logs, error messages, step titles, URLs and attachment bodies never enter
|
|
22
23
|
// the protocol. IDs are hashes; Go persists only this bounded metadata stream.
|
|
@@ -80,12 +81,19 @@ class EngineReporter {
|
|
|
80
81
|
if (step.category === 'expect' && insideAssertion(step))
|
|
81
82
|
return;
|
|
82
83
|
const categories = { 'test.step': 'action', expect: 'assertion', 'pw:api': 'browser', fixture: 'fixture' };
|
|
83
|
-
const
|
|
84
|
+
const typed = this.target && step.category === 'test.step' && step.location?.file === protocol_1.targetStepFile && step.title.startsWith('9l target ') ? step.title.slice('9l target '.length) : undefined;
|
|
85
|
+
// "<operation>" or "<operation> <control>": the control is the test ID
|
|
86
|
+
// the fixture named, an identifier only. Anything else keeps the whole
|
|
87
|
+
// remainder as the operation, which the engine rejects as unknown. Only a
|
|
88
|
+
// failed step names its control, so passing evidence carries no test ID.
|
|
89
|
+
const named = typed === undefined ? undefined : /^([a-z][a-z-]{0,63}) ([A-Za-z0-9_][A-Za-z0-9_.-]{0,63})$/.exec(typed);
|
|
90
|
+
const operation = named ? named[1] : typed, control = step.error ? named?.[2] : undefined;
|
|
84
91
|
const reason = operation && step.error ? targetStopReason(step.error) : undefined;
|
|
85
92
|
this.emit('step_end', {
|
|
86
93
|
testId: this.testId(test), retry: result.retry, stepId: `step-${++this.stepSeq}`,
|
|
87
94
|
category: operation ? operation.startsWith('assert-') ? 'assertion' : 'action' : step.category === 'test.step' && step.title === '9l goal' ? 'goal' : categories[step.category] ?? 'other', status: step.error ? 'failed' : 'passed',
|
|
88
95
|
...(operation ? { operation } : {}),
|
|
96
|
+
...(control ? { control } : {}),
|
|
89
97
|
...(reason ? { reason } : {}),
|
|
90
98
|
});
|
|
91
99
|
}
|
package/dist/target-setup.js
CHANGED
|
@@ -13,7 +13,7 @@ exports.setupReasons = {
|
|
|
13
13
|
blocked: ['device-locked', 'screen-off'],
|
|
14
14
|
dirty: ['extra-window', 'foreign-focus', 'ime-showing'],
|
|
15
15
|
/** The device is not in the posture or width the spec declared. */
|
|
16
|
-
mismatch: ['posture', 'display-width', 'build-digest', 'build-version', 'build-signer'],
|
|
16
|
+
mismatch: ['posture', 'display-width', 'build-digest', 'build-version', 'build-signer', 'biometrics-unavailable'],
|
|
17
17
|
/** The accessibility snapshot still reported an element whose window the
|
|
18
18
|
* window manager no longer lists: observer staleness, not the app. */
|
|
19
19
|
observer: ['window-gone-element-displayed'],
|
package/dist/targets.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ import { targetVersion } from './protocol';
|
|
|
3
3
|
import { type AndroidRuntime } from './android-runtime';
|
|
4
4
|
import { type TargetSetupRecord, type TargetDiagnostic } from './target-setup';
|
|
5
5
|
export { TargetSetupError, validTargetSetup, validTargetDiagnostic, type TargetSetupRecord, type SetupClassification, type TargetDiagnostic, type WindowObservation } from './target-setup';
|
|
6
|
-
export declare const targetCapabilities: readonly ["open", "reset", "test-id", "tap", "fill", "visible", "text", "state", "back", "keyboard", "scroll", "tap-at", "bounds", "viewport", "terminate", "activate", "screen-digest"];
|
|
6
|
+
export declare const targetCapabilities: readonly ["open", "reset", "test-id", "tap", "fill", "visible", "text", "state", "back", "keyboard", "scroll", "tap-at", "bounds", "viewport", "terminate", "activate", "screen-digest", "foreground", "device-serial", "fingerprint"];
|
|
7
7
|
export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
|
|
8
8
|
/** Integer device coordinates: physical pixels on Android, CSS pixels in the web viewport. */
|
|
9
9
|
export type TargetPoint = {
|
|
@@ -26,7 +26,10 @@ export type TargetContext = {
|
|
|
26
26
|
signal: AbortSignal;
|
|
27
27
|
deadlineMs: number;
|
|
28
28
|
};
|
|
29
|
-
|
|
29
|
+
/** `invalid`: the control reports a validation error (Android's
|
|
30
|
+
* content-invalid; on the web aria-invalid or failed constraint validation). */
|
|
31
|
+
export type TargetState = 'enabled' | 'checked' | 'invalid';
|
|
32
|
+
export type TargetForeground = 'app' | 'foreign' | 'none';
|
|
30
33
|
/** Per-call bound, capped by Go's worker deadline. */
|
|
31
34
|
export type TargetOperationOptions = {
|
|
32
35
|
timeoutMs?: number;
|
|
@@ -39,7 +42,10 @@ export interface TargetHandle {
|
|
|
39
42
|
fill(value: string, context: TargetContext): Promise<void>;
|
|
40
43
|
visible(context: TargetContext): Promise<boolean>;
|
|
41
44
|
text(context: TargetContext): Promise<string>;
|
|
42
|
-
state(name:
|
|
45
|
+
state(name: 'enabled' | 'checked', context: TargetContext): Promise<boolean>;
|
|
46
|
+
/** Whether the control reports a validation error. A handle without it
|
|
47
|
+
* fails `toHaveState('invalid', …)` as unsupported_state. */
|
|
48
|
+
invalid?(context: TargetContext): Promise<boolean>;
|
|
43
49
|
/** One bounded scroll gesture inside this element; percent of its size. */
|
|
44
50
|
scroll?(direction: ScrollDirection, percent: number, context: TargetContext): Promise<void>;
|
|
45
51
|
bounds?(context: TargetContext): Promise<TargetRect>;
|
|
@@ -60,6 +66,16 @@ export interface TargetDriver extends TargetIdentity {
|
|
|
60
66
|
/** One touch down/up at device coordinates. */
|
|
61
67
|
tapAt?(point: TargetPoint, context: TargetContext): Promise<void>;
|
|
62
68
|
viewport?(context: TargetContext): Promise<TargetSize>;
|
|
69
|
+
/** Which window has input focus: the app's, another package's (a system
|
|
70
|
+
* dialog, a permission prompt, Settings) or none. Read-only. Android only. */
|
|
71
|
+
foreground?(context: TargetContext): Promise<TargetForeground>;
|
|
72
|
+
/** The serial of the device the open session targets, for spec-side adb
|
|
73
|
+
* commands. Never written to receipts. Android only. */
|
|
74
|
+
deviceSerial?(): string | undefined;
|
|
75
|
+
/** Touch and lift the virtual fingerprint sensor with an enrolled (or
|
|
76
|
+
* deliberately unenrolled) finger. Owned emulators with declared
|
|
77
|
+
* biometrics only. */
|
|
78
|
+
fingerprint?(finger: number, context: TargetContext): Promise<void>;
|
|
63
79
|
/** SHA-256 of a screenshot of the target display, computed in memory. The
|
|
64
80
|
* image itself is never returned, written or attached. */
|
|
65
81
|
screenDigest?(context: TargetContext): Promise<string>;
|
|
@@ -87,6 +103,10 @@ export interface TargetDriver extends TargetIdentity {
|
|
|
87
103
|
point?: TargetPoint;
|
|
88
104
|
}, context: TargetContext): Promise<TargetDiagnostic | undefined>;
|
|
89
105
|
}
|
|
106
|
+
/** A test ID that names its control in the step title, and from there in
|
|
107
|
+
* receipts: an identifier, never free text. Other IDs (with spaces, `@` or
|
|
108
|
+
* other characters that could carry data) name no control. */
|
|
109
|
+
export declare const controlPattern: RegExp;
|
|
90
110
|
/** Deterministic shared operations; browser/device handles stay in the worker. */
|
|
91
111
|
export declare class TargetApp {
|
|
92
112
|
private driver;
|
|
@@ -114,9 +134,20 @@ export declare class TargetApp {
|
|
|
114
134
|
/** Opt-in failure diagnostics: ask the driver once per test, while it is
|
|
115
135
|
* still open, and attach only a validated record. Never changes the outcome. */
|
|
116
136
|
private diagnose;
|
|
137
|
+
private get maxMs();
|
|
138
|
+
/** The stop reason for a bound that ran out: operation_timeout for the
|
|
139
|
+
* call's own bound, deadline for the attempt's (Go's worker deadline). */
|
|
140
|
+
private boundReason;
|
|
117
141
|
private perform;
|
|
118
142
|
open(options?: TargetOperationOptions): Promise<void>;
|
|
119
143
|
reset(options?: TargetOperationOptions): Promise<void>;
|
|
144
|
+
private get lifecycleMs();
|
|
145
|
+
/** Poll a check until it holds or the next read could overrun the bound.
|
|
146
|
+
* Held, or not held after at least one completed observation (with the
|
|
147
|
+
* last failed read, if any); failed reads alone throw their own error, and
|
|
148
|
+
* a bound reached before any completed read is a deadline. Ambiguity,
|
|
149
|
+
* invalid input and cancellation are never transient. */
|
|
150
|
+
private poll;
|
|
120
151
|
/** Poll a check to its bound. A completed false observation is an assertion
|
|
121
152
|
* failure even if a later read stalls; a bound reached before any completed
|
|
122
153
|
* check is a deadline; failed reads alone keep their own operation error.
|
|
@@ -144,6 +175,21 @@ export declare class TargetApp {
|
|
|
144
175
|
terminate(options?: TargetOperationOptions): Promise<void>;
|
|
145
176
|
/** Bring the configured app back to the foreground. Android only. */
|
|
146
177
|
activate(options?: TargetOperationOptions): Promise<void>;
|
|
178
|
+
/** Which window has input focus: the app's, another package's (a system
|
|
179
|
+
* dialog, permission prompt or Settings) or none. Read-only; package
|
|
180
|
+
* scoping of every action is unchanged. Recorded as an executed action,
|
|
181
|
+
* never an assertion. Android only. */
|
|
182
|
+
foreground(options?: TargetOperationOptions): Promise<TargetForeground>;
|
|
183
|
+
/** Touch the emulator's fingerprint sensor with finger 1-10, as a person
|
|
184
|
+
* would at a biometric prompt. Only an owned emulator whose driver
|
|
185
|
+
* declares biometrics has a sensor to touch; elsewhere this fails as
|
|
186
|
+
* unsupported_operation before touching the device. Recorded as an
|
|
187
|
+
* executed action: a biometric sign-in still needs an assertion. */
|
|
188
|
+
fingerprint(finger: number, options?: TargetOperationOptions): Promise<void>;
|
|
189
|
+
/** The serial of the device the open session targets, for adb commands a
|
|
190
|
+
* spec issues itself; those are outside the driver's cleanup and evidence.
|
|
191
|
+
* Not a device operation and never recorded. Android only. */
|
|
192
|
+
deviceSerial(): string;
|
|
147
193
|
getByTestId(id: string): {
|
|
148
194
|
tap: (options?: TargetOperationOptions) => Promise<any>;
|
|
149
195
|
fill: (value: string, options?: TargetOperationOptions) => Promise<void>;
|
|
@@ -158,6 +204,12 @@ export declare class TargetApp {
|
|
|
158
204
|
width: number;
|
|
159
205
|
height: number;
|
|
160
206
|
}>;
|
|
207
|
+
/** Whether the control is visible, without ending the session when it
|
|
208
|
+
* is not: one observation, or with timeoutMs a poll until it appears.
|
|
209
|
+
* Absent counts as not visible; ambiguity and reads that never
|
|
210
|
+
* complete still fail. Recorded as an executed action, never an
|
|
211
|
+
* assertion, so it cannot stand in for one. */
|
|
212
|
+
isVisible: (options?: TargetOperationOptions) => Promise<boolean>;
|
|
161
213
|
toBeVisible: (timeoutMs?: number) => Promise<void>;
|
|
162
214
|
/** Passes when the control is absent or not displayed. */
|
|
163
215
|
toBeHidden: (timeoutMs?: number) => Promise<void>;
|
package/dist/targets.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.TargetApp = exports.targetCapabilities = exports.validTargetDiagnostic = exports.validTargetSetup = exports.TargetSetupError = void 0;
|
|
3
|
+
exports.TargetApp = exports.controlPattern = exports.targetCapabilities = exports.validTargetDiagnostic = exports.validTargetSetup = exports.TargetSetupError = void 0;
|
|
4
4
|
exports.webTargetDriver = webTargetDriver;
|
|
5
5
|
exports.createTargetTest = createTargetTest;
|
|
6
6
|
const test_1 = require("@playwright/test");
|
|
@@ -14,23 +14,33 @@ Object.defineProperty(exports, "TargetSetupError", { enumerable: true, get: func
|
|
|
14
14
|
Object.defineProperty(exports, "validTargetSetup", { enumerable: true, get: function () { return target_setup_2.validTargetSetup; } });
|
|
15
15
|
Object.defineProperty(exports, "validTargetDiagnostic", { enumerable: true, get: function () { return target_setup_2.validTargetDiagnostic; } });
|
|
16
16
|
exports.targetCapabilities = ['open', 'reset', 'test-id', 'tap', 'fill', 'visible', 'text', 'state',
|
|
17
|
-
'back', 'keyboard', 'scroll', 'tap-at', 'bounds', 'viewport', 'terminate', 'activate', 'screen-digest'
|
|
17
|
+
'back', 'keyboard', 'scroll', 'tap-at', 'bounds', 'viewport', 'terminate', 'activate', 'screen-digest',
|
|
18
|
+
'foreground', 'device-serial', 'fingerprint'];
|
|
18
19
|
const defaultOperationMs = 5_000;
|
|
19
20
|
const defaultAssertionMs = 5_000;
|
|
20
21
|
const maxOperationMs = 60_000;
|
|
22
|
+
// An emulator relaunches an app, clears its data or settles a cold start in
|
|
23
|
+
// tens of seconds: Android lifecycle operations default to a minute, and
|
|
24
|
+
// every Android operation and assertion accepts up to the open bound.
|
|
25
|
+
const androidLifecycleMs = 60_000;
|
|
26
|
+
const androidMaxMs = 180_000;
|
|
21
27
|
const maxObservations = 200;
|
|
22
28
|
// An operation is aborted and rejected at its deadline. If it is still pending
|
|
23
29
|
// after this grace, the session closes its driver to cancel it.
|
|
24
30
|
const settleMs = 250;
|
|
25
31
|
const stepLocation = { file: protocol_1.targetStepFile, line: 1, column: 1 };
|
|
32
|
+
/** A test ID that names its control in the step title, and from there in
|
|
33
|
+
* receipts: an identifier, never free text. Other IDs (with spaces, `@` or
|
|
34
|
+
* other characters that could carry data) name no control. */
|
|
35
|
+
exports.controlPattern = /^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$/;
|
|
26
36
|
class TargetStopped extends Error {
|
|
27
37
|
reason;
|
|
28
|
-
constructor(reason, cause) {
|
|
29
|
-
super(`9lives target stopped: ${reason}`, cause === undefined ? undefined : { cause });
|
|
38
|
+
constructor(reason, cause, detail) {
|
|
39
|
+
super(`9lives target stopped: ${reason}${detail ? ` (${detail})` : ''}`, cause === undefined ? undefined : { cause });
|
|
30
40
|
this.reason = reason;
|
|
31
41
|
}
|
|
32
42
|
}
|
|
33
|
-
const stopped = (reason, cause) => new TargetStopped(reason, cause);
|
|
43
|
+
const stopped = (reason, cause, detail) => new TargetStopped(reason, cause, detail);
|
|
34
44
|
const recheckMs = 5_000;
|
|
35
45
|
// A closed metadata record; the reporter forwards it as one target_setup frame.
|
|
36
46
|
const attachSetup = (record) => test_1.test.info().attach('9l.target-setup', { body: Buffer.from(JSON.stringify(record)), contentType: target_setup_1.targetSetupType });
|
|
@@ -120,9 +130,15 @@ class TargetApp {
|
|
|
120
130
|
if (record !== undefined && (0, target_setup_1.validTargetDiagnostic)(record))
|
|
121
131
|
await attachDiagnostic(record);
|
|
122
132
|
}
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
133
|
+
get maxMs() { return this.driver.kind === 'android' ? androidMaxMs : maxOperationMs; }
|
|
134
|
+
/** The stop reason for a bound that ran out: operation_timeout for the
|
|
135
|
+
* call's own bound, deadline for the attempt's (Go's worker deadline). */
|
|
136
|
+
boundReason(deadlineMs) { return deadlineMs < this.options.deadlineMs ? 'operation_timeout' : 'deadline'; }
|
|
137
|
+
async perform(operation, body, timeoutMs = defaultOperationMs, maxTimeoutMs = this.maxMs, deadlineReason = () => 'operation_timeout', point, control) {
|
|
138
|
+
// The SDK location marks this as a typed target step for the reporter;
|
|
139
|
+
// an identifier-shaped test ID after the operation names its control.
|
|
140
|
+
const named = control !== undefined && exports.controlPattern.test(control) ? ` ${control}` : '';
|
|
141
|
+
return test_1.test.step(`9l target ${operation}${named}`, async () => {
|
|
126
142
|
if (this.controller.signal.aborted)
|
|
127
143
|
throw stopped(this.reason);
|
|
128
144
|
if (this.busy) {
|
|
@@ -130,8 +146,9 @@ class TargetApp {
|
|
|
130
146
|
throw stopped(this.reason);
|
|
131
147
|
}
|
|
132
148
|
if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > maxTimeoutMs) {
|
|
149
|
+
// The accepted range is named locally; only the reason crosses the bridge.
|
|
133
150
|
this.stop('invalid_timeout', false);
|
|
134
|
-
throw stopped(this.reason);
|
|
151
|
+
throw stopped(this.reason, undefined, `accepted 1-${maxTimeoutMs} ms`);
|
|
135
152
|
}
|
|
136
153
|
this.busy = true;
|
|
137
154
|
const deadlineMs = Math.min(this.options.deadlineMs, Date.now() + timeoutMs);
|
|
@@ -217,51 +234,66 @@ class TargetApp {
|
|
|
217
234
|
throw stopped('invalid_setup_record');
|
|
218
235
|
await attachSetup(recovered);
|
|
219
236
|
}
|
|
220
|
-
}, options.timeoutMs
|
|
237
|
+
}, options.timeoutMs === undefined && this.driver.kind === 'android' ? androidMaxMs : options.timeoutMs);
|
|
238
|
+
}
|
|
239
|
+
// Defaults apply only to an omitted timeout; any other non-integer,
|
|
240
|
+
// including null, stops as invalid_timeout.
|
|
241
|
+
reset(options = {}) { return this.perform('reset', context => this.driver.reset(context), options.timeoutMs === undefined ? this.lifecycleMs : options.timeoutMs); }
|
|
242
|
+
get lifecycleMs() { return this.driver.kind === 'android' ? androidLifecycleMs : defaultOperationMs; }
|
|
243
|
+
/** Poll a check until it holds or the next read could overrun the bound.
|
|
244
|
+
* Held, or not held after at least one completed observation (with the
|
|
245
|
+
* last failed read, if any); failed reads alone throw their own error, and
|
|
246
|
+
* a bound reached before any completed read is a deadline. Ambiguity,
|
|
247
|
+
* invalid input and cancellation are never transient. */
|
|
248
|
+
async poll(context, attempt, timeoutMs, observations = maxObservations, falseSeen = () => { }, strict = false) {
|
|
249
|
+
const interval = Math.max(25, Math.ceil(timeoutMs / maxObservations));
|
|
250
|
+
let last, slowest = 0, observedFalse = false;
|
|
251
|
+
for (let poll = 0; poll < observations; poll++) {
|
|
252
|
+
context.signal.throwIfAborted();
|
|
253
|
+
const started = Date.now();
|
|
254
|
+
try {
|
|
255
|
+
if (await attempt(context))
|
|
256
|
+
return { held: true };
|
|
257
|
+
observedFalse = true;
|
|
258
|
+
falseSeen();
|
|
259
|
+
}
|
|
260
|
+
catch (error) {
|
|
261
|
+
// A query answers only from reads that completed: any failed read
|
|
262
|
+
// (a lost transport, a driver-level ambiguity) ends it.
|
|
263
|
+
if (strict || error instanceof TargetStopped || context.signal.aborted)
|
|
264
|
+
throw error;
|
|
265
|
+
last = error;
|
|
266
|
+
}
|
|
267
|
+
// Stop while the next observation, half again as slow as the slowest
|
|
268
|
+
// so far, would still finish in time. A last read that overran the
|
|
269
|
+
// bound would end the operation by its deadline, which on Android
|
|
270
|
+
// releases the driver before diagnostics or the recheck can read
|
|
271
|
+
// the device; native read times vary on a loaded host.
|
|
272
|
+
slowest = Math.max(slowest, Date.now() - started);
|
|
273
|
+
if (poll + 1 >= observations || Date.now() + interval + slowest * 1.5 >= context.deadlineMs)
|
|
274
|
+
break;
|
|
275
|
+
await (0, promises_1.setTimeout)(interval, undefined, { signal: context.signal });
|
|
276
|
+
}
|
|
277
|
+
if (observedFalse)
|
|
278
|
+
return { held: false, last };
|
|
279
|
+
// Failed reads alone establish nothing. Keep their operation failure
|
|
280
|
+
// distinct from an executed false comparison.
|
|
281
|
+
if (last !== undefined)
|
|
282
|
+
throw last;
|
|
283
|
+
throw stopped(this.boundReason(context.deadlineMs));
|
|
221
284
|
}
|
|
222
|
-
reset(options = {}) { return this.perform('reset', context => this.driver.reset(context), options.timeoutMs); }
|
|
223
285
|
/** Poll a check to its bound. A completed false observation is an assertion
|
|
224
286
|
* failure even if a later read stalls; a bound reached before any completed
|
|
225
287
|
* check is a deadline; failed reads alone keep their own operation error.
|
|
226
288
|
* After a completed failure, the driver may reclassify the device state. */
|
|
227
|
-
async assertLoop(operation, attempt, timeoutMs = defaultAssertionMs) {
|
|
289
|
+
async assertLoop(operation, attempt, timeoutMs = defaultAssertionMs, control) {
|
|
228
290
|
let observedFalse = false;
|
|
229
291
|
try {
|
|
230
292
|
return await this.perform(operation, async (context) => {
|
|
231
|
-
const
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
const started = Date.now();
|
|
236
|
-
try {
|
|
237
|
-
if (await attempt(context))
|
|
238
|
-
return;
|
|
239
|
-
observedFalse = true;
|
|
240
|
-
}
|
|
241
|
-
catch (error) {
|
|
242
|
-
// Ambiguity, invalid input and cancellation are not transient.
|
|
243
|
-
if (error instanceof TargetStopped || context.signal.aborted)
|
|
244
|
-
throw error;
|
|
245
|
-
last = error;
|
|
246
|
-
}
|
|
247
|
-
// Stop while the next observation, half again as slow as the slowest
|
|
248
|
-
// so far, would still finish in time. A last read that overran the
|
|
249
|
-
// bound would end the assertion by its deadline, which on Android
|
|
250
|
-
// releases the driver before diagnostics or the recheck can read
|
|
251
|
-
// the device; native read times vary on a loaded host.
|
|
252
|
-
slowest = Math.max(slowest, Date.now() - started);
|
|
253
|
-
if (Date.now() + interval + slowest * 1.5 >= context.deadlineMs)
|
|
254
|
-
break;
|
|
255
|
-
await (0, promises_1.setTimeout)(interval, undefined, { signal: context.signal });
|
|
256
|
-
}
|
|
257
|
-
if (observedFalse)
|
|
258
|
-
throw stopped('assertion_failed', last);
|
|
259
|
-
// Failed reads alone establish no business mismatch. Keep their
|
|
260
|
-
// operation failure distinct from an executed false comparison.
|
|
261
|
-
if (last !== undefined)
|
|
262
|
-
throw last;
|
|
263
|
-
throw stopped('deadline');
|
|
264
|
-
}, timeoutMs, maxOperationMs, () => observedFalse ? 'assertion_failed' : 'deadline');
|
|
293
|
+
const result = await this.poll(context, attempt, timeoutMs, maxObservations, () => { observedFalse = true; });
|
|
294
|
+
if (!result.held)
|
|
295
|
+
throw stopped('assertion_failed', result.last);
|
|
296
|
+
}, timeoutMs, this.maxMs, () => observedFalse ? 'assertion_failed' : 'operation_timeout', undefined, control);
|
|
265
297
|
}
|
|
266
298
|
catch (error) {
|
|
267
299
|
// A completed mismatch on a device the driver can still read: ask it
|
|
@@ -325,7 +357,7 @@ class TargetApp {
|
|
|
325
357
|
throw stopped('invalid_point');
|
|
326
358
|
}
|
|
327
359
|
await this.optional('tapAt')({ x: point.x, y: point.y }, context);
|
|
328
|
-
}, options.timeoutMs,
|
|
360
|
+
}, options.timeoutMs, this.maxMs, () => 'operation_timeout', validPoint(point) ? { x: point.x, y: point.y } : undefined);
|
|
329
361
|
}
|
|
330
362
|
viewport(options = {}) {
|
|
331
363
|
return this.perform('viewport', async (context) => {
|
|
@@ -346,9 +378,46 @@ class TargetApp {
|
|
|
346
378
|
}, options.timeoutMs);
|
|
347
379
|
}
|
|
348
380
|
/** Stop the configured app without clearing its data. Android only. */
|
|
349
|
-
terminate(options = {}) { return this.perform('terminate', context => this.optional('terminate')(context), options.timeoutMs); }
|
|
381
|
+
terminate(options = {}) { return this.perform('terminate', context => this.optional('terminate')(context), options.timeoutMs === undefined ? this.lifecycleMs : options.timeoutMs); }
|
|
350
382
|
/** Bring the configured app back to the foreground. Android only. */
|
|
351
|
-
activate(options = {}) { return this.perform('activate', context => this.optional('activate')(context), options.timeoutMs); }
|
|
383
|
+
activate(options = {}) { return this.perform('activate', context => this.optional('activate')(context), options.timeoutMs === undefined ? this.lifecycleMs : options.timeoutMs); }
|
|
384
|
+
/** Which window has input focus: the app's, another package's (a system
|
|
385
|
+
* dialog, permission prompt or Settings) or none. Read-only; package
|
|
386
|
+
* scoping of every action is unchanged. Recorded as an executed action,
|
|
387
|
+
* never an assertion. Android only. */
|
|
388
|
+
foreground(options = {}) {
|
|
389
|
+
return this.perform('foreground', async (context) => {
|
|
390
|
+
const value = await this.optional('foreground')(context);
|
|
391
|
+
if (value !== 'app' && value !== 'foreign' && value !== 'none')
|
|
392
|
+
throw stopped('invalid_property');
|
|
393
|
+
return value;
|
|
394
|
+
}, options.timeoutMs);
|
|
395
|
+
}
|
|
396
|
+
/** Touch the emulator's fingerprint sensor with finger 1-10, as a person
|
|
397
|
+
* would at a biometric prompt. Only an owned emulator whose driver
|
|
398
|
+
* declares biometrics has a sensor to touch; elsewhere this fails as
|
|
399
|
+
* unsupported_operation before touching the device. Recorded as an
|
|
400
|
+
* executed action: a biometric sign-in still needs an assertion. */
|
|
401
|
+
fingerprint(finger, options = {}) {
|
|
402
|
+
return this.perform('fingerprint', async (context) => {
|
|
403
|
+
if (!Number.isInteger(finger) || finger < 1 || finger > 10)
|
|
404
|
+
throw stopped('invalid_value');
|
|
405
|
+
await this.optional('fingerprint')(finger, context);
|
|
406
|
+
}, options.timeoutMs);
|
|
407
|
+
}
|
|
408
|
+
/** The serial of the device the open session targets, for adb commands a
|
|
409
|
+
* spec issues itself; those are outside the driver's cleanup and evidence.
|
|
410
|
+
* Not a device operation and never recorded. Android only. */
|
|
411
|
+
deviceSerial() {
|
|
412
|
+
if (this.controller.signal.aborted)
|
|
413
|
+
throw stopped(this.reason);
|
|
414
|
+
if (typeof this.driver.deviceSerial !== 'function')
|
|
415
|
+
throw stopped('unsupported_operation');
|
|
416
|
+
const serial = this.driver.deviceSerial();
|
|
417
|
+
if (typeof serial !== 'string' || !/^[a-zA-Z0-9_.:-]{1,128}$/.test(serial))
|
|
418
|
+
throw stopped('session_unavailable');
|
|
419
|
+
return serial;
|
|
420
|
+
}
|
|
352
421
|
getByTestId(id) {
|
|
353
422
|
const observe = async (context) => {
|
|
354
423
|
if (!boundedText(id, 128) || !id || /[\x00-\x1f]/.test(id))
|
|
@@ -371,19 +440,21 @@ class TargetApp {
|
|
|
371
440
|
};
|
|
372
441
|
// A missing control is a completed false observation, except for a
|
|
373
442
|
// hidden assertion, where absence is exactly what it asserts.
|
|
443
|
+
// Every operation on this control names it.
|
|
444
|
+
const step = (operation, body, timeoutMs) => this.perform(operation, body, timeoutMs, undefined, undefined, undefined, id);
|
|
374
445
|
const assertion = (operation, check, timeoutMs, absent = false) => this.assertLoop(operation, async (context) => {
|
|
375
446
|
const handle = await observe(context);
|
|
376
447
|
return handle ? check(handle, context) : absent;
|
|
377
|
-
}, timeoutMs);
|
|
448
|
+
}, timeoutMs, id);
|
|
378
449
|
return {
|
|
379
|
-
tap: (options = {}) =>
|
|
380
|
-
fill: (value, options = {}) =>
|
|
450
|
+
tap: (options = {}) => step('tap', async (context) => (await required(context)).tap(context), options.timeoutMs),
|
|
451
|
+
fill: (value, options = {}) => step('fill', async (context) => {
|
|
381
452
|
if (!boundedText(value, 4096))
|
|
382
453
|
throw stopped('invalid_value');
|
|
383
454
|
await (await required(context)).fill(value, context);
|
|
384
455
|
}, options.timeoutMs),
|
|
385
456
|
/** One bounded scroll gesture inside this control, by a fraction of its size. */
|
|
386
|
-
scroll: (direction, options = {}) =>
|
|
457
|
+
scroll: (direction, options = {}) => step('scroll', async (context) => {
|
|
387
458
|
const percent = options.percent ?? 0.5;
|
|
388
459
|
if (!['up', 'down', 'left', 'right'].includes(direction) || typeof percent !== 'number' || !(percent > 0 && percent <= 1))
|
|
389
460
|
throw stopped('invalid_value');
|
|
@@ -393,7 +464,7 @@ class TargetApp {
|
|
|
393
464
|
await handle.scroll(direction, percent, context);
|
|
394
465
|
}, options.timeoutMs),
|
|
395
466
|
/** The control's rectangle in device coordinates. */
|
|
396
|
-
bounds: (options = {}) =>
|
|
467
|
+
bounds: (options = {}) => step('bounds', async (context) => {
|
|
397
468
|
const handle = await required(context);
|
|
398
469
|
if (typeof handle.bounds !== 'function')
|
|
399
470
|
throw stopped('unsupported_operation');
|
|
@@ -402,6 +473,26 @@ class TargetApp {
|
|
|
402
473
|
throw stopped('invalid_property');
|
|
403
474
|
return { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
|
|
404
475
|
}, options.timeoutMs),
|
|
476
|
+
/** Whether the control is visible, without ending the session when it
|
|
477
|
+
* is not: one observation, or with timeoutMs a poll until it appears.
|
|
478
|
+
* Absent counts as not visible; ambiguity and reads that never
|
|
479
|
+
* complete still fail. Recorded as an executed action, never an
|
|
480
|
+
* assertion, so it cannot stand in for one. */
|
|
481
|
+
isVisible: (options = {}) => {
|
|
482
|
+
const polling = options.timeoutMs !== undefined;
|
|
483
|
+
const bound = polling ? options.timeoutMs : defaultOperationMs;
|
|
484
|
+
return step('query-visible', async (context) => {
|
|
485
|
+
const result = await this.poll(context, async (context) => {
|
|
486
|
+
const handle = await observe(context);
|
|
487
|
+
return handle ? visibility(handle, context) : false;
|
|
488
|
+
}, bound, polling ? maxObservations : 1, () => { }, true);
|
|
489
|
+
// A poll that Go's worker deadline cut short has not answered:
|
|
490
|
+
// the requested wait never ran to its end.
|
|
491
|
+
if (!result.held && polling && context.deadlineMs >= this.options.deadlineMs)
|
|
492
|
+
throw stopped('deadline');
|
|
493
|
+
return result.held;
|
|
494
|
+
}, bound);
|
|
495
|
+
},
|
|
405
496
|
toBeVisible: (timeoutMs) => assertion('assert-visible', async (handle, context) => await visibility(handle, context), timeoutMs),
|
|
406
497
|
/** Passes when the control is absent or not displayed. */
|
|
407
498
|
toBeHidden: (timeoutMs) => assertion('assert-hidden', async (handle, context) => !await visibility(handle, context), timeoutMs, true),
|
|
@@ -414,9 +505,18 @@ class TargetApp {
|
|
|
414
505
|
}, timeoutMs);
|
|
415
506
|
},
|
|
416
507
|
toHaveState: (name, value, timeoutMs) => {
|
|
417
|
-
if (!['enabled', 'checked'].includes(name) || typeof value !== 'boolean')
|
|
508
|
+
if (!['enabled', 'checked', 'invalid'].includes(name) || typeof value !== 'boolean')
|
|
418
509
|
return assertion('assert-state', async () => { throw stopped('unsupported_state'); }, timeoutMs);
|
|
419
|
-
return assertion('assert-state', async (handle, context) =>
|
|
510
|
+
return assertion('assert-state', async (handle, context) => {
|
|
511
|
+
if (name !== 'invalid')
|
|
512
|
+
return await handle.state(name, context) === value;
|
|
513
|
+
if (typeof handle.invalid !== 'function')
|
|
514
|
+
throw stopped('unsupported_state');
|
|
515
|
+
const invalid = await handle.invalid(context);
|
|
516
|
+
if (typeof invalid !== 'boolean')
|
|
517
|
+
throw stopped('invalid_property');
|
|
518
|
+
return invalid === value;
|
|
519
|
+
}, timeoutMs);
|
|
420
520
|
},
|
|
421
521
|
};
|
|
422
522
|
}
|
|
@@ -447,6 +547,10 @@ function locatorHandle(locator) {
|
|
|
447
547
|
visible: async (context) => { remaining(context); return locator.isVisible(); },
|
|
448
548
|
text: async (context) => await locator.textContent({ timeout: remaining(context) }) ?? '',
|
|
449
549
|
state: async (name, context) => name === 'enabled' ? locator.isEnabled({ timeout: remaining(context) }) : locator.isChecked({ timeout: remaining(context) }),
|
|
550
|
+
invalid: async (context) => locator.evaluate(element => {
|
|
551
|
+
const aria = element.getAttribute('aria-invalid');
|
|
552
|
+
return (aria !== null && aria !== '' && aria !== 'false') || element.matches(':invalid');
|
|
553
|
+
}, undefined, { timeout: remaining(context) }),
|
|
450
554
|
scroll: async (direction, percent, context) => {
|
|
451
555
|
remaining(context);
|
|
452
556
|
await locator.evaluate((element, { direction, percent }) => {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@9l/playwright",
|
|
3
|
-
"version": "0.6.0-beta.
|
|
3
|
+
"version": "0.6.0-beta.4",
|
|
4
4
|
"description": "Playwright fixtures and the versioned 9lives Go engine bridge",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"homepage": "https://github.com/Quality-Max/9lives-runner#local-playwright-sdk",
|