@keepsnappy/appium-driver 0.0.0-stage → 0.1.0-alpha.11

package/README.md

@@ -1,3 +1,38 @@
-# Temporary Holding Version
+# @keepsnappy/appium-driver
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+KeepSnappy's built-in Appium driver for `perflab farm run --driver appium --journey-module <file>` (BrowserStack App Automate, iOS and Android; `--platform ios|android`, default ios). A thin step vocabulary over W3C WebDriver: you write the journey, the driver owns the session, run tokens, step markers, the readiness wait (`expectNext`) after a touch and the result files. Design: `docs/plans/54b-appium-driver.md`.
+
+A journey module default-exports `defineJourney({ app, home, options?, setup?, journeys })`; see the plan for the full shape. A journey needs no import from this package: selectors are plain objects (`{ id }`, `{ text }`, `{ ...sel, childOf }`, or a bare string) and everything else is on the `t` it is given (`t.acceptAlert`, `t.openLink`, ...). `defineJourney` is only an identity helper for editor types. The CLI runs its own bundled copy, so do not `instanceof` driver errors (`WdError`) from your own copy; test `e.wdError`.
+
+Run directly (what `farm run` does): `node dist/src/cli.js --journey-module j.mjs --app bs://… --tokens-js tokens.js --journeys a,b --repeat 3 --out DIR [--local-identifier ID]`, with `BROWSERSTACK_USERNAME` / `BROWSERSTACK_ACCESS_KEY`. Exit 0, or 1 when the session or an iteration failed (the result files are written either way).
+
+## Step checks and Android
+
+`t.waitAll([{ shown: sel }, { gone: sel }, { keyboard: 'up' }, ...])` waits until all conditions hold in one poll (the poll asks them one lookup after another). On Android the ids are asked in one UiAutomator2 lookup (a walk of the whole tree costs the same for one id and for ten); elsewhere each condition is waited for in turn. The keyboard condition is answered by the platform (Android `mobile: isKeyboardShown`, iOS the Return key), so a journey needs no platform branch. `t.swipeFromUntilVisible(from, direction, target, times)` swipes until a target shows.
+
+Android specifics (UiAutomator2, measured on a Galaxy S23): a lookup that finds nothing walks the whole tree (about 1.2 s), one that finds a shown element takes 0.1 to 0.2 s, so `findShown` asks for one element first. `ignoreUnimportantViews` is on (about 30 % faster lookups).
+
+Inverted bounds: when the keyboard opens, TapIn translates the chat up while Android still cuts the chat nodes by the container's untranslated rect. The chat's scroll container and its nodes come back with top below bottom and `displayed=false`, and are left out of lookups. While the keyboard is up (and at most every 3 s) `waitAll` reads the page source with `allowInvisibleElements` and counts such a node as shown when it sits in an inverted scroll container, its real bottom edge is on screen and below the edge the clipped-away nodes pile up on (at least two clipped messages are needed to find the edge). See `src/snapshot.ts`.
+
+How to write journeys that run fast on Android, with measured costs: `docs/writing-fast-journeys.md`.
+
+## GC before the action (`--action-gc on|off`, default off)
+
+With `--action-gc on` the driver asks the app for a full garbage collection before every declared step, after the step's readiness wait and before its start marker, and once more before the run's flush. Design: `docs/plans/gc-before-action.md`; device checks: `docs/plans/gc-before-action-measurement.md`.
+
+- Each command has a number `n`, unique in the session. Android sends it as a broadcast (`mobile: broadcast`, action `<bundleId>.perflab.COMMAND`, extras `cmd=gc`, `n`) and reads the answer `gc:<n> ...` from the broadcast's result. iOS opens `<scheme>devtools/perf-lab?cmd=gc&n=<n>` and waits up to 10 s for the element `perflab.ack` whose label starts with `gc:<n> `.
+- The step's start marker carries `gc_n`, so the backend (derivation 18) pairs the step with its GC record without mapping clocks.
+- No answer turns the command off for the rest of the session (`actionGc: unsupported` in `driver-log.json`); the test still passes. Safari link mode sends none (`safari`).
+- The GC command ends the app's open windows: runs with and without it are a different instrument (`actionGc` aspect), never compared as an app change.
+
+## GC at the run end (`--end-gc on|off`, default on)
+
+One GC command at the end of every run, after the journey's last step and its readiness wait, before the markers and the flush, also when `--action-gc` is off. Its record gives the end reading after a GC (derivation 19: `mem.end_after_gc_mb`, `mem.retained_growth_mb`, `mem.js_heap_end_mb`; setup fact `sdk.end_gc`). End the journey on its home screen (`docs/writing-fast-journeys.md`), so the reading holds what the journey kept, not an open heavy screen; `sdk.journey_ends_home` = 0 flags a run that did not.
+
+- Same command and fallbacks as above; an app that does not answer turns it off for the rest of the session.
+- The command ends the last open window (end reason `gc-command`) instead of the flush: that one window per run is shorter than on a driver without it. Driver 0.2.0 carries both commands, so runs before and after it are a different instrument already (`driverVersion` aspect).
+- On by default (REQ-MEAS-35, REQ-FARM-28; driver 0.3.0); `--end-gc off` or `endGc: false` turns it off. It changes the memory readings only (it runs after the last window): a main without it still judges a PR's render, commit and component measures; only the memory verdict needs end-GC runs on both sides (`endGc` setup aspect, memory measures only). Older SDKs do not answer and send no line.
+
+## The default run configuration (`links.ts`)
+
+`RUN_DEFAULTS` and the link builders are the one source of the activation, flush and GC links (REQ-FARM-28): `profile=1`, `diag=1` (the React export), ttl 3600, no `cpuprof`, and the end GC on (`END_GC_DEFAULT`). A journey module's `sdkArgs` (`k=v&...`) are set over the defaults key by key, so `sdkArgs: 'profile=1'` still gets `diag=1`; `diag=0` turns the export off explicitly. `perflab activation-link | flush-link | gc-link` print the same links for runners that are not this driver, and `perflab farm open` writes the settings into `tokens.js` (`output.perflabLinkArgs`) for Maestro flows. Maestro runs send no GC for now. A guard test in `apps/agent` fails on a hand-written activation link anywhere else in the repo.

