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

package/dist/src/run.d.ts

@@ -0,0 +1,92 @@
+import type { JourneyModule } from './journey.js';
+import { type FetchLike } from './webdriver.js';
+export interface IterationRecord {
+    journey: string;
+    iteration: number;
+    token: boolean;
+    alert?: string | null;
+    steps?: number;
+    ready?: {
+        n: number;
+        ms: number;
+    };
+    flushed?: string | null;
+    t_start?: number;
+    begin_ms?: number;
+    journey_ms?: number;
+    end_ms?: number;
+    total_ms?: number;
+}
+export interface RunDeps {
+    env: Readonly<Record<string, string | undefined>>;
+    fetch: FetchLike;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    print: (line: string) => void;
+    error: (line: string) => void;
+}
+export declare const realRunDeps: () => RunDeps;
+/** The flags `perflab farm run` passes (docs/plans/54a section 4); a journey module adds its own through `options`. */
+export declare const DRIVER_OPTIONS: {
+    readonly 'journey-module': {
+        readonly type: "string";
+    };
+    readonly app: {
+        readonly type: "string";
+    };
+    readonly 'app-custom-id': {
+        readonly type: "string";
+        readonly default: "";
+    };
+    readonly 'tokens-js': {
+        readonly type: "string";
+    };
+    readonly journeys: {
+        readonly type: "string";
+    };
+    readonly repeat: {
+        readonly type: "string";
+        readonly default: "1";
+    };
+    readonly device: {
+        readonly type: "string";
+    };
+    readonly 'local-identifier': {
+        readonly type: "string";
+    };
+    readonly 'build-name': {
+        readonly type: "string";
+        readonly default: "keepsnappy-appium";
+    };
+    readonly 'appium-version': {
+        readonly type: "string";
+        readonly default: "2.19.0";
+    };
+    readonly out: {
+        readonly type: "string";
+        readonly default: "farm-run";
+    };
+    readonly platform: {
+        readonly type: "string";
+        readonly default: "ios";
+    };
+    readonly 'action-gc': {
+        readonly type: "string";
+        readonly default: "off";
+    };
+    readonly 'end-gc': {
+        readonly type: "string";
+        readonly default: "off" | "on";
+    };
+};
+type Args = Record<string, string | boolean | undefined>;
+export declare function parseDriverArgs(argv: readonly string[], module: JourneyModule): Args;
+/** The module path out of the command line, before the module's own options are known. */
+export declare function journeyModulePath(argv: readonly string[]): string | undefined;
+/**
+ * One BrowserStack App Automate session that runs every iteration of the module's journeys, then a final flush, and
+ * writes <out>/driver-log.json and <out>/browserstack.<platform>.json in the shape `perflab farm close --bs-build`
+ * reads. Returns the exit code: 0, or 1 when the session or an iteration failed (the result files are written anyway).
+ */
+export declare function runDriver(argv: readonly string[], module: JourneyModule, deps?: RunDeps): Promise<number>;
+export {};

package/dist/src/run.js

