@9l/playwright 0.6.0-beta.1 → 0.6.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.ts CHANGED
@@ -11,5 +11,5 @@ export declare const test: import("@playwright/test").TestType<import("@playwrig
11
11
  }, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
12
12
  export { expect };
13
13
  export { protocolVersion } from './protocol';
14
- export { createTargetTest, TargetApp, webTargetDriver, targetCapabilities } from './targets';
15
- export type { TargetDriver, TargetHandle, TargetIdentity, TargetContext, TargetState, TargetFixtures, TargetOperationOptions } from './targets';
14
+ export { createTargetTest, TargetApp, webTargetDriver, targetCapabilities, TargetSetupError, validTargetSetup, validTargetDiagnostic } from './targets';
15
+ export type { TargetDriver, TargetHandle, TargetIdentity, TargetContext, TargetState, TargetFixtures, TargetOperationOptions, TargetSetupRecord, SetupClassification, TargetDiagnostic, WindowObservation, TargetPoint, TargetRect, TargetSize, ScrollDirection } from './targets';
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.targetCapabilities = exports.webTargetDriver = exports.TargetApp = exports.createTargetTest = exports.protocolVersion = exports.expect = exports.test = void 0;
3
+ exports.validTargetDiagnostic = exports.validTargetSetup = exports.TargetSetupError = exports.targetCapabilities = exports.webTargetDriver = exports.TargetApp = exports.createTargetTest = exports.protocolVersion = exports.expect = exports.test = void 0;
4
4
  const test_1 = require("@playwright/test");
5
5
  Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_1.expect; } });
6
6
  const protocol_1 = require("./protocol");