package/dist/src/browserstack.d.ts

@@ -0,0 +1,24 @@
+import { type Platform } from './platform.js';
+import type { FetchLike } from './webdriver.js';
+export declare const HUB = "https://hub-cloud.browserstack.com/wd/hub";
+export declare const BS_API = "https://api-cloud.browserstack.com/app-automate";
+export declare const basicAuth: (user: string, key: string) => string;
+/** `bs://` passes through; a file is uploaded, or the recent upload under `customId` is reused. */
+export declare function resolveApp(app: string, customId: string, auth: string, fetchImpl: FetchLike, platform?: Platform): Promise<string>;
+export interface CapsInput {
+    appUrl: string;
+    device: string;
+    buildName: string;
+    sessionName: string;
+    appiumVersion: string;
+    localIdentifier?: string | undefined;
+    /** Default iOS. */
+    platform?: Platform;
+}
+/** `local` is on only when a tunnel exists: without one BrowserStack waits for a Local binary that never comes. */
+export declare function sessionCaps(i: CapsInput): Record<string, unknown>;
+export declare function sessionDetail(sessionId: string, auth: string, fetchImpl: FetchLike): Promise<{
+    build_hashed_id?: string;
+    public_url?: string;
+    browser_url?: string;
+}>;

package/dist/src/browserstack.js

@@ -0,0 +1,54 @@
+import { openAsBlob } from 'node:fs';
+import { basename } from 'node:path';
+import { IOS } from './platform.js';
+// BrowserStack App Automate only: real devices, so no simulator-only capability belongs in the caps.
+export const HUB = 'https://hub-cloud.browserstack.com/wd/hub';
+export const BS_API = 'https://api-cloud.browserstack.com/app-automate';
+export const basicAuth = (user, key) => `Basic ${Buffer.from(`${user}:${key}`).toString('base64')}`;
+/** `bs://` passes through; a file is uploaded, or the recent upload under `customId` is reused. */
+export async function resolveApp(app, customId, auth, fetchImpl, platform = IOS) {
+    if (app.startsWith('bs://'))
+        return app;
+    const headers = { Authorization: auth };
+    if (customId) {
+        const res = await fetchImpl(`${BS_API}/recent_apps/${encodeURIComponent(customId)}`, { headers });
+        const list = res.ok ? await res.json().catch(() => []) : [];
+        const url = Array.isArray(list) ? list[0]?.app_url : undefined;
+        if (url)
+            return url;
+    }
+    const form = new FormData();
+    form.append('file', await openAsBlob(app), basename(app));
+    if (customId)
+        form.append('custom_id', customId);
+    for (const [k, v] of Object.entries(platform.uploadFields))
+        form.append(k, v);
+    const res = await fetchImpl(`${BS_API}/upload`, { method: 'POST', headers, body: form });
+    const body = (await res.json().catch(() => ({})));
+    if (!body.app_url)
+        throw new Error(`app upload failed: HTTP ${res.status} ${JSON.stringify(body)}`);
+    return body.app_url;
+}
+/** `local` is on only when a tunnel exists: without one BrowserStack waits for a Local binary that never comes. */
+export function sessionCaps(i) {
+    const tunnel = i.localIdentifier ? { local: true, localIdentifier: i.localIdentifier } : {};
+    return {
+        ...(i.platform ?? IOS).caps(i.device),
+        'appium:app': i.appUrl,
+        'bstack:options': {
+            projectName: 'perflab',
+            buildName: i.buildName,
+            sessionName: i.sessionName,
+            ...tunnel,
+            idleTimeout: 300,
+            appiumVersion: i.appiumVersion,
+        },
+    };
+}
+export async function sessionDetail(sessionId, auth, fetchImpl) {
+    const res = await fetchImpl(`${BS_API}/sessions/${sessionId}.json`, { headers: { Authorization: auth } }).catch(() => null);
+    if (!res?.ok)
+        return {};
+    return (await res.json()).automation_session ?? {};
+}
+//# sourceMappingURL=browserstack.js.map