@@ -0,0 +1,157 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { basicAuth, HUB, resolveApp, sessionCaps, sessionDetail } from './browserstack.js';
+import { END_GC_DEFAULT } from './links.js';
+import { platformOf } from './platform.js';
+import { Session } from './session.js';
+import { parseTokensJs, plan } from './tokens.js';
+import { Driver, realSleep } from './webdriver.js';
+export const realRunDeps = () => ({
+    env: process.env,
+    fetch: fetch,
+    now: Date.now,
+    sleep: realSleep,
+    print: (l) => console.log(l),
+    error: (l) => console.error(l),
+});
+/** The flags `perflab farm run` passes (docs/plans/54a section 4); a journey module adds its own through `options`. */
+export const DRIVER_OPTIONS = {
+    'journey-module': { type: 'string' },
+    app: { type: 'string' },
+    'app-custom-id': { type: 'string', default: '' },
+    'tokens-js': { type: 'string' },
+    journeys: { type: 'string' },
+    repeat: { type: 'string', default: '1' },
+    device: { type: 'string' },
+    'local-identifier': { type: 'string' },
+    'build-name': { type: 'string', default: 'keepsnappy-appium' },
+    'appium-version': { type: 'string', default: '2.19.0' },
+    out: { type: 'string', default: 'farm-run' },
+    platform: { type: 'string', default: 'ios' },
+    'action-gc': { type: 'string', default: 'off' },
+    'end-gc': { type: 'string', default: END_GC_DEFAULT ? 'on' : 'off' },
+};
+export function parseDriverArgs(argv, module) {
+    const values = parseArgs({ args: [...argv], options: { ...(module.options ?? {}), ...DRIVER_OPTIONS } }).values;
+    // The journey reads `ctx.args.device`: it is the resolved device, not unset.
+    values.device ??= platformOf(String(values.platform)).defaultDevice;
+    return values;
+}
+/** The module path out of the command line, before the module's own options are known. */
+export function journeyModulePath(argv) {
+    return parseArgs({ args: [...argv], options: { 'journey-module': { type: 'string' } }, strict: false }).values['journey-module'];
+}
+/**
+ * One BrowserStack App Automate session that runs every iteration of the module's journeys, then a final flush, and
+ * writes <out>/driver-log.json and <out>/browserstack.<platform>.json in the shape `perflab farm close --bs-build`
+ * reads. Returns the exit code: 0, or 1 when the session or an iteration failed (the result files are written anyway).
+ */
+export async function runDriver(argv, module, deps = realRunDeps()) {
+    const a = parseDriverArgs(argv, module);
+    const user = deps.env.BROWSERSTACK_USERNAME;
+    const key = deps.env.BROWSERSTACK_ACCESS_KEY;
+    if (!user || !key)
+        throw new Error('BROWSERSTACK_USERNAME / BROWSERSTACK_ACCESS_KEY are not set');
+    if (!a.app || !a['tokens-js'] || !a.journeys)
+        throw new Error('--app, --tokens-js and --journeys are required');
+    const platform = platformOf(String(a.platform));
+    const journeys = String(a.journeys).split(',').map((s) => s.trim()).filter(Boolean);
+    const unknown = journeys.filter((j) => !Object.hasOwn(module.journeys, j));
+    if (unknown.length)
+        throw new Error(`the journey module has no journey ${unknown.map((j) => `"${j}"`).join(', ')} (it has ${Object.keys(module.journeys).join(', ') || 'none'})`);
+    const repeat = Number(a.repeat);
+    if (!Number.isInteger(repeat) || repeat < 1)
+        throw new Error('--repeat must be a whole number >= 1');
+    if (a['action-gc'] !== 'on' && a['action-gc'] !== 'off')
+        throw new Error('--action-gc must be on or off');
+    if (a['end-gc'] !== 'on' && a['end-gc'] !== 'off')
+        throw new Error('--end-gc must be on or off');
+    const out = String(a.out);
+    const auth = basicAuth(user, key);
+    mkdirSync(out, { recursive: true });
+    const { api, tokens } = parseTokensJs(readFileSync(String(a['tokens-js']), 'utf8'));
+    const appUrl = await resolveApp(String(a.app), String(a['app-custom-id'] ?? ''), auth, deps.fetch, platform);
+    deps.print(`app: ${appUrl}`);
+    const log = [];
+    const driver = new Driver({ hub: HUB, log, headers: { Authorization: auth }, bundleId: module.app.bundleId, platform, fetch: deps.fetch, now: deps.now, sleep: deps.sleep });
+    const t = new Session({ driver, scheme: module.app.scheme, fetch: deps.fetch, api, actionGc: a['action-gc'] === 'on', endGc: a['end-gc'] === 'on' });
+    const sessionName = module.sessionName ?? 'perflab (appium)';
+    const device = String(a.device);
+    const ctx = { fetch: deps.fetch, tokens, journeys, repeat, args: a };
+    const caps = sessionCaps({ appUrl, device, buildName: String(a['build-name']), sessionName, appiumVersion: String(a['appium-version']), platform, localIdentifier: a['local-identifier'] });
+    const startedAt = deps.now();
+    let error = null;
+    const iterations = [];
+    try {
+        await driver.start(caps);
+        deps.print(`session ${driver.sessionId}`);
+        await driver
+            .cmd('POST', '/appium/settings', { settings: platform.settings })
+            .catch(() => null);
+        await module.setup?.(t, ctx);
+        await runIterations(t, module, ctx, iterations);
+    }
+    catch (e) {
+        error = e instanceof Error ? e : new Error(String(e));
+        deps.error(`::error::${error.message}`);
+        if (driver.sessionId) {
+            const source = await driver.cmd('GET', '/source').catch(() => null);
+            if (typeof source === 'string')
+                writeFileSync(join(out, 'failure-source.xml'), source);
+            const png = await driver.cmd('GET', '/screenshot').catch(() => null);
+            if (typeof png === 'string')
+                writeFileSync(join(out, 'failure-screen.png'), Buffer.from(png, 'base64'));
+        }
+    }
+    if (driver.sessionId) {
+        // A failed iteration still sends what it measured.
+        driver.context = { phase: 'final-flush' };
+        await t.endRun().catch(() => null);
+        const reason = error ? error.message.slice(0, 250) : `${sessionName} done`;
+        await driver.execute(`browserstack_executor: ${JSON.stringify({ action: 'setSessionStatus', arguments: { status: error ? 'failed' : 'passed', reason } })}`).catch(() => null);
+    }
+    const endedAt = deps.now();
+    await driver.end();
+    const detail = driver.sessionId ? await sessionDetail(driver.sessionId, auth, deps.fetch) : {};
+    const buildId = detail.build_hashed_id ?? null;
+    writeFileSync(join(out, `browserstack.${String(a.platform)}.json`), `${JSON.stringify({
+        driver: 'appium',
+        status: error ? 'failed' : 'passed',
+        buildId,
+        dashboard: detail.public_url ?? detail.browser_url ?? null,
+        devices: [{ device, sessions: [{ id: driver.sessionId, ...(error ? { error: { message: error.message } } : {}) }] }],
+    }, null, 2)}\n`);
+    writeFileSync(join(out, 'driver-log.json'), `${JSON.stringify({ driver: 'appium', device, appUrl, session: driver.sessionId, buildId, linkMode: t.linkState.linkMode ?? null, actionGc: t.actionGc, endGc: t.endGc, linkError: t.linkState.linkError ?? null, startedAt, endedAt, total_ms: endedAt - startedAt, error: error?.message ?? null, iterations, commands: log }, null, 2)}\n`);
+    deps.print(`driver-log.json: ${log.length} commands, ${iterations.length} iterations, ${Math.round((endedAt - startedAt) / 1000)} s`);
+    for (const r of iterations)
+        deps.print(`  ${r.journey} #${r.iteration}: ${r.total_ms ?? '?'} ms, flushed=${r.flushed}`);
+    return error ? 1 : 0;
+}
+/** Per iteration: begin-run (relaunch, home, activation link), the journey, `run:complete`, end-run (markers, flush link). */
+async function runIterations(t, module, ctx, iterations) {
+    const { driver } = t;
+    for (const it of plan(ctx.journeys, ctx.repeat, ctx.tokens)) {
+        const rec = { journey: it.journey, iteration: it.iteration, token: it.token !== '' };
+        iterations.push(rec);
+        driver.context = { journey: it.journey, iteration: it.iteration, phase: 'begin' };
+        const t0 = t.now();
+        rec.alert = await t.beginRun({ token: it.token, home: module.home, ...(module.sdkArgs ? { args: module.sdkArgs } : {}) });
+        const t1 = t.now();
+        driver.context = { ...driver.context, phase: 'journey' };
+        const waitsBefore = t.readyWaits.length;
+        await module.journeys[it.journey](t, { ...ctx, journey: it.journey, iteration: it.iteration });
+        // The last action's screen is part of the journey: its wait ends before the completion marker and the flush.
+        await t.ready();
+        const t2 = t.now();
+        t.marker('run:complete', 'end');
+        rec.steps = t.markers.filter((m) => m.phase === 'start').length;
+        const waits = t.readyWaits.slice(waitsBefore);
+        rec.ready = { n: waits.length, ms: waits.reduce((x, y) => x + y, 0) };
+        driver.context = { ...driver.context, phase: 'end' };
+        rec.flushed = await t.endRun();
+        const t3 = t.now();
+        Object.assign(rec, { t_start: t0, begin_ms: t1 - t0, journey_ms: t2 - t1, end_ms: t3 - t2, total_ms: t3 - t0 });
+    }
+}
+//# sourceMappingURL=run.js.map

