@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 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 native mobile support are not qualified features.
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. All matches remain strict
6
- * and scoped to the configured package; arbitrary XPath is not accepted. */
7
- export type AndroidControl = ({
8
- accessibilityId: string;
9
- text?: never;
10
- accessibilityIdSuffix?: never;
11
- } | {
12
- text: string;
13
- accessibilityId?: never;
14
- accessibilityIdSuffix?: never;
15
- } | {
16
- accessibilityIdSuffix: string;
17
- text?: never;
18
- accessibilityId?: never;
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
- if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,127}$/.test(id) || !control ||
170
- Object.keys(control).some(k => !['text', 'accessibilityId', 'accessibilityIdSuffix', 'className', 'selected'].includes(k)) ||
171
- [control.text, control.accessibilityId, control.accessibilityIdSuffix].filter(v => v !== undefined).length !== 1 ||
172
- typeof (control.text ?? control.accessibilityId ?? control.accessibilityIdSuffix) !== 'string' ||
173
- !/^[^\x00-\x1f\x7f]{1,128}$/.test(control.text ?? control.accessibilityId ?? control.accessibilityIdSuffix) ||
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
- const matches = async (id, c) => {
403
- if (!/^[a-zA-Z_][a-zA-Z0-9_]{0,127}$/.test(id))
404
- throw failure('invalid_resource_id');
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 selector = `new UiSelector().packageName(${JSON.stringify(options.appPackage)})`;
407
- if (control) {
408
- if (control.accessibilityIdSuffix !== undefined) {
409
- const literal = control.accessibilityIdSuffix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
410
- selector += `.descriptionMatches(${JSON.stringify(`.*${literal}$`)})`;
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(${JSON.stringify(control.text)})` : `.description(${JSON.stringify(control.accessibilityId)})`;
464
+ selector += control.accessibilityId === undefined ? `.text(${selectorString(control.text)})` : `.description(${selectorString(control.accessibilityId)})`;
414
465
  if (control.className)
415
- selector += `.className(${JSON.stringify(control.className)})`;
466
+ selector += `.className(${selectorString(control.className)})`;
416
467
  if (control.selected !== undefined)
417
468
  selector += `.selected(${control.selected})`;
418
469
  }
419
- const result = await endpoint('/elements', c, 'POST', control ? { using: '-android uiautomator', value: selector } : { using: 'id', value: `${options.appPackage}:id/${id}` });
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 value = await endpoint(`/element/${await resolveOne(id, c)}/displayed`, c);
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
- emulator = (0, node_child_process_1.spawn)(emulatorPath, ['-avd', options.avd, '-read-only', '-no-snapshot', '-no-audio', '-report-console', `unix:${consoleSocket}`, ...(options.headless === false ? [] : ['-no-window']), '-gpu', 'swiftshader_indirect'], { env, stdio: 'ignore' });
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
@@ -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/2";
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/2';
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. Only a token of that exact form crosses
17
- // the bridge; any other error text, or none, sends no reason.
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})$/.exec(error?.message ?? '')?.[1];
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 operation = this.target && step.category === 'test.step' && step.location?.file === protocol_1.targetStepFile && step.title.startsWith('9l target ') ? step.title.slice('9l target '.length) : undefined;
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
  }
@@ -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
- export type TargetState = 'enabled' | 'checked';
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: TargetState, context: TargetContext): Promise<boolean>;
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
- async perform(operation, body, timeoutMs = defaultOperationMs, maxTimeoutMs = maxOperationMs, deadlineReason = () => 'deadline', point) {
124
- // The SDK location marks this as a typed target step for the reporter.
125
- return test_1.test.step(`9l target ${operation}`, async () => {
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 ?? (this.driver.kind === 'android' ? 180_000 : undefined), this.driver.kind === 'android' ? 180_000 : maxOperationMs);
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 interval = Math.max(25, Math.ceil(timeoutMs / maxObservations));
232
- let last, slowest = 0;
233
- for (let poll = 0; poll < maxObservations; poll++) {
234
- context.signal.throwIfAborted();
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, maxOperationMs, () => 'deadline', validPoint(point) ? { x: point.x, y: point.y } : undefined);
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 = {}) => this.perform('tap', async (context) => (await required(context)).tap(context), options.timeoutMs),
380
- fill: (value, options = {}) => this.perform('fill', async (context) => {
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 = {}) => this.perform('scroll', async (context) => {
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 = {}) => this.perform('bounds', async (context) => {
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) => await handle.state(name, context) === value, timeoutMs);
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.2",
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",