package/dist/src/browserstack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserstack.js","sourceRoot":"","sources":["../../src/browserstack.ts"],"names":[],"mappings":"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"}

package/dist/src/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { main } from './load.js';
+// No "is this the main module" guard: it compared two paths and silently exited 0 through a symlink (macOS /tmp).
+main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+    console.error(`::error::${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,kHAAkH;AAClH,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC9B,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAC5B,CAAC,CAAU,EAAE,EAAE;IACb,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACxE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CACF,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+export { Driver, WdError, realSleep, type CommandLogEntry, type FetchLike, type Rect } from './webdriver.js';
+export { END_GC_DEFAULT, RUN_DEFAULTS, acceptAlert, activationLink, flushLink, gcLink, linkArgs, openLink, parseSdkArgs, type LinkState } from './links.js';
+export { defineJourney, type JourneyContext, type JourneyFn, type JourneyModule } from './journey.js';
+export { ANDROID, IOS, PLATFORMS, platformOf, type Platform, type PlatformName } from './platform.js';
+export { androidLocators, childOf, describeSelector, id, idText, locator, text, toSelector, type Selector, type SelectorLike } from './selectors.js';
+export { FLUSH_WAIT_MS, HOST_CLOCK_TRIPS, Session, sendMarkers, type ActionGc, type ClockTrip, type Condition, type Marker } from './session.js';
+export { loadElements, parseTokensJs, plan, type PlannedRun } from './tokens.js';
+export { runDriver, DRIVER_OPTIONS, type IterationRecord, type RunDeps } from './run.js';
+export { loadJourneyModule, main } from './load.js';
+export { driverVersion, journeyVersion } from './version.js';

package/dist/src/index.js

@@ -0,0 +1,11 @@
+export { Driver, WdError, realSleep } from './webdriver.js';
+export { END_GC_DEFAULT, RUN_DEFAULTS, acceptAlert, activationLink, flushLink, gcLink, linkArgs, openLink, parseSdkArgs } from './links.js';
+export { defineJourney } from './journey.js';
+export { ANDROID, IOS, PLATFORMS, platformOf } from './platform.js';
+export { androidLocators, childOf, describeSelector, id, idText, locator, text, toSelector } from './selectors.js';
+export { FLUSH_WAIT_MS, HOST_CLOCK_TRIPS, Session, sendMarkers } from './session.js';
+export { loadElements, parseTokensJs, plan } from './tokens.js';
+export { runDriver, DRIVER_OPTIONS } from './run.js';
+export { loadJourneyModule, main } from './load.js';
+export { driverVersion, journeyVersion } from './version.js';
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAmD,MAAM,gBAAgB,CAAC;AAC7G,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAkB,MAAM,YAAY,CAAC;AAC5J,OAAO,EAAE,aAAa,EAA2D,MAAM,cAAc,CAAC;AACtG,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,SAAS,EAAE,UAAU,EAAoC,MAAM,eAAe,CAAC;AACtG,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,gBAAgB,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAoC,MAAM,gBAAgB,CAAC;AACrJ,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,OAAO,EAAE,WAAW,EAA8D,MAAM,cAAc,CAAC;AACjJ,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,IAAI,EAAmB,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAsC,MAAM,UAAU,CAAC;AACzF,OAAO,EAAE,iBAAiB,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACpD,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/src/journey.d.ts

@@ -0,0 +1,43 @@
+import type { Session } from './session.js';
+import type { SelectorLike } from './selectors.js';
+import type { FetchLike } from './webdriver.js';
+export interface JourneyContext {
+    fetch: FetchLike;
+    /** Run tokens from `farm open`: journey name to one token per iteration. */
+    tokens: Record<string, string[]>;
+    /** The journey names of this session, in run order. */
+    journeys: readonly string[];
+    repeat: number;
+    /** Parsed command line: the driver's own flags plus the module's `options`. */
+    args: Record<string, string | boolean | undefined>;
+    /** The journey and iteration being run (unset in `setup`). */
+    journey?: string;
+    iteration?: number;
+}
+export type JourneyFn = (t: Session, ctx: JourneyContext) => Promise<void>;
+/**
+ * What a customer's journey module default-exports. Everything app-specific is a value in here; the driver owns the
+ * session, the run tokens, the begin/end of each run, the `run:complete` marker and the result files.
+ */
+export interface JourneyModule {
+    app: {
+        bundleId: string;
+        scheme: string;
+    };
+    /** Visible once the app has launched; begin-run waits for it before opening the activation link. */
+    home: SelectorLike;
+    sessionName?: string;
+    /** Extra command-line flags the module reads from `ctx.args` (node:util parseArgs option configs). */
+    options?: Record<string, {
+        type: 'string' | 'boolean';
+        default?: string | boolean;
+        multiple?: false;
+    }>;
+    /** Query args of the SDK activation link (`k=v&...`), set over the run defaults (`RUN_DEFAULTS`) key by key. */
+    sdkArgs?: string;
+    /** Once per session, after it started and before the first iteration (e.g. pointing the app at a mock server). */
+    setup?: JourneyFn;
+    /** One function per journey name that `--journeys` may list. */
+    journeys: Record<string, JourneyFn>;
+}
+export declare const defineJourney: (m: JourneyModule) => JourneyModule;

package/dist/src/journey.js

@@ -0,0 +1,2 @@
+export const defineJourney = (m) => m;
+//# sourceMappingURL=journey.js.map

package/dist/src/journey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"journey.js","sourceRoot":"","sources":["../../src/journey.ts"],"names":[],"mappings":"AAuCA,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAgB,EAAiB,EAAE,CAAC,CAAC,CAAC"}

package/dist/src/links.d.ts

@@ -0,0 +1,35 @@
+import type { Driver } from './webdriver.js';
+export declare const ALERT_POLL_MS = 250;
+/**
+ * The default run configuration (REQ-FARM-28), the one source for the farm, this driver, the agent CLI and the Maestro flows:
+ * React profiling and the React export on, the Hermes CPU profile off (no `cpuprof`, REQ-MEAS-31), and one GC at the run end
+ * (REQ-MEAS-35). A runner turns a default off only explicitly (`profile=0`, `diag=0`, `--end-gc off`).
+ */
+export declare const RUN_DEFAULTS: {
+    readonly ttl: 3600;
+    readonly profile: 1;
+    readonly diag: 1;
+};
+export declare const END_GC_DEFAULT = true;
+/** `k=v&k2=v2` into pairs; an empty string gives none. */
+export declare function parseSdkArgs(args: string): Array<[string, string]>;
+/**
+ * The activation link's settings: the defaults, then `args` (`k=v&...`, e.g. a journey module's `sdkArgs`) over them key by key, so
+ * a module that names only `profile=1` still gets `diag=1`. `activate` and `runToken` are not settings and are dropped.
+ */
+export declare function linkArgs(args?: string): string;
+export declare const activationLink: (scheme: string, token: string, args?: string) => string;
+export declare const flushLink: (scheme: string) => string;
+/** Command n (a GC); the SDK takes it as a link on both platforms, and Android drivers send the same command as a broadcast. */
+export declare const gcLink: (scheme: string, n: number) => string;
+/** Taps the button of a system alert if one shows within `waitMs` ("Open in ...?" and any permission prompt). Returns the label tapped, or null. */
+export declare function acceptAlert(driver: Driver, labels: readonly string[], waitMs: number): Promise<string | null>;
+export interface LinkState {
+    linkMode?: 'deepLink' | 'safari';
+    linkError?: string;
+}
+/**
+ * Opens a deep link. `mobile: deepLink` (XCUITest driver, iOS 16.4+) first; Safari's address bar if the driver refuses
+ * it, since `driver.get` opens Siri on a real iPhone.
+ */
+export declare function openLink(driver: Driver, url: string, state: LinkState): Promise<string | null>;

package/dist/src/links.js

@@ -0,0 +1,87 @@
+export const ALERT_POLL_MS = 250;
+/**
+ * The default run configuration (REQ-FARM-28), the one source for the farm, this driver, the agent CLI and the Maestro flows:
+ * React profiling and the React export on, the Hermes CPU profile off (no `cpuprof`, REQ-MEAS-31), and one GC at the run end
+ * (REQ-MEAS-35). A runner turns a default off only explicitly (`profile=0`, `diag=0`, `--end-gc off`).
+ */
+export const RUN_DEFAULTS = { ttl: 3600, profile: 1, diag: 1 };
+export const END_GC_DEFAULT = true;
+// The SDK's link route under the app's own URL scheme (e.g. `myapp://`).
+const route = (scheme) => `${scheme}devtools/perf-lab`;
+/** `k=v&k2=v2` into pairs; an empty string gives none. */
+export function parseSdkArgs(args) {
+    return args
+        .split('&')
+        .filter(Boolean)
+        .map((kv) => {
+        const i = kv.indexOf('=');
+        return i < 0 ? [kv, '1'] : [kv.slice(0, i), kv.slice(i + 1)];
+    });
+}
+/**
+ * The activation link's settings: the defaults, then `args` (`k=v&...`, e.g. a journey module's `sdkArgs`) over them key by key, so
+ * a module that names only `profile=1` still gets `diag=1`. `activate` and `runToken` are not settings and are dropped.
+ */
+export function linkArgs(args = '') {
+    const fields = new Map(Object.entries(RUN_DEFAULTS).map(([k, v]) => [k, String(v)]));
+    for (const [k, v] of parseSdkArgs(args))
+        if (k !== 'activate' && k !== 'runToken')
+            fields.set(k, v);
+    return [...fields].map(([k, v]) => `${k}=${v}`).join('&');
+}
+export const activationLink = (scheme, token, args = '') => `${route(scheme)}?activate=1&${linkArgs(args)}&runToken=${token}`;
+export const flushLink = (scheme) => `${route(scheme)}?flush=1&activate=0`;
+/** Command n (a GC); the SDK takes it as a link on both platforms, and Android drivers send the same command as a broadcast. */
+export const gcLink = (scheme, n) => `${route(scheme)}?cmd=gc&n=${n}`;
+/** Taps the button of a system alert if one shows within `waitMs` ("Open in ...?" and any permission prompt). Returns the label tapped, or null. */
+export async function acceptAlert(driver, labels, waitMs) {
+    const deadline = driver.now() + waitMs;
+    for (;;) {
+        let buttons = null;
+        try {
+            buttons = await driver.execute('mobile: alert', { action: 'getButtons' });
+        }
+        catch {
+            buttons = null;
+        }
+        const hit = Array.isArray(buttons) ? labels.find((l) => buttons.includes(l)) : undefined;
+        if (hit) {
+            await driver.execute('mobile: alert', { action: 'accept', buttonLabel: hit });
+            return hit;
+        }
+        if (driver.now() > deadline)
+            return null;
+        await driver.sleep(ALERT_POLL_MS);
+    }
+}
+/**
+ * Opens a deep link. `mobile: deepLink` (XCUITest driver, iOS 16.4+) first; Safari's address bar if the driver refuses
+ * it, since `driver.get` opens Siri on a real iPhone.
+ */
+export async function openLink(driver, url, state) {
+    if (state.linkMode !== 'safari') {
+        try {
+            await driver.execute('mobile: deepLink', { url, bundleId: driver.bundleId });
+            state.linkMode = 'deepLink';
+        }
+        catch (e) {
+            if (state.linkMode === 'deepLink')
+                throw e;
+            state.linkMode = 'safari';
+            state.linkError = String(e.message);
+        }
+    }
+    if (state.linkMode === 'safari') {
+        await driver.execute('mobile: launchApp', { bundleId: 'com.apple.mobilesafari' });
+        const bar = (await driver.find('accessibility id', 'TabBarItemTitle')) ?? (await driver.find('accessibility id', 'URL'));
+        if (bar)
+            await driver.click(bar);
+        const field = await driver.find('-ios predicate string', 'type == "XCUIElementTypeTextField" AND name == "URL"');
+        if (!field)
+            throw new Error('Safari address bar not found');
+        await driver.cmd('POST', `/element/${field}/value`, { text: `${url}\n` });
+    }
+    // In deepLink mode autoAcceptAlerts already answers a prompt, so this only looks once.
+    return acceptAlert(driver, ['Open'], state.linkMode === 'safari' ? 8000 : 0);
+}
+//# sourceMappingURL=links.js.map

package/dist/src/links.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../src/links.ts"],"names":[],"mappings":"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"}

package/dist/src/load.d.ts

@@ -0,0 +1,4 @@
+import type { JourneyModule } from './journey.js';
+/** Loads the customer's journey module: its default export, or the module itself when it has no default. */
+export declare function loadJourneyModule(path: string, cwd?: string): Promise<JourneyModule>;
+export declare function main(argv: readonly string[]): Promise<number>;

package/dist/src/load.js

@@ -0,0 +1,23 @@
+import { isAbsolute, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { journeyModulePath, runDriver } from './run.js';
+/** Loads the customer's journey module: its default export, or the module itself when it has no default. */
+export async function loadJourneyModule(path, cwd = process.cwd()) {
+    const file = isAbsolute(path) ? path : resolve(cwd, path);
+    const mod = (await import(pathToFileURL(file).href));
+    const m = mod.default ?? mod;
+    if (!m.app?.bundleId || !m.app.scheme)
+        throw new Error(`${path}: the journey module must export app: { bundleId, scheme }`);
+    if (m.home === undefined)
+        throw new Error(`${path}: the journey module must export home (the selector visible after launch)`);
+    if (!m.journeys || Object.keys(m.journeys).length === 0)
+        throw new Error(`${path}: the journey module must export journeys: { <name>: async (t, ctx) => {...} }`);
+    return m;
+}
+export async function main(argv) {
+    const path = journeyModulePath(argv);
+    if (!path)
+        throw new Error('--journey-module <file> is required');
+    return runDriver(argv, await loadJourneyModule(path));
+}
+//# sourceMappingURL=load.js.map

package/dist/src/load.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.js","sourceRoot":"","sources":["../../src/load.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAExD,4GAA4G;AAC5G,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,IAAY,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,EAAE;IACvE,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAyD,CAAC;IAC7G,MAAM,CAAC,GAAG,GAAG,CAAC,OAAO,IAAK,GAAqB,CAAC;IAChD,IAAI,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,4DAA4D,CAAC,CAAC;IAC5H,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,2EAA2E,CAAC,CAAC;IAC9H,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,gFAAgF,CAAC,CAAC;IAClK,OAAO,CAAC,CAAC;AACX,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,IAAuB;IAChD,MAAM,IAAI,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IAClE,OAAO,SAAS,CAAC,IAAI,EAAE,MAAM,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;AACxD,CAAC"}

package/dist/src/platform.d.ts

@@ -0,0 +1,63 @@
+import { type LinkState } from './links.js';
+import { type Locator, type Selector } from './selectors.js';
+import { Screen } from './snapshot.js';
+import { type Driver } from './webdriver.js';
+export type PlatformName = 'ios' | 'android';
+/** Everything that differs between the XCUITest and the UiAutomator2 driver; the session and the journeys do not see it. */
+export interface Platform {
+    readonly name: PlatformName;
+    /** `model-os`, the form of `--device` (BrowserStack's deviceName and platformVersion). */
+    readonly defaultDevice: string;
+    /** Platform capabilities of a session on `device` (`model-os`). */
+    caps(device: string): Record<string, unknown>;
+    /** Sent to `/appium/settings` once the session started. */
+    readonly settings: Record<string, unknown>;
+    /** The lookups to try, in order, for a selector (UiSelector has no OR, so Android text is two). */
+    locators(sel: Selector): Locator[];
+    /** Argument of `mobile: terminateApp / activateApp`. */
+    appArg(appId: string): Record<string, string>;
+    /** Opens a deep link in the app; returns the label of a system prompt it accepted, or null. */
+    openLink(driver: Driver, url: string, state: LinkState): Promise<string | null>;
+    /** Accepts a system prompt if one shows within `waitMs`; returns what it accepted, or null. */
+    acceptAlert(driver: Driver, labels: readonly string[], waitMs: number): Promise<string | null>;
+    /**
+     * `perflab.flushed`: the lookup tried on every poll, which attribute holds the status, and a heavier lookup tried now and
+     * then when the cheap one misses (it needs `setting` on while it runs).
+     */
+    readonly flush: {
+        lookup: Locator;
+        statusAttribute: string;
+        fallback?: {
+            lookup: Locator;
+            setting: string;
+        };
+    };
+    /**
+     * One read of the whole screen that answers any number of "is this selector shown" questions (a step's combined
+     * conditions). The reading also lists the nodes the platform leaves out of lookups (dearer: about twice a plain source on the S23's live screen). Absent where the platform has no cheap one: the session then asks with one lookup per condition.
+     */
+    readScreen?(driver: Driver): Promise<Screen>;
+    /** Whether the on-screen keyboard is up: the question the journey asks, answered the way each platform can. */
+    keyboardShown(driver: Driver): Promise<boolean>;
+    /** One lookup for several resource ids at once: a tree walk costs the same for one id and for ten (UiAutomator2 walks it whole when nothing is found). */
+    readonly anyOfIds?: (ids: readonly string[]) => Locator;
+    /**
+     * Look for one element first (one cheap request when it is there); only when that one is not on screen look at all matches.
+     * The answer is the same as looking at all matches at once.
+     */
+    readonly singleFindFirst?: boolean;
+    /** BrowserStack accepts an upload option that only means something for iOS. */
+    readonly uploadFields: Record<string, string>;
+    /**
+     * GC before the action (docs/plans/gc-before-action.md): asks the SDK to end its open windows, run a full GC and answer.
+     * Returns the SDK's answer (`gc:<n> ok` or `gc:<n> unavailable`), or null when no answer came (an SDK without the command).
+     */
+    gcCommand(driver: Driver, n: number, scheme: string, state: LinkState): Promise<string | null>;
+}
+export declare const GC_ANSWER_WAIT_MS = 10000;
+/** The answer for command n out of `am broadcast` output (`Broadcast completed: result=-1, data="gc:3 ok"`). */
+export declare function parseBroadcastAnswer(out: unknown, n: number): string | null;
+export declare const IOS: Platform;
+export declare const ANDROID: Platform;
+export declare const PLATFORMS: Record<PlatformName, Platform>;
+export declare function platformOf(name: string): Platform;

package/dist/src/platform.js

@@ -0,0 +1,145 @@
+import { ALERT_POLL_MS, acceptAlert as acceptIosAlert, gcLink, openLink as openIosLink } from './links.js';
+import { androidAnyOfIds, androidLocators, id, locator } from './selectors.js';
+import { Screen, parseAndroidSource } from './snapshot.js';
+import { WdError } from './webdriver.js';
+// The split of `model-os` is BrowserStack's: the last dash starts the OS version.
+const modelOf = (device) => device.replace(/-[^-]*$/, '');
+const versionOf = (device) => device.replace(/^.*-/, '');
+const FLUSH_ID = 'perflab.flushed';
+const ACK_ID = 'perflab.ack';
+// Only ends the wait for an iOS answer that never comes (an SDK without the command); no window edge depends on it.
+export const GC_ANSWER_WAIT_MS = 10_000;
+const GC_POLL_MS = 100;
+/** The answer for command n out of `am broadcast` output (`Broadcast completed: result=-1, data="gc:3 ok"`). */
+export function parseBroadcastAnswer(out, n) {
+    const data = /data="([^"]*)"/.exec(String(out ?? ''))?.[1];
+    return data !== undefined && data.startsWith(`gc:${n} `) ? data : null;
+}
+// A command waits for the app to go idle by default; PerfLab must not change the app's pace (docs/plans/61-android-support.md 1.2).
+const NO_WAIT_MS = 0;
+// Appium's own session-idle limit, the same on both platforms.
+const NEW_COMMAND_TIMEOUT_S = 300;
+export const IOS = {
+    name: 'ios',
+    defaultDevice: 'iPhone 15 Pro-17',
+    caps: (device) => ({
+        platformName: 'iOS',
+        'appium:automationName': 'XCUITest',
+        'appium:deviceName': modelOf(device),
+        'appium:platformVersion': versionOf(device),
+        'appium:autoAcceptAlerts': true,
+        'appium:newCommandTimeout': NEW_COMMAND_TIMEOUT_S,
+        'appium:waitForIdleTimeout': NO_WAIT_MS,
+    }),
+    settings: { animationCoolOffTimeout: NO_WAIT_MS, waitForIdleTimeout: NO_WAIT_MS, shouldUseCompactResponses: true },
+    locators: (sel) => [locator(sel)],
+    // The Return key is the one element of the iOS keyboard XCUITest lists reliably.
+    keyboardShown: async (driver) => Boolean(await driver.findShown(id('Return'))),
+    appArg: (bundleId) => ({ bundleId }),
+    openLink: (driver, url, state) => openIosLink(driver, url, state),
+    acceptAlert: (driver, labels, waitMs) => acceptIosAlert(driver, labels, waitMs),
+    flush: { lookup: { using: 'accessibility id', value: FLUSH_ID }, statusAttribute: 'label' },
+    uploadFields: { ios_keychain_support: 'true' },
+    // The link, then the `perflab.ack` element. The trailing space keeps `gc:1` from matching the answer to 10.
+    async gcCommand(driver, n, scheme, state) {
+        await openIosLink(driver, gcLink(scheme, n), state);
+        const want = `type == "XCUIElementTypeStaticText" AND name == "${ACK_ID}" AND label BEGINSWITH "gc:${n} "`;
+        const deadline = driver.now() + GC_ANSWER_WAIT_MS;
+        for (;;) {
+            const el = await driver.find('-ios predicate string', want);
+            // The predicate already matched `gc:<n> `; an unreadable label is taken as ok and logged, so a run that relied on it can be found.
+            if (el)
+                return driver
+                    .cmd('GET', `/element/${el}/attribute/label`)
+                    .then(String)
+                    .catch(() => {
+                    driver.log.push({ ...driver.context, cmd: 'gc-ack-label', t: driver.now(), ms: 0, status: 1 });
+                    return `gc:${n} ok`;
+                });
+            if (driver.now() > deadline)
+                return null;
+            await driver.sleep(GC_POLL_MS);
+        }
+    },
+};
+export const ANDROID = {
+    name: 'android',
+    // The phone of the TapIn farm workflow (docs/plans/61-android-support.md 1.2).
+    defaultDevice: 'Google Pixel 7-13.0',
+    caps: (device) => ({
+        platformName: 'Android',
+        'appium:automationName': 'UiAutomator2',
+        'appium:deviceName': modelOf(device),
+        'appium:platformVersion': versionOf(device),
+        'appium:autoGrantPermissions': true,
+        'appium:newCommandTimeout': NEW_COMMAND_TIMEOUT_S,
+    }),
+    // enableMultiWindows: with an RN Modal open (its own Dialog window) XPath and the source still reach the activity window under it, where the flush element lives.
+    // ignoreUnimportantViews: lookups skip nodes Android marks not important for accessibility, about 30 % faster on the S23. Safe for a journey that looks for RN testIDs, texts and descriptions: in 6 recorded S23 page sources every node with an app testID (live.*) was a11y-important (4, 21 and 26 in plain sources, 40, 42 and 47 with hidden nodes; 0 unimportant). A bare wrapper view without testID would not be found.
+    settings: { waitForIdleTimeout: NO_WAIT_MS, actionAcknowledgmentTimeout: NO_WAIT_MS, waitForSelectorTimeout: NO_WAIT_MS, enableMultiWindows: true, ignoreUnimportantViews: true },
+    locators: androidLocators,
+    appArg: (appId) => ({ appId }),
+    // `package` pins the link to the app: a scheme two builds register would otherwise show a chooser.
+    async openLink(driver, url) {
+        await driver.execute('mobile: deepLink', { url, package: driver.bundleId });
+        return null;
+    },
+    // UiAutomator2 has the W3C alert commands, which handle the runtime-permission dialog (there are no button labels to choose from).
+    async acceptAlert(driver, _labels, waitMs) {
+        const deadline = driver.now() + waitMs;
+        for (;;) {
+            try {
+                const alertText = await driver.cmd('GET', '/alert/text');
+                await driver.cmd('POST', '/alert/accept', {});
+                return String(alertText);
+            }
+            catch (e) {
+                if (!(e instanceof WdError && e.wdError === 'no such alert'))
+                    throw e;
+            }
+            if (driver.now() > deadline)
+                return null;
+            await driver.sleep(ALERT_POLL_MS);
+        }
+    },
+    // The cheap UiSelector lookup on content-desc; XPath walks every window, so it is only the fallback (a Modal open). The status is the element's text.
+    flush: {
+        lookup: { using: '-android uiautomator', value: `new UiSelector().description("${FLUSH_ID}")` },
+        statusAttribute: 'text',
+        fallback: { lookup: { using: 'xpath', value: `//*[@content-desc="${FLUSH_ID}"]` }, setting: 'allowInvisibleElements' },
+    },
+    async readScreen(driver) {
+        // The source leaves out nodes the accessibility service calls not visible unless this is on; the screen decides for itself which of them count (snapshot.ts).
+        await driver.cmd('POST', '/appium/settings', { settings: { allowInvisibleElements: true } });
+        let xml;
+        try {
+            xml = await driver.cmd('GET', '/source');
+        }
+        finally {
+            await driver.cmd('POST', '/appium/settings', { settings: { allowInvisibleElements: false } }).catch(() => null);
+        }
+        return new Screen(parseAndroidSource(xml), await driver.screen());
+    },
+    keyboardShown: async (driver) => Boolean(await driver.execute('mobile: isKeyboardShown')),
+    singleFindFirst: true,
+    anyOfIds: androidAnyOfIds,
+    uploadFields: {},
+    // A broadcast pauses no activity (a link does). `am broadcast` returns once the SDK finished the receiver, so its output is the answer.
+    async gcCommand(driver, n) {
+        const out = await driver.execute('mobile: broadcast', {
+            action: `${driver.bundleId}.perflab.COMMAND`,
+            package: driver.bundleId,
+            extras: [['s', 'cmd', 'gc'], ['i', 'n', String(n)]],
+            // FLAG_RECEIVER_FOREGROUND: the foreground broadcast queue, not the background one that other apps' broadcasts can delay.
+            flags: '0x10000000',
+        });
+        return parseBroadcastAnswer(out, n);
+    },
+};
+export const PLATFORMS = { ios: IOS, android: ANDROID };
+export function platformOf(name) {
+    if (!Object.hasOwn(PLATFORMS, name))
+        throw new Error(`--platform ${name}: the Appium driver drives ios and android`);
+    return PLATFORMS[name];
+}
+//# sourceMappingURL=platform.js.map

package/dist/src/platform.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../../src/platform.ts"],"names":[],"mappings":"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"}