package/dist/src/run.js.map

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

package/dist/src/selectors.d.ts

@@ -0,0 +1,25 @@
+/** What a journey points at. A bare string is an accessibility id. */
+export interface Selector {
+    id?: string;
+    text?: string;
+    childOf?: string;
+}
+export type SelectorLike = Selector | string;
+export declare const toSelector: (s: SelectorLike) => Selector;
+export declare const id: (value: string) => Selector;
+export declare const text: (value: string) => Selector;
+/** An id whose text also matches. */
+export declare const idText: (value: string, re: string) => Selector;
+export declare const childOf: (selector: Selector, parentId: string) => Selector;
+export declare const REGEX_CHARS: RegExp;
+export interface Locator {
+    using: string;
+    value: string;
+}
+/** The WebDriver locator for a selector, without its parent. */
+export declare function locator(sel: Selector): Locator;
+export declare const describeSelector: (sel: Selector) => string;
+/** The UiAutomator2 locators for a selector, without its parent, in the order to try them. */
+export declare function androidLocators(sel: Selector): Locator[];
+/** One UiAutomator2 lookup that finds an element whose resource id is any of `ids` (a plain id is matched literally, a regex id as a whole value). */
+export declare function androidAnyOfIds(ids: readonly string[]): Locator;

package/dist/src/selectors.js