@@ -37,3 +37,6 @@ Object.defineProperty(exports, "createTargetTest", { enumerable: true, get: func
37
37
  Object.defineProperty(exports, "TargetApp", { enumerable: true, get: function () { return targets_1.TargetApp; } });
38
38
  Object.defineProperty(exports, "webTargetDriver", { enumerable: true, get: function () { return targets_1.webTargetDriver; } });
39
39
  Object.defineProperty(exports, "targetCapabilities", { enumerable: true, get: function () { return targets_1.targetCapabilities; } });
40
+ Object.defineProperty(exports, "TargetSetupError", { enumerable: true, get: function () { return targets_1.TargetSetupError; } });
41
+ Object.defineProperty(exports, "validTargetSetup", { enumerable: true, get: function () { return targets_1.validTargetSetup; } });
42
+ Object.defineProperty(exports, "validTargetDiagnostic", { enumerable: true, get: function () { return targets_1.validTargetDiagnostic; } });
@@ -2,11 +2,11 @@ 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/1";
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;
9
- kind: "web" | "android-fake" | "android";
9
+ kind: "android" | "web" | "android-fake";
10
10
  appId: string;
11
11
  id: string;
12
12
  };
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/1';
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
@@ -4,6 +4,7 @@ const node_crypto_1 = require("node:crypto");
4
4
  const node_fs_1 = require("node:fs");
5
5
  const protocol_1 = require("./protocol");
6
6
  const android_runtime_1 = require("./android-runtime");
7
+ const target_setup_1 = require("./target-setup");
7
8
  function insideAssertion(step) {
8
9
  for (let ancestor = step.parent; ancestor; ancestor = ancestor.parent) {
9
10
  if (ancestor.category === 'expect')
@@ -11,6 +12,13 @@ function insideAssertion(step) {
11
12
  }
12
13
  return false;
13
14
  }
15
+ // A typed target step fails only with "9lives target stopped: <reason>", where
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.
19
+ function targetStopReason(error) {
20
+ return /^(?:Error: )?9lives target stopped: ([a-z_]{1,64})(?: \(accepted 1-[0-9]{1,7} ms\))?$/.exec(error?.message ?? '')?.[1];
21
+ }
14
22
  // Worker logs, error messages, step titles, URLs and attachment bodies never enter
15
23
  // the protocol. IDs are hashes; Go persists only this bounded metadata stream.
16
24
  class EngineReporter {
@@ -73,11 +81,20 @@ class EngineReporter {
73
81
  if (step.category === 'expect' && insideAssertion(step))
74
82
  return;
75
83
  const categories = { 'test.step': 'action', expect: 'assertion', 'pw:api': 'browser', fixture: 'fixture' };
76
- 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;
91
+ const reason = operation && step.error ? targetStopReason(step.error) : undefined;
77
92
  this.emit('step_end', {
78
93
  testId: this.testId(test), retry: result.retry, stepId: `step-${++this.stepSeq}`,
79
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',
80
95
  ...(operation ? { operation } : {}),
96
+ ...(control ? { control } : {}),
97
+ ...(reason ? { reason } : {}),
81
98
  });
82
99
  }
83
100
  onTestEnd(test, result) {
@@ -85,7 +102,60 @@ class EngineReporter {
85
102
  this.emit('engine_error');
86
103
  return;
87
104
  }
105
+ // Bounded classifications from a native target only: at most one made
106
+ // before the test ran (a recovered baseline) and one from a recheck.
107
+ const setups = result.attachments.filter(attachment => attachment.name === '9l.target-setup');
108
+ const stages = setups.map(attachment => { try {
109
+ return JSON.parse(attachment.body?.toString('utf8') ?? '')?.stage;
110
+ }
111
+ catch {
112
+ return undefined;
113
+ } });
114
+ if (result.attachments.filter(attachment => attachment.name === '9l.target-diagnostic').length > 1 || setups.length > 2 || (setups.length === 2 && !(stages[0] === 'open' && stages[1] === 'recheck'))) {
115
+ this.emit('engine_error');
116
+ return;
117
+ }
88
118
  for (const attachment of result.attachments) {
119
+ if (attachment.name === '9l.target-diagnostic') {
120
+ if (!this.target || this.target.kind === 'web' || attachment.contentType !== target_setup_1.targetDiagnosticType || !attachment.body || attachment.body.length > 1024) {
121
+ this.emit('engine_error');
122
+ return;
123
+ }
124
+ let diagnostic;
125
+ try {
126
+ diagnostic = JSON.parse(attachment.body.toString('utf8'));
127
+ }
128
+ catch {
129
+ this.emit('engine_error');
130
+ return;
131
+ }
132
+ if (!(0, target_setup_1.validTargetDiagnostic)(diagnostic)) {
133
+ this.emit('engine_error');
134
+ return;
135
+ }
136
+ this.emit('target_diagnostic', { testId: this.testId(test), retry: result.retry, diagnostic });
137
+ continue;
138
+ }
139
+ if (attachment.name === '9l.target-setup') {
140
+ if (!this.target || this.target.kind === 'web' || attachment.contentType !== target_setup_1.targetSetupType || !attachment.body || attachment.body.length > 512) {
141
+ this.emit('engine_error');
142
+ return;
143
+ }
144
+ let setup;
145
+ try {
146
+ setup = JSON.parse(attachment.body.toString('utf8'));
147
+ }
148
+ catch {
149
+ this.emit('engine_error');
150
+ return;
151
+ }
152
+ if (!(0, target_setup_1.validTargetSetup)(setup)) {
153
+ this.emit('engine_error');
154
+ return;
155
+ }
156
+ this.emit('target_setup', { testId: this.testId(test), retry: result.retry, setup });
157
+ continue;
158
+ }
89
159
  if (attachment.name !== '9l.android-runtime')
90
160
  continue;
91
161
  if (this.target?.kind !== 'android' || attachment.contentType !== android_runtime_1.androidRuntimeType || !attachment.body || attachment.body.length > 2048) {
@@ -0,0 +1,50 @@
1
+ export declare const targetSetupType = "application/vnd.9l.target-setup+json";
2
+ export declare const setupClassifications: readonly ["blocked", "dirty", "mismatch", "observer", "unknown"];
3
+ export type SetupClassification = typeof setupClassifications[number];
4
+ /** Reasons per classification; Go rejects any other pair. */
5
+ export declare const setupReasons: Record<SetupClassification, readonly string[]>;
6
+ export type TargetSetupRecord = {
7
+ classification: SetupClassification;
8
+ reason: string;
9
+ /** `open`: found before any application operation; `recheck`: found after a failed assertion. */
10
+ stage: 'open' | 'recheck';
11
+ /** A user-declared, non-destructive recovery the driver took before the test ran. */
12
+ recovery?: {
13
+ method: 'back';
14
+ presses: number;
15
+ restored: boolean;
16
+ };
17
+ };
18
+ export declare function validTargetSetup(value: unknown): value is TargetSetupRecord;
19
+ /** Thrown by a driver's open (or returned by its recheck) to classify the
20
+ * device or app state instead of letting the failure read as an application
21
+ * defect. The session stops with reason `setup_<classification>`. */
22
+ export declare class TargetSetupError extends Error {
23
+ readonly record: TargetSetupRecord;
24
+ constructor(record: TargetSetupRecord, cause?: unknown);
25
+ }
26
+ /** Opt-in, metadata-only description of a failed target operation: timing,
27
+ * requested coordinates, viewport and the app's window count/focus at the
28
+ * last mutation and after the failure. It states what was observed, never a
29
+ * cause, and carries no screen content, hierarchy, text or identifiers. */
30
+ export declare const targetDiagnosticType = "application/vnd.9l.target-diagnostic+json";
31
+ export type WindowObservation = {
32
+ windows: number;
33
+ focus: 'app' | 'foreign' | 'none' | 'unknown';
34
+ };
35
+ export type TargetDiagnostic = {
36
+ operation: string;
37
+ reason: string;
38
+ elapsedMs: number;
39
+ x?: number;
40
+ y?: number;
41
+ point?: true;
42
+ viewportWidth?: number;
43
+ viewportHeight?: number;
44
+ /** -1: not observed. */
45
+ windowsBefore: number;
46
+ windowsAfter: number;
47
+ focusBefore?: WindowObservation['focus'];
48
+ focusAfter?: WindowObservation['focus'];
49
+ };
50
+ export declare function validTargetDiagnostic(value: unknown): value is TargetDiagnostic;
@@ -0,0 +1,73 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.targetDiagnosticType = exports.TargetSetupError = exports.setupReasons = exports.setupClassifications = exports.targetSetupType = void 0;
4
+ exports.validTargetSetup = validTargetSetup;
5
+ exports.validTargetDiagnostic = validTargetDiagnostic;
6
+ // A native driver's bounded classification of the device or app state. It
7
+ // crosses the worker bridge as closed metadata; no screen content, window
8
+ // titles, hierarchy or device identifiers are part of it.
9
+ exports.targetSetupType = 'application/vnd.9l.target-setup+json';
10
+ exports.setupClassifications = ['blocked', 'dirty', 'mismatch', 'observer', 'unknown'];
11
+ /** Reasons per classification; Go rejects any other pair. */
12
+ exports.setupReasons = {
13
+ blocked: ['device-locked', 'screen-off'],
14
+ dirty: ['extra-window', 'foreign-focus', 'ime-showing'],
15
+ /** The device is not in the posture or width the spec declared. */
16
+ mismatch: ['posture', 'display-width', 'build-digest', 'build-version', 'build-signer', 'biometrics-unavailable'],
17
+ /** The accessibility snapshot still reported an element whose window the
18
+ * window manager no longer lists: observer staleness, not the app. */
19
+ observer: ['window-gone-element-displayed'],
20
+ unknown: ['device-state-unknown'],
21
+ };
22
+ function validTargetSetup(value) {
23
+ if (!value || typeof value !== 'object' || Array.isArray(value))
24
+ return false;
25
+ const r = value;
26
+ const keys = Object.keys(r);
27
+ if (keys.some(key => !['classification', 'reason', 'stage', 'recovery'].includes(key)) || keys.length < 3)
28
+ return false;
29
+ if (!exports.setupClassifications.includes(r.classification) || typeof r.reason !== 'string' ||
30
+ !exports.setupReasons[r.classification].includes(r.reason) || !['open', 'recheck'].includes(r.stage))
31
+ return false;
32
+ if (r.classification === 'observer' && r.stage !== 'recheck')
33
+ return false;
34
+ if (r.recovery === undefined)
35
+ return true;
36
+ const recovery = r.recovery;
37
+ return !!recovery && typeof recovery === 'object' && !Array.isArray(recovery) && Object.keys(recovery).length === 3 &&
38
+ recovery.method === 'back' && Number.isInteger(recovery.presses) && recovery.presses >= 0 && recovery.presses <= 16 &&
39
+ typeof recovery.restored === 'boolean' && r.classification === 'dirty' && r.stage === 'open';
40
+ }
41
+ /** Thrown by a driver's open (or returned by its recheck) to classify the
42
+ * device or app state instead of letting the failure read as an application
43
+ * defect. The session stops with reason `setup_<classification>`. */
44
+ class TargetSetupError extends Error {
45
+ record;
46
+ constructor(record, cause) {
47
+ super(`9lives target setup ${record.classification}: ${record.reason}`, cause === undefined ? undefined : { cause });
48
+ this.record = record;
49
+ if (!validTargetSetup(record))
50
+ throw new Error('9lives target setup: invalid record');
51
+ }
52
+ }
53
+ exports.TargetSetupError = TargetSetupError;
54
+ /** Opt-in, metadata-only description of a failed target operation: timing,
55
+ * requested coordinates, viewport and the app's window count/focus at the
56
+ * last mutation and after the failure. It states what was observed, never a
57
+ * cause, and carries no screen content, hierarchy, text or identifiers. */
58
+ exports.targetDiagnosticType = 'application/vnd.9l.target-diagnostic+json';
59
+ function validTargetDiagnostic(value) {
60
+ if (!value || typeof value !== 'object' || Array.isArray(value))
61
+ return false;
62
+ const d = value;
63
+ const pixel = (v) => Number.isInteger(v) && v >= 0 && v <= 65_535;
64
+ const windows = (v) => Number.isInteger(v) && v >= -1 && v <= 1024;
65
+ const focus = (v) => v === undefined || ['app', 'foreign', 'none', 'unknown'].includes(v);
66
+ if (Object.keys(d).some(key => !['operation', 'reason', 'elapsedMs', 'x', 'y', 'point', 'viewportWidth', 'viewportHeight', 'windowsBefore', 'windowsAfter', 'focusBefore', 'focusAfter'].includes(key)))
67
+ return false;
68
+ return typeof d.operation === 'string' && /^[a-z-]{1,32}$/.test(d.operation) && typeof d.reason === 'string' && /^[a-z_]{1,64}$/.test(d.reason) &&
69
+ Number.isInteger(d.elapsedMs) && d.elapsedMs >= 0 && d.elapsedMs <= 3_600_000 &&
70
+ (d.point === undefined ? d.x === undefined && d.y === undefined : d.point === true && pixel(d.x) && pixel(d.y)) &&
71
+ (d.viewportWidth === undefined ? d.viewportHeight === undefined : pixel(d.viewportWidth) && pixel(d.viewportHeight) && d.viewportWidth > 0 && d.viewportHeight > 0) &&
72
+ windows(d.windowsBefore) && windows(d.windowsAfter) && focus(d.focusBefore) && focus(d.focusAfter);
73
+ }
package/dist/targets.d.ts CHANGED
@@ -1,7 +1,23 @@
1
1
  import { type Page } from '@playwright/test';
2
2
  import { targetVersion } from './protocol';
3
3
  import { type AndroidRuntime } from './android-runtime';
4
- export declare const targetCapabilities: readonly ["open", "reset", "test-id", "tap", "fill", "visible", "text", "state"];
4
+ import { type TargetSetupRecord, type TargetDiagnostic } from './target-setup';
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", "foreground", "device-serial", "fingerprint"];
7
+ export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
8
+ /** Integer device coordinates: physical pixels on Android, CSS pixels in the web viewport. */
9
+ export type TargetPoint = {
10
+ x: number;
11
+ y: number;
12
+ };
13
+ export type TargetRect = TargetPoint & {
14
+ width: number;
15
+ height: number;
16
+ };
17
+ export type TargetSize = {
18
+ width: number;
19
+ height: number;
20
+ };
5
21
  export type TargetIdentity = {
6
22
  kind: 'web' | 'android-fake' | 'android';
7
23
  appId: string;
@@ -10,7 +26,10 @@ export type TargetContext = {
10
26
  signal: AbortSignal;
11
27
  deadlineMs: number;
12
28
  };
13
- 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';
14
33
  /** Per-call bound, capped by Go's worker deadline. */
15
34
  export type TargetOperationOptions = {
16
35
  timeoutMs?: number;
@@ -23,7 +42,13 @@ export interface TargetHandle {
23
42
  fill(value: string, context: TargetContext): Promise<void>;
24
43
  visible(context: TargetContext): Promise<boolean>;
25
44
  text(context: TargetContext): Promise<string>;
26
- 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>;
49
+ /** One bounded scroll gesture inside this element; percent of its size. */
50
+ scroll?(direction: ScrollDirection, percent: number, context: TargetContext): Promise<void>;
51
+ bounds?(context: TargetContext): Promise<TargetRect>;
27
52
  }
28
53
  export interface TargetDriver extends TargetIdentity {
29
54
  version: typeof targetVersion;
@@ -32,9 +57,56 @@ export interface TargetDriver extends TargetIdentity {
32
57
  reset(context: TargetContext): Promise<void>;
33
58
  /** Observe at most two matches; two means ambiguous and must fail. */
34
59
  observeTestId(id: string, context: TargetContext): Promise<readonly TargetHandle[]>;
60
+ /** Platform back: Android's Back key, the browser's history. */
61
+ back?(context: TargetContext): Promise<void>;
62
+ /** Software keyboard visibility; an unreadable state throws. Android only. */
63
+ keyboardShown?(context: TargetContext): Promise<boolean>;
64
+ /** Dismiss the keyboard without changing the input method. Android only. */
65
+ hideKeyboard?(context: TargetContext): Promise<void>;
66
+ /** One touch down/up at device coordinates. */
67
+ tapAt?(point: TargetPoint, context: TargetContext): Promise<void>;
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>;
79
+ /** SHA-256 of a screenshot of the target display, computed in memory. The
80
+ * image itself is never returned, written or attached. */
81
+ screenDigest?(context: TargetContext): Promise<string>;
82
+ /** Stop and relaunch the configured app, keeping its data. Android only. */
83
+ terminate?(context: TargetContext): Promise<void>;
84
+ activate?(context: TargetContext): Promise<void>;
35
85
  close(): Promise<void>;
36
86
  runtime?(): AndroidRuntime | undefined;
87
+ /** After a successful open: the setup record of a declared recovery that
88
+ * restored the baseline, so the receipt shows the test ran from it. */
89
+ setup?(): TargetSetupRecord | undefined;
90
+ /** After a completed assertion failure, while the driver is still open:
91
+ * classify the device state (a locked phone, for example) so the failure
92
+ * reads as inconclusive setup, never as an application defect. It must only
93
+ * read state; it never acts on the device. Its own errors are ignored. */
94
+ recheck?(context: TargetContext, failed: {
95
+ operation: string;
96
+ }): Promise<TargetSetupRecord | undefined>;
97
+ /** Opt-in: describe a failed operation as bounded metadata, captured before
98
+ * fixture teardown. Read-only; errors are ignored; one record per test. */
99
+ diagnose?(failure: {
100
+ operation: string;
101
+ reason: string;
102
+ elapsedMs: number;
103
+ point?: TargetPoint;
104
+ }, context: TargetContext): Promise<TargetDiagnostic | undefined>;
37
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;
38
110
  /** Deterministic shared operations; browser/device handles stay in the worker. */
39
111
  export declare class TargetApp {
40
112
  private driver;
@@ -44,6 +116,7 @@ export declare class TargetApp {
44
116
  private busy;
45
117
  private reason;
46
118
  private closing?;
119
+ private diagnosed;
47
120
  private externalAbort;
48
121
  constructor(driver: TargetDriver, expected: TargetIdentity, options: {
49
122
  deadlineMs: number;
@@ -58,13 +131,88 @@ export declare class TargetApp {
58
131
  close(): Promise<void>;
59
132
  /** Permanently stop this session, including a pending mutation. */
60
133
  cancel(): void;
134
+ /** Opt-in failure diagnostics: ask the driver once per test, while it is
135
+ * still open, and attach only a validated record. Never changes the outcome. */
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;
61
141
  private perform;
62
142
  open(options?: TargetOperationOptions): Promise<void>;
63
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;
151
+ /** Poll a check to its bound. A completed false observation is an assertion
152
+ * failure even if a later read stalls; a bound reached before any completed
153
+ * check is a deadline; failed reads alone keep their own operation error.
154
+ * After a completed failure, the driver may reclassify the device state. */
155
+ private assertLoop;
156
+ private optional;
157
+ /** Platform back: Android's Back key, the browser's history. */
158
+ back(options?: TargetOperationOptions): Promise<void>;
159
+ /** Dismiss the software keyboard, keeping the selected input method. Android only. */
160
+ hideKeyboard(options?: TargetOperationOptions): Promise<void>;
161
+ /** Android only: assert the software keyboard is shown or hidden. */
162
+ toHaveKeyboard(visible: boolean, timeoutMs?: number): Promise<void>;
163
+ /** One touch down/up at device coordinates, for example outside a pane.
164
+ * Coordinates are integers inside the viewport, checked against the
165
+ * driver's viewport when it reports one; nothing is retried. */
166
+ tapAt(point: TargetPoint, options?: TargetOperationOptions): Promise<void>;
167
+ viewport(options?: TargetOperationOptions): Promise<{
168
+ width: number;
169
+ height: number;
170
+ }>;
171
+ /** A digest of the active display's current image, for settling checks
172
+ * (two equal digests mean nothing moved). The image is never retained. */
173
+ screenDigest(options?: TargetOperationOptions): Promise<string>;
174
+ /** Stop the configured app without clearing its data. Android only. */
175
+ terminate(options?: TargetOperationOptions): Promise<void>;
176
+ /** Bring the configured app back to the foreground. Android only. */
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;
64
193
  getByTestId(id: string): {
65
194
  tap: (options?: TargetOperationOptions) => Promise<any>;
66
195
  fill: (value: string, options?: TargetOperationOptions) => Promise<void>;
196
+ /** One bounded scroll gesture inside this control, by a fraction of its size. */
197
+ scroll: (direction: ScrollDirection, options?: TargetOperationOptions & {
198
+ percent?: number;
199
+ }) => Promise<void>;
200
+ /** The control's rectangle in device coordinates. */
201
+ bounds: (options?: TargetOperationOptions) => Promise<{
202
+ x: number;
203
+ y: number;
204
+ width: number;
205
+ height: number;
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>;
67
213
  toBeVisible: (timeoutMs?: number) => Promise<void>;
214
+ /** Passes when the control is absent or not displayed. */
215
+ toBeHidden: (timeoutMs?: number) => Promise<void>;
68
216
  toHaveText: (value: string, timeoutMs?: number) => Promise<void>;
69
217
  toHaveState: (name: TargetState, value: boolean, timeoutMs?: number) => Promise<void>;
70
218
  };
@@ -86,4 +234,3 @@ type TargetOptions = {
86
234
  * context or browser dependency, including when the default config uses them.
87
235
  * Specs load without 9l (listing, editors); using `app` requires 9l run --sdk --target. */
88
236
  export declare function createTargetTest(options: TargetOptions): import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & TargetFixtures, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
89
- export {};