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

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.
@@ -0,0 +1,64 @@
1
+ /** Keyguard and wakefulness markers from `dumpsys window` and `dumpsys power`. */
2
+ export declare const deviceStatePattern = "mShowingLockscreen=|isStatusBarKeyguard=|(^| )showing=|mKeyguardShowing=|mDreamingLockscreen=|mInputRestricted=|mWakefulness=";
3
+ export type DeviceState = 'unlocked' | 'locked' | 'screen-off' | 'unknown';
4
+ export declare function parseDeviceState(text: string): DeviceState;
5
+ /** Window and focus markers from `dumpsys window windows`. */
6
+ export declare const windowPattern = "Window #[0-9]+ Window\\{|mCurrentFocus=";
7
+ export type WindowState = {
8
+ windows: number;
9
+ focus: 'app' | 'foreign' | 'none' | 'unknown';
10
+ };
11
+ /** Counts the windows titled with the app's package (its activity and its
12
+ * dialogs; anonymous popups are not attributed) and classifies focus. */
13
+ export declare function parseWindows(text: string, appPackage: string): WindowState;
14
+ /** Software keyboard visibility from `dumpsys input_method`. */
15
+ export declare const imePattern = "mInputShown=";
16
+ export type ImeState = 'shown' | 'hidden' | 'unknown';
17
+ export declare function parseIme(text: string): ImeState;
18
+ /** Physical displays from `dumpsys display`: the DisplayDeviceInfo lines carry
19
+ * the physical id, size, density and power state; the logical DisplayInfo
20
+ * lines carry the current app size and density after rotation and overrides. */
21
+ export declare const displayPattern = "DisplayDeviceInfo\\{|mBaseDisplayInfo=|mOverrideDisplayInfo=";
22
+ export type DisplayInfo = {
23
+ id: string;
24
+ width: number;
25
+ height: number;
26
+ density: number;
27
+ on: boolean;
28
+ };
29
+ export declare function parseDisplays(text: string): DisplayInfo[];
30
+ /** The display to target: the one powered on when exactly one is. */
31
+ export declare function activeDisplay(displays: DisplayInfo[]): DisplayInfo | undefined;
32
+ /** Current logical layout per physical display id: the app size (which
33
+ * follows rotation) and the effective density (which follows overrides).
34
+ * An override entry replaces the base entry of the same display. */
35
+ export type LogicalDisplay = {
36
+ width: number;
37
+ height: number;
38
+ density: number;
39
+ };
40
+ export declare function parseLogicalDisplays(text: string): Map<string, LogicalDisplay>;
41
+ /** Fold posture from `dumpsys device_state`: the committed state's name. A
42
+ * device without the service has no posture to report and is flat. */
43
+ export declare const posturePattern = "Committed state:|mCommittedState=|No device state|not found|Can.t find service";
44
+ export declare const postures: readonly ["opened", "half-opened", "closed", "flat", "unknown"];
45
+ export type Posture = typeof postures[number];
46
+ export declare function parsePosture(text: string): Posture;
47
+ /** Package version from `dumpsys package <pkg>`. Each field starts its own
48
+ * (indented) line, so text inside another field's value never matches. */
49
+ export declare const packagePattern = "versionCode=|versionName=";
50
+ export type PackageVersion = {
51
+ versionCode: string;
52
+ versionName: string;
53
+ };
54
+ export declare function parsePackageVersion(text: string): PackageVersion;
55
+ /** The first signer's certificate digest from `apksigner verify --print-certs`:
56
+ * a complete output line, so a certificate DN quoting one never matches. */
57
+ export declare function parseSigner(text: string): string | undefined;
58
+ /** The emulator's version: `emulator -version` (macOS prints the line on
59
+ * stdout, Linux on stderr) or, when that command fails or prints none, the
60
+ * emulator package's `Pkg.Revision`. An interruption (cancellation, the
61
+ * deadline, a closed driver) propagates instead of falling back. */
62
+ export declare function parseEmulatorVersion(output: string): string | undefined;
63
+ export declare function parsePackageRevision(properties: string): string | undefined;
64
+ export declare function emulatorVersion(run: () => Promise<string>, properties: () => Promise<string>, interrupted: () => void): Promise<string | undefined>;
@@ -0,0 +1,134 @@
1
+ "use strict";
2
+ // Bounded readers of Android device state. They parse lines the driver
3
+ // already filtered on the device; nothing here keeps or returns the text.
4
+ // Every parser answers `unknown` when its markers are absent, so an
5
+ // unfamiliar Android build is reported as unknown, never guessed.
6
+ Object.defineProperty(exports, "__esModule", { value: true });
7
+ exports.packagePattern = exports.postures = exports.posturePattern = exports.displayPattern = exports.imePattern = exports.windowPattern = exports.deviceStatePattern = void 0;
8
+ exports.parseDeviceState = parseDeviceState;
9
+ exports.parseWindows = parseWindows;
10
+ exports.parseIme = parseIme;
11
+ exports.parseDisplays = parseDisplays;
12
+ exports.activeDisplay = activeDisplay;
13
+ exports.parseLogicalDisplays = parseLogicalDisplays;
14
+ exports.parsePosture = parsePosture;
15
+ exports.parsePackageVersion = parsePackageVersion;
16
+ exports.parseSigner = parseSigner;
17
+ exports.parseEmulatorVersion = parseEmulatorVersion;
18
+ exports.parsePackageRevision = parsePackageRevision;
19
+ exports.emulatorVersion = emulatorVersion;
20
+ /** Keyguard and wakefulness markers from `dumpsys window` and `dumpsys power`. */
21
+ exports.deviceStatePattern = 'mShowingLockscreen=|isStatusBarKeyguard=|(^| )showing=|mKeyguardShowing=|mDreamingLockscreen=|mInputRestricted=|mWakefulness=';
22
+ function parseDeviceState(text) {
23
+ const wakefulness = /mWakefulness=(\w+)/.exec(text)?.[1];
24
+ if (wakefulness === 'Asleep' || wakefulness === 'Dozing')
25
+ return 'screen-off';
26
+ const markers = [...text.matchAll(/(?:^|[\s{,])(mShowingLockscreen|isStatusBarKeyguard|showing|mKeyguardShowing|mDreamingLockscreen|mInputRestricted)=(true|false)/g)];
27
+ if (markers.length === 0)
28
+ return 'unknown';
29
+ return markers.some(([, , value]) => value === 'true') ? 'locked' : 'unlocked';
30
+ }
31
+ /** Window and focus markers from `dumpsys window windows`. */
32
+ exports.windowPattern = 'Window #[0-9]+ Window\\{|mCurrentFocus=';
33
+ /** Counts the windows titled with the app's package (its activity and its
34
+ * dialogs; anonymous popups are not attributed) and classifies focus. */
35
+ function parseWindows(text, appPackage) {
36
+ const escaped = appPackage.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
37
+ const windows = [...text.matchAll(new RegExp(`Window #[0-9]+ Window\\{[0-9a-f]+ u[0-9]+ ${escaped}(?:[/ }:]|$)`, 'gm'))].length;
38
+ // One focus line per display: the app's focus on any display wins over
39
+ // another display's, and a focused window over a display with none.
40
+ const focus = [...text.matchAll(/mCurrentFocus=(null|Window\{[0-9a-f]+ u[0-9]+ ([^ /}]+)[^}]*\})/g)];
41
+ if (!focus.length)
42
+ return { windows, focus: 'unknown' };
43
+ if (focus.some(line => line[2] === appPackage))
44
+ return { windows, focus: 'app' };
45
+ return { windows, focus: focus.some(line => line[1] !== 'null') ? 'foreign' : 'none' };
46
+ }
47
+ /** Software keyboard visibility from `dumpsys input_method`. */
48
+ exports.imePattern = 'mInputShown=';
49
+ function parseIme(text) {
50
+ const value = /mInputShown=(true|false)/.exec(text)?.[1];
51
+ return value === undefined ? 'unknown' : value === 'true' ? 'shown' : 'hidden';
52
+ }
53
+ /** Physical displays from `dumpsys display`: the DisplayDeviceInfo lines carry
54
+ * the physical id, size, density and power state; the logical DisplayInfo
55
+ * lines carry the current app size and density after rotation and overrides. */
56
+ exports.displayPattern = 'DisplayDeviceInfo\\{|mBaseDisplayInfo=|mOverrideDisplayInfo=';
57
+ function parseDisplays(text) {
58
+ const displays = [];
59
+ for (const [, body] of text.matchAll(/DisplayDeviceInfo\{([^\n]*)/g)) {
60
+ const id = /uniqueId="?local:([0-9]{1,24})"?/.exec(body)?.[1];
61
+ const size = /(?:^|[\s,])([0-9]{2,5}) x ([0-9]{2,5})(?:[\s,]|$)/.exec(body);
62
+ const density = /density ([0-9]{2,4})(?:[\s,]|$)/.exec(body)?.[1];
63
+ const state = /state (ON|OFF|DOZE|UNKNOWN|VR)(?:[\s,}]|$)/.exec(body)?.[1];
64
+ // A device's cached `mInfo=DisplayDeviceInfo` repeats its top-level
65
+ // record; the first record per physical id stands.
66
+ if (!id || !size || !density || displays.some(display => display.id === id))
67
+ continue;
68
+ displays.push({ id, width: Number(size[1]), height: Number(size[2]), density: Number(density), on: state === 'ON' });
69
+ }
70
+ return displays;
71
+ }
72
+ /** The display to target: the one powered on when exactly one is. */
73
+ function activeDisplay(displays) {
74
+ const on = displays.filter(display => display.on);
75
+ return on.length === 1 ? on[0] : displays.length === 1 ? displays[0] : undefined;
76
+ }
77
+ function parseLogicalDisplays(text) {
78
+ const logical = new Map();
79
+ for (const [, kind, body] of text.matchAll(/(mBaseDisplayInfo|mOverrideDisplayInfo)=DisplayInfo\{([^\n]*)/g)) {
80
+ const id = /uniqueId "local:([0-9]{1,24})"/.exec(body)?.[1];
81
+ // Whole comma-delimited fields only: `largest app` and `smallest app`
82
+ // carry the nominal range, not the current size.
83
+ const app = /(?:^|, )app ([0-9]{2,5}) x ([0-9]{2,5})(?:,|$)/.exec(body);
84
+ const density = /(?:^|, )density ([0-9]{2,4})(?:[\s,(]|$)/.exec(body)?.[1];
85
+ if (!id || !app || !density || (kind === 'mBaseDisplayInfo' && logical.has(id)))
86
+ continue;
87
+ logical.set(id, { width: Number(app[1]), height: Number(app[2]), density: Number(density) });
88
+ }
89
+ return logical;
90
+ }
91
+ /** Fold posture from `dumpsys device_state`: the committed state's name. A
92
+ * device without the service has no posture to report and is flat. */
93
+ exports.posturePattern = 'Committed state:|mCommittedState=|No device state|not found|Can.t find service';
94
+ exports.postures = ['opened', 'half-opened', 'closed', 'flat', 'unknown'];
95
+ function parsePosture(text) {
96
+ if (/Can.t find service|not found|No device state/i.test(text) || text.trim() === '')
97
+ return text.trim() === '' ? 'unknown' : 'flat';
98
+ const name = /(?:Committed state:|mCommittedState=)[^\n]*?name='?([A-Z_]+)'?/.exec(text)?.[1];
99
+ // The documented state names, matched exactly; anything else is unknown.
100
+ return { OPENED: 'opened', HALF_OPENED: 'half-opened', CLOSED: 'closed' }[name ?? ''] ?? 'unknown';
101
+ }
102
+ /** Package version from `dumpsys package <pkg>`. Each field starts its own
103
+ * (indented) line, so text inside another field's value never matches. */
104
+ exports.packagePattern = 'versionCode=|versionName=';
105
+ function parsePackageVersion(text) {
106
+ const code = /^[ \t]*versionCode=([0-9]{1,10})(?:[ \t]|$)/m.exec(text)?.[1];
107
+ const name = /^[ \t]*versionName=([A-Za-z0-9._+-]{1,64})[ \t]*$/m.exec(text)?.[1];
108
+ return { versionCode: code ?? 'unknown', versionName: name ?? 'unknown' };
109
+ }
110
+ /** The first signer's certificate digest from `apksigner verify --print-certs`:
111
+ * a complete output line, so a certificate DN quoting one never matches. */
112
+ function parseSigner(text) {
113
+ return /^Signer #1 certificate SHA-256 digest: ([a-f0-9]{64})[ \t]*$/m.exec(text)?.[1];
114
+ }
115
+ /** The emulator's version: `emulator -version` (macOS prints the line on
116
+ * stdout, Linux on stderr) or, when that command fails or prints none, the
117
+ * emulator package's `Pkg.Revision`. An interruption (cancellation, the
118
+ * deadline, a closed driver) propagates instead of falling back. */
119
+ function parseEmulatorVersion(output) {
120
+ return /Android emulator version ([0-9]{1,3}(?:\.[0-9]{1,5}){0,3})/.exec(output)?.[1];
121
+ }
122
+ function parsePackageRevision(properties) {
123
+ return /^Pkg\.Revision=([0-9]{1,3}(?:\.[0-9]{1,5}){0,3})\s*$/m.exec(properties)?.[1];
124
+ }
125
+ async function emulatorVersion(run, properties, interrupted) {
126
+ let version;
127
+ try {
128
+ version = parseEmulatorVersion(await run());
129
+ }
130
+ catch {
131
+ interrupted();
132
+ }
133
+ return version ?? parsePackageRevision(await properties().catch(() => ''));
134
+ }
@@ -0,0 +1,65 @@
1
+ /** The Appium server and UiAutomator2 driver releases the adapter is qualified with. */
2
+ export declare const androidVersions: {
3
+ readonly appium: "3.8.0";
4
+ readonly uiautomator2: "8.7.0";
5
+ };
6
+ /** The build-tools release whose aapt2 and apksigner the adapter runs. */
7
+ export declare const androidBuildTools = "35.0.0";
8
+ /** Where the pinned tooling is looked for when NINELIVES_ANDROID_TOOLS is unset, under the home directory. */
9
+ export declare const androidToolsDirectory = ".9l/android-tools";
10
+ /** The install command for the pinned tooling into a prefix directory. */
11
+ export declare const androidToolsInstall: (prefix: string) => string;
12
+ /** The variables that can choose the SDK root. `9l run` passes none of them
13
+ * to tests unless named with --pass-env, so a worker can discover another
14
+ * root than the shell that ran doctor or a setup script. */
15
+ export declare const androidSdkVariables: readonly ["ANDROID_HOME", "ANDROID_SDK_ROOT", "HOMEBREW_PREFIX"];
16
+ /** How a root was found: an environment variable, a common install location or the default tools directory. */
17
+ export type AndroidSource = 'ANDROID_HOME' | 'ANDROID_SDK_ROOT' | 'homebrew' | 'android-studio' | 'NINELIVES_ANDROID_TOOLS' | 'default';
18
+ export type AndroidCandidate = {
19
+ path: string;
20
+ source: AndroidSource;
21
+ };
22
+ export type AndroidDefaults = {
23
+ /** The SDK root, or undefined when neither variable is set and no common location exists. */
24
+ sdkRoot?: string;
25
+ sdkSource?: AndroidSource;
26
+ /** Set when ANDROID_SDK_ROOT names another directory than the ANDROID_HOME that won. */
27
+ sdkRootIgnored?: boolean;
28
+ /** The directory whose node_modules holds the pinned Appium tooling; it may not exist yet. */
29
+ toolsRoot?: string;
30
+ toolsSource?: AndroidSource;
31
+ };
32
+ type Environment = Record<string, string | undefined>;
33
+ export type AndroidDiscoveryOptions = {
34
+ env?: Environment;
35
+ home?: string;
36
+ platform?: NodeJS.Platform;
37
+ isDirectory?: (path: string) => boolean;
38
+ };
39
+ /** Common SDK locations in the order they are tried after ANDROID_HOME and
40
+ * ANDROID_SDK_ROOT: the Homebrew command-line tools under HOMEBREW_PREFIX and
41
+ * the standard Homebrew prefixes, then the Android Studio default for the
42
+ * platform. `brew` itself is not run. */
43
+ export declare function androidSdkCandidates(options?: AndroidDiscoveryOptions): AndroidCandidate[];
44
+ /** The SDK root and pinned-tooling directory the driver uses when its options
45
+ * omit them. ANDROID_HOME wins, then ANDROID_SDK_ROOT, then the first common
46
+ * location that exists. A variable that is set is used as given, even if the
47
+ * directory is missing, so a misconfiguration is reported rather than hidden.
48
+ * The tooling directory is NINELIVES_ANDROID_TOOLS, else ~/.9l/android-tools.
49
+ * Relative values resolve against the current directory. */
50
+ export declare function androidDefaults(options?: AndroidDiscoveryOptions): AndroidDefaults;
51
+ /** The SDK executables the driver runs, under one SDK root. */
52
+ export declare function androidToolPaths(sdkRoot: string, platform?: NodeJS.Platform): {
53
+ adb: string;
54
+ emulator: string;
55
+ buildTools: string;
56
+ aapt2: string;
57
+ apksigner: string;
58
+ };
59
+ /** The pinned packages' manifests and the Appium entry point under a tooling directory. */
60
+ export declare function androidToolingPaths(toolsRoot: string, platform?: NodeJS.Platform): {
61
+ appium: string;
62
+ appiumEntry: string;
63
+ uiautomator2: string;
64
+ };
65
+ export {};
@@ -0,0 +1,114 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.androidSdkVariables = exports.androidToolsInstall = exports.androidToolsDirectory = exports.androidBuildTools = exports.androidVersions = void 0;
4
+ exports.androidSdkCandidates = androidSdkCandidates;
5
+ exports.androidDefaults = androidDefaults;
6
+ exports.androidToolPaths = androidToolPaths;
7
+ exports.androidToolingPaths = androidToolingPaths;
8
+ // Android SDK and pinned tooling discovery. One implementation serves the
9
+ // driver's defaults (@9l/playwright/android) and `9l doctor --android`:
10
+ // packages/playwright/src/android-env.ts is the source and
11
+ // packages/browser-checks/src/android-env.ts is a byte-identical copy that a
12
+ // test keeps in step. Discovery only reads the environment and checks that
13
+ // directories exist; it never runs a tool, downloads or writes anything.
14
+ const node_fs_1 = require("node:fs");
15
+ const node_os_1 = require("node:os");
16
+ const node_path_1 = require("node:path");
17
+ // Paths follow the platform being described, so a Windows SDK root keeps its
18
+ // separators and drive and a macOS or Linux candidate stays POSIX wherever
19
+ // the code runs; by default that is the host's own platform.
20
+ const paths = (platform) => platform === 'win32' ? node_path_1.win32 : node_path_1.posix;
21
+ /** The Appium server and UiAutomator2 driver releases the adapter is qualified with. */
22
+ exports.androidVersions = { appium: '3.8.0', uiautomator2: '8.7.0' };
23
+ /** The build-tools release whose aapt2 and apksigner the adapter runs. */
24
+ exports.androidBuildTools = '35.0.0';
25
+ /** Where the pinned tooling is looked for when NINELIVES_ANDROID_TOOLS is unset, under the home directory. */
26
+ exports.androidToolsDirectory = '.9l/android-tools';
27
+ /** The install command for the pinned tooling into a prefix directory. */
28
+ const androidToolsInstall = (prefix) => `npm install --prefix ${prefix} --save-exact --ignore-scripts appium@${exports.androidVersions.appium} appium-uiautomator2-driver@${exports.androidVersions.uiautomator2}`;
29
+ exports.androidToolsInstall = androidToolsInstall;
30
+ /** The variables that can choose the SDK root. `9l run` passes none of them
31
+ * to tests unless named with --pass-env, so a worker can discover another
32
+ * root than the shell that ran doctor or a setup script. */
33
+ exports.androidSdkVariables = ['ANDROID_HOME', 'ANDROID_SDK_ROOT', 'HOMEBREW_PREFIX'];
34
+ const directory = (path) => { try {
35
+ return (0, node_fs_1.statSync)(path).isDirectory();
36
+ }
37
+ catch {
38
+ return false;
39
+ } };
40
+ const set = (value) => typeof value === 'string' && value.trim() !== '' ? value : undefined;
41
+ /** Common SDK locations in the order they are tried after ANDROID_HOME and
42
+ * ANDROID_SDK_ROOT: the Homebrew command-line tools under HOMEBREW_PREFIX and
43
+ * the standard Homebrew prefixes, then the Android Studio default for the
44
+ * platform. `brew` itself is not run. */
45
+ function androidSdkCandidates(options = {}) {
46
+ const env = options.env ?? process.env, platform = options.platform ?? process.platform, { join } = paths(platform);
47
+ const home = options.home ?? (set(platform === 'win32' ? env.USERPROFILE : env.HOME) ?? (0, node_os_1.homedir)());
48
+ const prefixes = [set(env.HOMEBREW_PREFIX), '/opt/homebrew', '/usr/local', '/home/linuxbrew/.linuxbrew'].filter((p) => p !== undefined);
49
+ const candidates = platform === 'win32' ? [] :
50
+ [...new Set(prefixes)].map(prefix => ({ path: join(prefix, 'share/android-commandlinetools'), source: 'homebrew' }));
51
+ if (platform === 'darwin')
52
+ candidates.push({ path: join(home, 'Library/Android/sdk'), source: 'android-studio' });
53
+ else if (platform === 'win32') {
54
+ const local = set(env.LOCALAPPDATA);
55
+ if (local)
56
+ candidates.push({ path: join(local, 'Android/Sdk'), source: 'android-studio' });
57
+ }
58
+ else
59
+ candidates.push({ path: join(home, 'Android/Sdk'), source: 'android-studio' });
60
+ return candidates;
61
+ }
62
+ /** The SDK root and pinned-tooling directory the driver uses when its options
63
+ * omit them. ANDROID_HOME wins, then ANDROID_SDK_ROOT, then the first common
64
+ * location that exists. A variable that is set is used as given, even if the
65
+ * directory is missing, so a misconfiguration is reported rather than hidden.
66
+ * The tooling directory is NINELIVES_ANDROID_TOOLS, else ~/.9l/android-tools.
67
+ * Relative values resolve against the current directory. */
68
+ function androidDefaults(options = {}) {
69
+ const env = options.env ?? process.env, exists = options.isDirectory ?? directory;
70
+ const platform = options.platform ?? process.platform, { join, resolve } = paths(platform);
71
+ const home = options.home ?? (set(platform === 'win32' ? env.USERPROFILE : env.HOME) ?? (0, node_os_1.homedir)());
72
+ const result = {};
73
+ const androidHome = set(env.ANDROID_HOME), sdkRoot = set(env.ANDROID_SDK_ROOT);
74
+ if (androidHome) {
75
+ Object.assign(result, { sdkRoot: resolve(androidHome), sdkSource: 'ANDROID_HOME' });
76
+ if (sdkRoot && resolve(sdkRoot) !== result.sdkRoot)
77
+ result.sdkRootIgnored = true;
78
+ }
79
+ else if (sdkRoot) {
80
+ Object.assign(result, { sdkRoot: resolve(sdkRoot), sdkSource: 'ANDROID_SDK_ROOT' });
81
+ }
82
+ else {
83
+ const found = androidSdkCandidates({ ...options, env, home, platform }).find(candidate => exists(candidate.path));
84
+ if (found)
85
+ Object.assign(result, { sdkRoot: found.path, sdkSource: found.source });
86
+ }
87
+ const tools = set(env.NINELIVES_ANDROID_TOOLS);
88
+ if (tools)
89
+ Object.assign(result, { toolsRoot: resolve(tools), toolsSource: 'NINELIVES_ANDROID_TOOLS' });
90
+ else if (home)
91
+ Object.assign(result, { toolsRoot: join(home, exports.androidToolsDirectory), toolsSource: 'default' });
92
+ return result;
93
+ }
94
+ /** The SDK executables the driver runs, under one SDK root. */
95
+ function androidToolPaths(sdkRoot, platform = process.platform) {
96
+ const windows = platform === 'win32', { join } = paths(platform);
97
+ const buildTools = join(sdkRoot, 'build-tools', exports.androidBuildTools);
98
+ return {
99
+ adb: join(sdkRoot, 'platform-tools', windows ? 'adb.exe' : 'adb'),
100
+ emulator: join(sdkRoot, 'emulator', windows ? 'emulator.exe' : 'emulator'),
101
+ buildTools,
102
+ aapt2: join(buildTools, windows ? 'aapt2.exe' : 'aapt2'),
103
+ apksigner: join(buildTools, windows ? 'apksigner.bat' : 'apksigner'),
104
+ };
105
+ }
106
+ /** The pinned packages' manifests and the Appium entry point under a tooling directory. */
107
+ function androidToolingPaths(toolsRoot, platform = process.platform) {
108
+ const { join } = paths(platform);
109
+ return {
110
+ appium: join(toolsRoot, 'node_modules/appium/package.json'),
111
+ appiumEntry: join(toolsRoot, 'node_modules/appium/index.js'),
112
+ uiautomator2: join(toolsRoot, 'node_modules/appium-uiautomator2-driver/package.json'),
113
+ };
114
+ }
@@ -1,7 +1,5 @@
1
- export declare const androidVersions: {
2
- readonly appium: "3.8.0";
3
- readonly uiautomator2: "8.7.0";
4
- };
1
+ import { androidVersions } from './android-env';
2
+ export { androidVersions };
5
3
  export declare const androidRuntimeType = "application/vnd.9l.android-runtime+json";
6
4
  export type AndroidRuntime = {
7
5
  appPackage: string;
@@ -12,6 +10,20 @@ export type AndroidRuntime = {
12
10
  appium: string;
13
11
  uiautomator2: string;
14
12
  worker: string;
13
+ /** The physical display the session targets (its id, or unknown), its
14
+ * size in pixels and density, and the fold posture when the device
15
+ * reports one. Layout-dependent specs can be read against these. */
16
+ display: string;
17
+ displayWidth: string;
18
+ displayHeight: string;
19
+ density: string;
20
+ posture: 'opened' | 'half-opened' | 'closed' | 'flat' | 'unknown';
21
+ /** The installed build's version and signing certificate digest, read
22
+ * from the device; `unknown` when not read. apkSHA256 is the verified
23
+ * digest of the installed base APK. */
24
+ versionCode: string;
25
+ versionName: string;
26
+ signer: string;
15
27
  } & ({
16
28
  emulator: string;
17
29
  device?: never;
@@ -3,13 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.androidRuntimeType = exports.androidVersions = void 0;
4
4
  exports.validAndroidRuntime = validAndroidRuntime;
5
5
  // Closed, content-free metadata allowed across the native worker bridge.
6
- exports.androidVersions = { appium: '3.8.0', uiautomator2: '8.7.0' };
6
+ const android_env_1 = require("./android-env");
7
+ Object.defineProperty(exports, "androidVersions", { enumerable: true, get: function () { return android_env_1.androidVersions; } });
7
8
  exports.androidRuntimeType = 'application/vnd.9l.android-runtime+json';
8
9
  function validAndroidRuntime(value) {
9
10
  if (!value || typeof value !== 'object' || Array.isArray(value))
10
11
  return false;
11
12
  const r = value;
12
- const keys = ['appPackage', 'apkSHA256', 'api', 'release', 'abi', 'appium', 'uiautomator2', 'worker',
13
+ const keys = ['appPackage', 'apkSHA256', 'api', 'release', 'abi', 'appium', 'uiautomator2', 'worker', 'display', 'displayWidth', 'displayHeight', 'density', 'posture', 'versionCode', 'versionName', 'signer',
13
14
  ...(r.device === 'physical' ? ['device', 'deviceHash'] : ['emulator'])];
14
15
  if (Object.keys(r).length !== keys.length || keys.some(key => typeof r[key] !== 'string'))
15
16
  return false;
@@ -18,5 +19,9 @@ function validAndroidRuntime(value) {
18
19
  return text.appPackage.length <= 200 && /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z0-9_]+)+$/.test(text.appPackage) &&
19
20
  /^[a-f0-9]{64}$/.test(text.apkSHA256) && /^[a-f0-9]{64}$/.test(text.worker) &&
20
21
  /^[0-9]{1,3}$/.test(text.api) && version.test(text.release) && (text.device === 'physical' ? /^[a-f0-9]{64}$/.test(text.deviceHash) : version.test(text.emulator)) &&
21
- text.appium === exports.androidVersions.appium && text.uiautomator2 === exports.androidVersions.uiautomator2 && ['arm64-v8a', 'x86_64'].includes(text.abi);
22
+ text.appium === android_env_1.androidVersions.appium && text.uiautomator2 === android_env_1.androidVersions.uiautomator2 && ['arm64-v8a', 'x86_64'].includes(text.abi) &&
23
+ (text.display === 'unknown' || /^[0-9]{1,24}$/.test(text.display)) && /^[0-9]{1,5}$/.test(text.displayWidth) && /^[0-9]{1,5}$/.test(text.displayHeight) && /^[0-9]{1,4}$/.test(text.density) &&
24
+ ['opened', 'half-opened', 'closed', 'flat', 'unknown'].includes(text.posture) &&
25
+ (text.versionCode === 'unknown' || /^[0-9]{1,10}$/.test(text.versionCode)) && (text.versionName === 'unknown' || /^[A-Za-z0-9._+-]{1,64}$/.test(text.versionName)) &&
26
+ (text.signer === 'unknown' || /^[a-f0-9]{64}$/.test(text.signer));
22
27
  }
package/dist/android.d.ts CHANGED
@@ -1,5 +1,7 @@
1
1
  import { type TargetDriver } from './targets';
2
+ export { TargetSetupError, type TargetSetupRecord } from './targets';
2
3
  export { androidVersions, androidRuntimeType, validAndroidRuntime, type AndroidRuntime } from './android-runtime';
4
+ export { androidDefaults, androidSdkCandidates, androidSdkVariables, androidToolPaths, androidToolingPaths, androidToolsInstall, androidBuildTools, type AndroidDefaults, type AndroidSource } from './android-env';
3
5
  /** Explicit aliases for apps without resource IDs. All matches remain strict
4
6
  * and scoped to the configured package; arbitrary XPath is not accepted. */
5
7
  export type AndroidControl = ({
@@ -20,12 +22,60 @@ export type AndroidControl = ({
20
22
  };
21
23
  export type AndroidTargetOptions = {
22
24
  appId: string;
23
- sdkRoot: string;
24
- toolsRoot: string;
25
- apkSHA256: string;
25
+ /** The Android SDK root. Defaults to androidDefaults(): ANDROID_HOME,
26
+ * ANDROID_SDK_ROOT, then common install locations. */
27
+ sdkRoot?: string;
28
+ /** The directory whose node_modules holds the pinned Appium and
29
+ * UiAutomator2 packages. Defaults to NINELIVES_ANDROID_TOOLS, else
30
+ * ~/.9l/android-tools. Nothing is downloaded. */
31
+ toolsRoot?: string;
32
+ /** The expected SHA-256 of the installed base APK. May be omitted only
33
+ * when `expected.apk` names the artifact to compare the installation with. */
34
+ apkSHA256?: string;
26
35
  appPackage: string;
27
36
  activity: string;
28
37
  controls?: Record<string, AndroidControl>;
38
+ /** What the installed build must be. A digest that differs from the
39
+ * declared one, or from `expected.apk`, a different versionCode or
40
+ * versionName, or another signing certificate stops the test as
41
+ * `setup mismatch` before any application operation. The signer is read
42
+ * by pulling the installed base APK through the local apksigner when
43
+ * declared; versions come from the device's package manager. */
44
+ expected?: {
45
+ apk?: string;
46
+ versionCode?: string;
47
+ versionName?: string;
48
+ signerSHA256?: string;
49
+ };
50
+ /** Attached device only: the app state expected before each test. The
51
+ * driver reads the app's window count, focus and keyboard visibility after
52
+ * launching the activity; a difference is classified `dirty` (state left by
53
+ * a previous test) instead of running the test against it. */
54
+ baseline?: {
55
+ windows?: number;
56
+ };
57
+ /** Attached device only: on a dirty baseline, press Back up to this many
58
+ * times until the baseline returns. Recorded in the receipt; never clears
59
+ * data, force-stops or changes settings. */
60
+ recovery?: {
61
+ back: number;
62
+ };
63
+ /** Opt-in failure diagnostics: the app's window count and focus are read
64
+ * before each gesture and again when an operation fails, and a metadata
65
+ * record (timing, requested point, viewport, windows) is attached to the
66
+ * failed test. With it, a hidden-assertion failure whose window the window
67
+ * manager no longer lists is classified as observer staleness. No
68
+ * screenshot, hierarchy, text or log is captured. */
69
+ diagnostics?: {
70
+ gestures: boolean;
71
+ };
72
+ /** What the spec needs from the device: a fold posture and/or a minimum
73
+ * active-display width in dp. Another posture or a narrower display is
74
+ * reported as a setup mismatch before any application operation. */
75
+ requires?: {
76
+ posture?: 'opened' | 'half-opened' | 'closed' | 'flat';
77
+ minWidthDp?: number;
78
+ };
29
79
  } & ({
30
80
  avd: string;
31
81
  apk: string;
@@ -39,7 +89,28 @@ export type AndroidTargetOptions = {
39
89
  apk?: never;
40
90
  headless?: never;
41
91
  });
92
+ /** The host-local lease that gives one owner exclusive use of a device.
93
+ * The driver and installInPlace both take it, so an installation cannot
94
+ * replace the app under a running test or interleave with another installer. */
95
+ export declare function androidLeasePath(serial: string): string;
42
96
  /** Optional local Android adapter. Appium/UiAutomator2 owns native automation;
43
97
  * Go still owns scheduling/deadlines/receipts and this worker owns all handles.
44
98
  * No emulator, server, action or assertion is retried. */
45
99
  export declare function androidTargetDriver(options: AndroidTargetOptions): TargetDriver;
100
+ /** Install or update an app on an explicitly selected device without
101
+ * uninstalling or clearing its data. The APK's signing certificate must
102
+ * match the installed app's, read through the local apksigner; a different
103
+ * signer refuses before any device change. Returns the installed identity
104
+ * for the project's reviewed build metadata. Never runs inside a test. */
105
+ export declare function installInPlace(options: {
106
+ sdkRoot?: string;
107
+ deviceSerial: string;
108
+ apk: string;
109
+ timeoutMs?: number;
110
+ }): Promise<{
111
+ versionCode: string;
112
+ versionName: string;
113
+ appPackage: string;
114
+ apkSHA256: string;
115
+ signer: string;
116
+ }>;