@@ -0,0 +1,57 @@
+export const toSelector = (s) => (typeof s === 'string' ? { id: s } : s);
+export const id = (value) => ({ id: value });
+export const text = (value) => ({ text: value });
+/** An id whose text also matches. */
+export const idText = (value, re) => ({ id: value, text: re });
+export const childOf = (selector, parentId) => ({ ...selector, childOf: parentId });
+// `id` and `text` match whole values as regexes; a plain id goes to the exact accessibility-id lookup.
+export const REGEX_CHARS = /[\\()[\]*+?|^$]/;
+const quote = (s) => `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+const matches = (attr, re) => `${attr} MATCHES ${quote(`(?is)${re}`)}`;
+const textMatch = (re) => `(${matches('label', re)} OR ${matches('value', re)})`;
+/** The WebDriver locator for a selector, without its parent. */
+export function locator(sel) {
+    if (sel.id !== undefined && sel.text === undefined && !REGEX_CHARS.test(sel.id)) {
+        return { using: 'accessibility id', value: sel.id };
+    }
+    const parts = [];
+    if (sel.id !== undefined)
+        parts.push(REGEX_CHARS.test(sel.id) ? matches('name', sel.id) : `name == ${quote(sel.id)}`);
+    if (sel.text !== undefined)
+        parts.push(textMatch(sel.text));
+    return { using: '-ios predicate string', value: parts.join(' AND ') };
+}
+export const describeSelector = (sel) => [sel.id !== undefined ? `id=${sel.id}` : null, sel.text !== undefined ? `text=${sel.text}` : null, sel.childOf !== undefined ? `childOf=${sel.childOf}` : null]
+    .filter(Boolean)
+    .join(' ');
+// UiAutomator2: an RN testID is the `resource-id` (bare, without the package prefix); `accessibilityLabel` is `content-desc`.
+// UiSelector has no OR, so a text selector is two lookups (`text`, then `content-desc`) and the driver tries them in turn.
+// UiAutomator2's selector parser reads a backslash literally (measured on a Galaxy S23: "Tap \\(1\\)" matched, the Java-doubled form did not), only `\"` is an escape.
+const javaString = (s) => `"${s.replace(/"/g, '\\"')}"`;
+// A value ending in a backslash would escape the closing quote: an empty group after an escaped backslash fixes it, an odd count is not a regex.
+const javaRegex = (re) => {
+    const trailing = /\\*$/.exec(re)[0].length;
+    if (trailing % 2 === 1)
+        throw new Error(`selector ${JSON.stringify(re)} ends in a lone backslash`);
+    return javaString(`(?is)${re}${trailing > 0 ? '(?:)' : ''}`);
+};
+/** The UiAutomator2 locators for a selector, without its parent, in the order to try them. */
+export function androidLocators(sel) {
+    const base = () => {
+        if (sel.id === undefined)
+            return [];
+        return [REGEX_CHARS.test(sel.id) ? `resourceIdMatches(${javaRegex(sel.id)})` : `resourceId(${javaString(sel.id)})`];
+    };
+    const using = '-android uiautomator';
+    const build = (extra) => ({ using, value: `new UiSelector()${[...base(), ...extra].map((c) => `.${c}`).join('')}` });
+    if (sel.text === undefined)
+        return [build([])];
+    return [build([`textMatches(${javaRegex(sel.text)})`]), build([`descriptionMatches(${javaRegex(sel.text)})`])];
+}
+const escapeRegex = (s) => s.replace(/[\\^$.|?*+()[\]{}]/g, '\\$&');
+/** One UiAutomator2 lookup that finds an element whose resource id is any of `ids` (a plain id is matched literally, a regex id as a whole value). */
+export function androidAnyOfIds(ids) {
+    const alternatives = ids.map((id) => `(?:${REGEX_CHARS.test(id) ? id : escapeRegex(id)})`).join('|');
+    return { using: '-android uiautomator', value: `new UiSelector().resourceIdMatches(${javaRegex(alternatives)})` };
+}
+//# sourceMappingURL=selectors.js.map

