@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/README.md +72 -2
- package/dist/android-device.d.ts +64 -0
- package/dist/android-device.js +134 -0
- package/dist/android-env.d.ts +65 -0
- package/dist/android-env.js +114 -0
- package/dist/android-runtime.d.ts +16 -4
- package/dist/android-runtime.js +8 -3
- package/dist/android.d.ts +98 -18
- package/dist/android.js +690 -49
- package/dist/index.d.ts +2 -2
- package/dist/index.js +4 -1
- package/dist/protocol.d.ts +2 -2
- package/dist/protocol.js +1 -1
- package/dist/reporter.js +71 -1
- package/dist/target-setup.d.ts +50 -0
- package/dist/target-setup.js +73 -0
- package/dist/targets.d.ts +151 -4
- package/dist/targets.js +382 -54
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -56,8 +56,78 @@ Natural-language goals use finite observed controls and typed actions, with
|
|
|
56
56
|
budgets and a conservative stop policy. See the
|
|
57
57
|
[goal contract](https://github.com/Quality-Max/9lives-runner/blob/main/docs/goals.md)
|
|
58
58
|
and [SDK bridge](https://github.com/Quality-Max/9lives-runner/blob/main/docs/sdk-bridge.md).
|
|
59
|
-
Live provider accuracy, independent behavioral verification, verified replay
|
|
60
|
-
and
|
|
59
|
+
Live provider accuracy, independent behavioral verification, verified replay,
|
|
60
|
+
iOS and Android devices beyond those listed below are not qualified features.
|
|
61
|
+
|
|
62
|
+
## Android (experimental, 0.6.0-beta releases)
|
|
63
|
+
|
|
64
|
+
The Android target drives an owned emulator or an attached phone through
|
|
65
|
+
Appium 3.8.0 and UiAutomator2 8.7.0, with the same `app` fixture a web
|
|
66
|
+
target uses. It is qualified on API 35 emulators and one Android 17 phone;
|
|
67
|
+
see [Android setup and qualification limits](https://github.com/Quality-Max/9lives-runner/blob/main/docs/android-driver.md).
|
|
68
|
+
|
|
69
|
+
1. Install the matching beta CLI and `@9l/playwright` together (see
|
|
70
|
+
[beta releases](https://github.com/Quality-Max/9lives-runner/blob/main/docs/releases.md#beta-releases)),
|
|
71
|
+
and the pinned automation tooling once, outside your project:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
npm install --prefix ~/.9l/android-tools --save-exact --ignore-scripts \
|
|
75
|
+
appium@3.8.0 appium-uiautomator2-driver@8.7.0
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
For another location, set `NINELIVES_ANDROID_TOOLS`.
|
|
79
|
+
|
|
80
|
+
2. Check the host. Doctor reports Java, the SDK, build-tools, AVDs, devices
|
|
81
|
+
and the pinned tooling, each with a fix:
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
9l doctor --android
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
3. Construct the driver in the shared target fixture and name the Playwright
|
|
88
|
+
project `android:<alias>`:
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import {createTargetTest} from '@9l/playwright';
|
|
92
|
+
import {androidTargetDriver} from '@9l/playwright/android';
|
|
93
|
+
|
|
94
|
+
export const test = createTargetTest({
|
|
95
|
+
native: target => androidTargetDriver({
|
|
96
|
+
appId: target.appId, avd: 'Pixel_API_35',
|
|
97
|
+
apk: 'build/app.apk', apkSHA256: '<digest>',
|
|
98
|
+
appPackage: 'com.example.app', activity: '.MainActivity',
|
|
99
|
+
}),
|
|
100
|
+
});
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
```ts
|
|
104
|
+
// playwright.config.ts
|
|
105
|
+
import {defineConfig} from '@playwright/test';
|
|
106
|
+
|
|
107
|
+
export default defineConfig({
|
|
108
|
+
// A cold emulator boot fits in open()'s 180-second bound, which needs
|
|
109
|
+
// a test timeout above Playwright's 30-second default.
|
|
110
|
+
timeout: 240_000,
|
|
111
|
+
// 9l owns attempts: a Playwright retry is refused.
|
|
112
|
+
retries: 0,
|
|
113
|
+
projects: [{name: 'android:app'}],
|
|
114
|
+
});
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
4. Run through the engine, forwarding the variables the driver relies on.
|
|
118
|
+
`9l run` passes only a fixed environment to tests:
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
9l run tests/login.spec.ts --sdk --target android:app \
|
|
122
|
+
--pass-env ANDROID_HOME,JAVA_HOME,NINELIVES_ANDROID_TOOLS
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
Forward `ANDROID_SDK_ROOT`, `ANDROID_AVD_HOME` or `HOMEBREW_PREFIX` too if
|
|
126
|
+
your SDK or AVDs are found through them. `9l doctor --android` says which.
|
|
127
|
+
|
|
128
|
+
The driver holds the device's only UI-automation connection while a session
|
|
129
|
+
is open, so a spec-side `adb shell uiautomator dump` returns nothing. Use the
|
|
130
|
+
fixture's operations instead, and `app.deviceSerial()` for other adb commands.
|
|
61
131
|
|
|
62
132
|
## License
|
|
63
133
|
|
|
@@ -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
|
-
|
|
2
|
-
|
|
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;
|
package/dist/android-runtime.js
CHANGED
|
@@ -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
|
-
|
|
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 ===
|
|
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
|
}
|