package/dist/src/selectors.js.map

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

package/dist/src/session.d.ts

@@ -0,0 +1,199 @@
+import { type LinkState } from './links.js';
+import { type SelectorLike } from './selectors.js';
+import { type Driver, type FetchLike } from './webdriver.js';
+export interface Marker {
+    token: string;
+    step: string;
+    phase: 'start' | 'end';
+    t_host: number;
+    /** The GC command answered just before this step's start (GC before the action). */
+    gc_n?: number;
+}
+/** One request/response round trip with the PerfLab API: t0/t3 this host's send/receive, t1/t2 the server's receive/send. */
+export interface ClockTrip {
+    t0: number;
+    t1: number;
+    t2: number;
+    t3: number;
+}
+/** The API takes at most this many markers in one request; more go out in several. */
+export declare const MARKERS_PER_REQUEST = 500;
+/**
+ * Small /v1/clock round trips per run after its markers. The marker batch is one slow trip (a large body), and the API takes
+ * the shortest trip's half-delay as the host clock's error: one trip left it at 130-200 ms, more than a short step lasts.
+ */
+export declare const HOST_CLOCK_TRIPS = 6;
+export interface SendOptions {
+    sleep?: (ms: number) => Promise<void>;
+    /** This host's clock, the one `t_host` is on (each request is a round trip on it). */
+    now?: () => number;
+}
+/**
+ * The iteration's markers, posted after it ended so sending never changes the test's pace: one request per run token
+ * (per 500 markers), so a long journey does not run into the API's per-run rate limit. An API that predates batches
+ * answers 400 without per-item results; its markers then go one by one as before. Each request is a round trip on the
+ * clock of `t_host`: its trip rides on the run's next request and the last one goes to /v1/clock, followed by
+ * HOST_CLOCK_TRIPS small clock round trips, so the API can put the markers on the device's clock. Returns how many arrived.
+ */
+export declare function sendMarkers(fetchImpl: FetchLike, api: string, markers: Marker[], opts?: SendOptions): Promise<number>;
+export declare const FLUSH_WAIT_MS: number;
+type Step = () => Promise<unknown> | unknown;
+/** One thing a step expects of the screen: an element shown, an element gone, or the keyboard up or down. */
+export type Condition = {
+    shown: SelectorLike;
+} | {
+    gone: SelectorLike;
+} | {
+    keyboard: 'up' | 'down';
+};
+/** GC before the action: `off` (the default), `step` (a command before every declared step), or why it stopped. */
+export type ActionGc = 'off' | 'step' | 'unsupported' | 'unavailable' | 'safari';
+export interface SessionOptions {
+    driver: Driver;
+    scheme: string;
+    fetch?: FetchLike;
+    api?: string;
+    /** Sends a GC command before every declared step and once before the flush. An experiment switch, off by default. */
+    actionGc?: boolean;
+    /**
+     * Sends one GC command at the run end, after the journey's last step and before the flush, also when `actionGc` is off: the end
+     * memory reading after a GC (REQ-MEAS-35). On by default (`END_GC_DEFAULT`); the journey should end on its home screen.
+     */
+    endGc?: boolean;
+}
+/** One measured session: the phone, the run tokens, and the step vocabulary a journey calls. */
+export declare class Session {
+    readonly driver: Driver;
+    readonly scheme: string;
+    readonly fetch: FetchLike;
+    readonly api: string;
+    markers: Marker[];
+    token: string;
+    readonly linkState: LinkState;
+    /** What the journey said must show before the next action: the previous action's result. */
+    pendingReady: {
+        sel: SelectorLike;
+        timeoutMs: number;
+    } | null;
+    /** Time each readiness wait took, in ms. */
+    readonly readyWaits: number[];
+    actionGc: ActionGc;
+    readonly endGc: boolean;
+    /** Unique for the whole session; the SDK keeps its answers by run token and n. */
+    gcN: number;
+    /** Steps open right now: a step inside another step's action sends no GC, which would land inside the outer step. */
+    stepDepth: number;
+    /** Elements looked up again after going stale, over the session (see `frameOf`). */
+    private refinds;
+    get staleRefinds(): number;
+    constructor(o: SessionOptions);
+    /**
+     * One GC command; returns its number, or null when none was sent or none ran. Any answer but `gc:<n> ok` (none, a native
+     * timeout, an error, `unavailable` from an app without a GC) turns the command off for the rest of the session: a measuring
+     * aid never fails the customer's test, and the steps then carry no number. `atEnd`: the run end's command, which `endGc` sends
+     * also while the per-step command is off.
+     */
+    gc(atEnd?: boolean): Promise<number | null>;
+    now(): number;
+    /** After the action just made: the next action waits until `sel` is visible (the screen or element the action leads to). */
+    expectNext(sel: SelectorLike, timeoutMs?: number): void;
+    /** Before the next action: waits for what `expectNext` named, if anything. Throws when it does not show in time. */
+    ready(): Promise<number>;
+    /** A declared step marker, kept until the iteration ends. */
+    marker(step: string, phase: 'start' | 'end', gcN?: number | null): void;
+    /**
+     * One declared step: the readiness wait, `start`, the action, its checks and `once` (asserted before `end` only), `end`, then
+     * the checks again. `step(name, fn)` is the short form.
+     */
+    step(name: string, action: Step, checks?: Step, once?: Step): Promise<void>;
+    isVisible(sel: SelectorLike): Promise<boolean>;
+    waitVisible(sel: SelectorLike, timeoutMs?: number): Promise<string>;
+    waitGone(sel: SelectorLike, timeoutMs?: number): Promise<void>;
+    /** Waits until the keyboard is up (or down). */
+    waitKeyboard(want: 'up' | 'down', timeoutMs?: number): Promise<void>;
+    /**
+     * Waits until all the conditions hold in one poll. A poll asks them one lookup after another, so "the same poll" means the
+     * answers are a few hundred ms apart, not one instant. Where the platform can look for several ids in one request (Android)
+     * the ids are asked together; elsewhere each condition is waited for in turn, with its own timeout, as `waitVisible`,
+     * `waitGone` and `waitKeyboard` do.
+     */
+    waitAll(conditions: readonly Condition[], timeoutMs?: number): Promise<void>;
+    tap(sel: SelectorLike, timeoutMs?: number): Promise<void>;
+    /** Taps again while `target` has not shown and `sel` is still there (a tap right after a launch can land before the app takes touches). Returns how many extra taps it took. */
+    tapUntil(sel: SelectorLike, target: SelectorLike, timeoutMs?: number, retapAfterMs?: number): Promise<number>;
+    /**
+     * Swipe start/end in percent of the window. `target` is what the swipe acts on (the list or screen it starts in): the swipe
+     * waits for it to be visible, so it does not fire during the transition of the action before it. It does not wait for a fling to stop: the next tap after a swipe still needs `expectNext` on an element that is stable only once the scroll ended.
+     */
+    swipe(from: readonly [number, number], to: readonly [number, number], durationMs?: number, target?: SelectorLike): Promise<void>;
+    /** Swipe from an element's centre to 90 % of the window height (down) or 10 % (up). */
+    swipeFrom(sel: SelectorLike, direction: 'up' | 'down', durationMs?: number): Promise<void>;
+    /** Swipes until `sel` shows or `times` runs out. */
+    swipeUntilVisible(sel: SelectorLike, from: readonly [number, number], to: readonly [number, number], durationMs: number, times: number): Promise<void>;
+    /** Swipes from `from` (an element, as `swipeFrom`) until `target` shows or `times` swipes are used; throws when it never shows. */
+    swipeFromUntilVisible(from: SelectorLike, direction: 'up' | 'down', target: SelectorLike, times: number, durationMs?: number): Promise<void>;
+    /** Checks for the element fully on screen, then swipes from the centre, for as long as the timeout. speed 40 is a 601 ms swipe. */
+    scrollUntil(sel: SelectorLike, { direction, timeoutMs, speed }?: {
+        direction?: 'up' | 'down';
+        timeoutMs?: number;
+        speed?: number;
+    }): Promise<void>;
+    /**
+     * The frame of `sel`'s element. When the element went stale (the app re-mounted it between the lookup and the read), it is
+     * looked up again by the same selector, at most STALE_REFINDS times for this read; any other error passes straight through.
+     * A re-find is a lookup, not a touch: it adds no gesture, but it adds its lookup time to the window of the touch before it.
+     */
+    private frameOf;
+    /** `sel`'s frame once it reads the same twice in a row (a sheet still sliding in moves it). */
+    private settledFrame;
+    /** One fling inside `r`: 80 % to 30 % of its height towards the end, 30 % to 80 % back to the top, on its centre line. */
+    private flingIn;
+    /**
+     * Exactly `times` flings of `list` towards its end or back to its top, whatever the list holds: the same touches, so the
+     * same windows, in every run (REQ-FARM-33). The list's frame is read (settled) once, before the first fling, and every
+     * fling uses it: nothing is looked up or read between flings, so no lookup or re-find lands inside their windows. The
+     * caller then checks a condition the flings always reach.
+     */
+    flingTimes(list: SelectorLike, times: number, toward: 'end' | 'top', { durationMs, timeoutMs }?: {
+        durationMs?: number;
+        timeoutMs?: number;
+    }): Promise<void>;
+    /**
+     * Flings `list` until `target` is fully on screen. The number of flings depends on the data, so the step's windows can
+     * differ between runs: NOT for a judged step (REQ-FARM-33; use `flingTimes`). `blind` flings go first with no lookup.
+     * Returns the flings; logs flings, checks, blind and re-finds, also when it fails.
+     */
+    flingUntil(list: SelectorLike, target: SelectorLike, toward: 'end' | 'top', { blind, durationMs, timeoutMs }?: {
+        blind?: number;
+        durationMs?: number;
+        timeoutMs?: number;
+    }): Promise<number>;
+    /** The centres of `sels`' frames, once every frame reads the same twice in a row; a stale element is looked up again. For `tapAt`. */
+    stableCentres(sels: readonly SelectorLike[], timeoutMs?: number): Promise<{
+        x: number;
+        y: number;
+    }[]>;
+    /** A touch at a window point with no lookup (e.g. from `stableCentres`): the same touch as `tap`, after the same `ready()`. */
+    tapAt(point: {
+        x: number;
+        y: number;
+    }): Promise<void>;
+    type(sel: SelectorLike, value: string): Promise<void>;
+    /** Taps the button of a system alert if one shows within `waitMs`; returns the label tapped, or null. */
+    acceptAlert(labels: readonly string[], waitMs: number): Promise<string | null>;
+    openLink(url: string): Promise<string | null>;
+    /** A relaunch ends the screen a pending `expectNext` was waiting for; the wait must not leak into what comes after. */
+    relaunch(): Promise<void>;
+    activate(): Promise<unknown>;
+    /** Launch, wait for `home`, then the activation link with this iteration's token; `args` (`k=v&...`) override the run defaults. */
+    beginRun({ token, args, home }: {
+        token: string;
+        args?: string;
+        home: SelectorLike;
+    }): Promise<string | null>;
+    /** Markers, then the flush link, then the SDK's own `perflab.flushed` (ok | error | off). */
+    endRun(): Promise<string | null>;
+    /** The heavy lookup, with its setting on only while it runs. */
+    private findFallback;
+}
+export {};