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

package/dist/src/snapshot.js

@@ -0,0 +1,197 @@
+import { REGEX_CHARS } from './selectors.js';
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+const unescapeXml = (s) => s.replace(/&(#x[0-9a-f]+|#\d+|amp|lt|gt|quot|apos);/gi, (_, e) => e[0] === '#' ? String.fromCodePoint(e[1].toLowerCase() === 'x' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10)) : ENTITIES[e.toLowerCase()]);
+// A value that holds a double quote is written in single quotes (text='"quoted"'), and the other way round.
+const TAG = /<(\/?)([\w.$:-]+)((?:\s+[\w:.-]+=(?:"[^"]*"|'[^']*'))*)\s*(\/?)>/g;
+const ATTR = /([\w:.-]+)=(?:"([^"]*)"|'([^']*)')/g;
+const BOUNDS = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/;
+/** The nodes of a UiAutomator2 `GET /source`, in document order, each with the index of its parent (-1 for the root). */
+export function parseAndroidSource(xml) {
+    const nodes = [];
+    const open = [];
+    for (const m of xml.matchAll(TAG)) {
+        if (m[1] === '/') {
+            open.pop();
+            continue;
+        }
+        const attrs = {};
+        for (const a of m[3].matchAll(ATTR))
+            attrs[a[1]] = unescapeXml(a[2] ?? a[3]);
+        const b = BOUNDS.exec(attrs.bounds ?? '');
+        const node = {
+            parent: open.length ? open[open.length - 1] : -1,
+            id: attrs['resource-id'] ?? '',
+            text: attrs.text ?? '',
+            desc: attrs['content-desc'] ?? '',
+            displayed: attrs.displayed === 'true',
+            scrollable: attrs.scrollable === 'true',
+            left: b ? +b[1] : 0,
+            top: b ? +b[2] : 0,
+            right: b ? +b[3] : 0,
+            bottom: b ? +b[4] : 0,
+        };
+        nodes.push(node);
+        if (m[4] !== '/')
+            open.push(nodes.length - 1);
+    }
+    return nodes;
+}
+const inverted = (n) => n.bottom < n.top;
+/**
+ * Whether the node counts as on screen, from what the platform says about it. `displayed` is kept: a node it calls not
+ * displayed is hidden. A node with inverted bounds (top below bottom) is never shown by this test; `Screen` rescues some
+ * of them, see below. An empty or off-screen frame never counts, and with `full` the whole frame must be inside the window.
+ */
+export function nodeShown(n, w, full = false) {
+    if (!n.displayed || inverted(n))
+        return false;
+    if (n.right - n.left <= 0 || n.bottom - n.top <= 0)
+        return false;
+    if (full)
+        return n.left >= 0 && n.top >= 0 && n.right <= w.width && n.bottom <= w.height;
+    return n.left < w.width && n.top < w.height && n.right > 0 && n.bottom > 0;
+}
+/** A Java regex as the selectors write it (`(?is)` is added, a match is a whole-value match) read by JavaScript; null when it cannot be read faithfully. */
+function wholeMatch(re) {
+    if (/\(\?[^:=!<]/.test(re) || /\\[AZzGhHRVXpPk]|\\Q|[*+?}]\+/.test(re))
+        return null;
+    try {
+        return new RegExp(`^(?:${re})$`, 'is');
+    }
+    catch {
+        return null;
+    }
+}
+/** The node test of a selector without its parent, or null when the selector uses a regex JavaScript would read differently. */
+export function nodeMatcher(sel) {
+    let idTest = null;
+    if (sel.id !== undefined) {
+        if (REGEX_CHARS.test(sel.id)) {
+            const re = wholeMatch(sel.id);
+            if (!re)
+                return null;
+            idTest = (s) => re.test(s);
+        }
+        else {
+            const want = sel.id;
+            idTest = (s) => s === want;
+        }
+    }
+    let textRe = null;
+    if (sel.text !== undefined) {
+        textRe = wholeMatch(sel.text);
+        if (!textRe)
+            return null;
+    }
+    return (n) => (idTest ? idTest(n.id) : true) && (textRe ? textRe.test(n.text) || textRe.test(n.desc) : true);
+}
+/** A test of a resource id the way a selector's `id` reads it, or null when JavaScript would read it differently from UiAutomator2. */
+export function idMatcher(id) {
+    const m = nodeMatcher({ id });
+    return m && ((resourceId) => m({ parent: -1, id: resourceId, text: '', desc: '', displayed: true, scrollable: false, left: 0, top: 0, right: 0, bottom: 0 }));
+}
+/**
+ * One page source, ready to be asked "is this selector shown".
+ *
+ * Rescue of inverted nodes. Cause, measured on a Galaxy S23 (TapIn live room): when the keyboard opens the app translates the
+ * chat up. The accessibility bounds of the chat's nodes are still cut by the container's untranslated rect, whose top stays
+ * where it was (y 1083), so a node drawn on screen reports top 1083 and its real bottom (846, 948 ...): top below bottom and
+ * `displayed=false`, and the scroll container that holds them is inverted too. Nodes the real clip hides (the list scrolled
+ * past them) all report the same bottom, the clip's own edge (y 201 there). So, per scroll container that is itself inverted,
+ * a node inside it that is inverted counts as shown when its real bottom is on screen and below that edge. Outside such a
+ * container (a normal list, a node at opacity 0, the keyboard's own views) an inverted or hidden node never counts.
+ */
+export class Screen {
+    nodes;
+    window;
+    /** Per scroll container (a node index) that is inverted: the bottom edge the clipped-away nodes collapse onto. */
+    edges = new Map();
+    container;
+    constructor(nodes, window) {
+        this.nodes = nodes;
+        this.window = window;
+        this.container = nodes.map((_, i) => this.scrollAncestor(i));
+        const byContainer = new Map();
+        nodes.forEach((n, i) => {
+            const c = this.container[i];
+            if (c >= 0 && inverted(nodes[c]) && inverted(n))
+                (byContainer.get(c) ?? byContainer.set(c, []).get(c)).push(i);
+        });
+        for (const [c, members] of byContainer) {
+            const edge = this.clipEdge(members);
+            if (edge !== null)
+                this.edges.set(c, edge);
+        }
+    }
+    scrollAncestor(i) {
+        let p = this.nodes[i].parent;
+        while (p >= 0 && !this.nodes[p].scrollable)
+            p = this.nodes[p].parent;
+        return p;
+    }
+    /**
+     * The bottom shared by the most clipped-away subtrees of one container, or null. A subtree is counted once, by its head: a
+     * node whose parent does not have the same bottom, so the nested nodes of one message are one, two clipped messages are
+     * two. The edge needs at least two subtrees; with fewer than two clipped messages there is none and nothing is rescued
+     * (the step then fails loudly). On a tie the larger bottom wins, which shows fewer nodes.
+     */
+    clipEdge(members) {
+        const heads = new Map();
+        for (const i of members) {
+            const n = this.nodes[i];
+            const parent = this.nodes[n.parent];
+            if (parent && inverted(parent) && parent.bottom === n.bottom)
+                continue;
+            heads.set(n.bottom, (heads.get(n.bottom) ?? 0) + 1);
+        }
+        let edge = null;
+        let most = 1;
+        for (const [bottom, count] of heads) {
+            if (count > most || (count === most && edge !== null && bottom > edge)) {
+                edge = bottom;
+                most = count;
+            }
+        }
+        return edge;
+    }
+    nodeShown(i, full) {
+        const n = this.nodes[i];
+        if (!inverted(n))
+            return nodeShown(n, this.window, full);
+        const edge = this.edges.get(this.container[i]);
+        if (full || edge === undefined)
+            return false;
+        return n.bottom > edge && n.bottom <= this.window.height && n.right > n.left && n.left < this.window.width && n.right > 0;
+    }
+    /** The indexes of the nodes that match and are on screen, inside the shown parent when `childOf` is given, or null when the selector cannot be answered from a source. */
+    shown(sel, full = false) {
+        let inside;
+        if (sel.childOf !== undefined) {
+            const parent = this.shown({ id: sel.childOf });
+            if (parent === null)
+                return null;
+            if (parent.length === 0)
+                return [];
+            inside = parent[0];
+        }
+        const match = nodeMatcher({ ...(sel.id !== undefined ? { id: sel.id } : {}), ...(sel.text !== undefined ? { text: sel.text } : {}) });
+        if (!match)
+            return null;
+        const hits = [];
+        this.nodes.forEach((n, i) => {
+            if (!match(n) || !this.nodeShown(i, full))
+                return;
+            if (inside !== undefined && !this.within(i, inside))
+                return;
+            hits.push(i);
+        });
+        return hits;
+    }
+    within(i, ancestor) {
+        for (let p = this.nodes[i].parent; p >= 0; p = this.nodes[p].parent)
+            if (p === ancestor)
+                return true;
+        return false;
+    }
+}
+//# sourceMappingURL=snapshot.js.map

package/dist/src/snapshot.js.map

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

package/dist/src/tokens.d.ts

@@ -0,0 +1,14 @@
+/** tokens.js from `perflab farm open`: plain assignments on `output`, read without evaluating the file. */
+export declare function parseTokensJs(text: string): {
+    api: string;
+    tokens: Record<string, string[]>;
+};
+export interface PlannedRun {
+    journey: string;
+    iteration: number;
+    token: string;
+}
+/** Iteration-major, journeys in the given order inside each: the order `farm open` numbers its runs in. */
+export declare function plan(journeys: readonly string[], repeat: number, tokens: Record<string, string[]>): PlannedRun[];
+/** Page-object files that each assign onto `output.elements` (the shape a Maestro suite already uses), evaluated in a sandbox. */
+export declare function loadElements(dir: string, names: readonly string[]): Record<string, any>;

package/dist/src/tokens.js

@@ -0,0 +1,28 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runInNewContext } from 'node:vm';
+/** tokens.js from `perflab farm open`: plain assignments on `output`, read without evaluating the file. */
+export function parseTokensJs(text) {
+    const pick = (name) => {
+        const m = text.match(new RegExp(`output\\.${name}\\s*=\\s*(.+);\\s*$`, 'm'));
+        return m ? JSON.parse(m[1]) : undefined;
+    };
+    return { api: pick('perflabApi') ?? '', tokens: pick('perflabTokens') ?? {} };
+}
+/** Iteration-major, journeys in the given order inside each: the order `farm open` numbers its runs in. */
+export function plan(journeys, repeat, tokens) {
+    const out = [];
+    for (let i = 0; i < repeat; i++) {
+        for (const journey of journeys)
+            out.push({ journey, iteration: i + 1, token: tokens[journey]?.[i] ?? '' });
+    }
+    return out;
+}
+/** Page-object files that each assign onto `output.elements` (the shape a Maestro suite already uses), evaluated in a sandbox. */
+export function loadElements(dir, names) {
+    const output = {};
+    for (const name of names)
+        runInNewContext(readFileSync(join(dir, `${name}.js`), 'utf8'), { output });
+    return output.elements ?? {};
+}
+//# sourceMappingURL=tokens.js.map

package/dist/src/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,2GAA2G;AAC3G,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,IAAI,GAAG,CAAC,IAAY,EAAW,EAAE;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,YAAY,IAAI,qBAAqB,EAAE,GAAG,CAAC,CAAC,CAAC;QAC7E,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3C,CAAC,CAAC;IACF,OAAO,EAAE,GAAG,EAAG,IAAI,CAAC,YAAY,CAAwB,IAAI,EAAE,EAAE,MAAM,EAAG,IAAI,CAAC,eAAe,CAA0C,IAAI,EAAE,EAAE,CAAC;AAClJ,CAAC;AAQD,2GAA2G;AAC3G,MAAM,UAAU,IAAI,CAAC,QAA2B,EAAE,MAAc,EAAE,MAAgC;IAChG,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,KAAK,MAAM,OAAO,IAAI,QAAQ;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,kIAAkI;AAClI,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,KAAwB;IAChE,MAAM,MAAM,GAAuC,EAAE,CAAC;IACtD,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,eAAe,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,KAAK,CAAC,EAAE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;IACrG,OAAO,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;AAC/B,CAAC"}

package/dist/src/version.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The driver's version as a run's setup records it (REQ-VER-35): the package's own `version`, read from the package.json that sits
+ * above this file (`dist/src/version.js` in a published or built package, `src/version.ts` in the checkout). A bundle that has no
+ * package.json next to it (the agent CLI, `bun build`) is given the version at build time by `PERFLAB_DRIVER_VERSION`
+ * (scripts/release/stage.ts). Null when neither is known: the run then records no driver version (unknown, never a made-up one).
+ */
+export declare function driverVersion(): string | null;
+/**
+ * The journey's version: a content hash (12 hex) of the journey module and of every module it imports by a relative path, in a
+ * stable order, so editing a page object or the module itself changes it and moving the checkout does not (REQ-VER-35). Line endings
+ * are normalised (CRLF = LF), file keys are paths relative to the module. Not followed: path aliases (`@/x`, tsconfig `paths`), package
+ * imports and non-literal imports; a change that only reaches the journey through them does not change the version.
+ */
+export declare function journeyVersion(modulePath: string): string;

package/dist/src/version.js

@@ -0,0 +1,69 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * The driver's version as a run's setup records it (REQ-VER-35): the package's own `version`, read from the package.json that sits
+ * above this file (`dist/src/version.js` in a published or built package, `src/version.ts` in the checkout). A bundle that has no
+ * package.json next to it (the agent CLI, `bun build`) is given the version at build time by `PERFLAB_DRIVER_VERSION`
+ * (scripts/release/stage.ts). Null when neither is known: the run then records no driver version (unknown, never a made-up one).
+ */
+export function driverVersion() {
+    const built = (process.env.KEEPSNAPPY_DRIVER_VERSION ?? process.env.PERFLAB_DRIVER_VERSION);
+    if (built)
+        return built;
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 3; i++, dir = dirname(dir)) {
+        const file = join(dir, 'package.json');
+        if (!existsSync(file))
+            continue;
+        try {
+            const pkg = JSON.parse(readFileSync(file, 'utf8'));
+            if ((pkg.name === '@keepsnappy/appium-driver' || pkg.name === '@perf-labs/appium-driver') && pkg.version)
+                return pkg.version;
+        }
+        catch {
+            /* not the package file: look one level up */
+        }
+    }
+    return null;
+}
+const RELATIVE_IMPORT = /(?:from\s*|import\s*\(\s*|import\s+|require\s*\(\s*)['"](\.{1,2}\/[^'"]+)['"]/g;
+const EXTENSIONS = ['', '.ts', '.mjs', '.js', '/index.ts', '/index.mjs', '/index.js'];
+function resolveImport(from, spec) {
+    const base = resolve(dirname(from), spec);
+    for (const ext of EXTENSIONS) {
+        const p = base + ext;
+        if (existsSync(p) && statSync(p).isFile())
+            return p;
+    }
+    return null;
+}
+/**
+ * The journey's version: a content hash (12 hex) of the journey module and of every module it imports by a relative path, in a
+ * stable order, so editing a page object or the module itself changes it and moving the checkout does not (REQ-VER-35). Line endings
+ * are normalised (CRLF = LF), file keys are paths relative to the module. Not followed: path aliases (`@/x`, tsconfig `paths`), package
+ * imports and non-literal imports; a change that only reaches the journey through them does not change the version.
+ */
+export function journeyVersion(modulePath) {
+    const seen = new Map();
+    const visit = (file) => {
+        if (seen.has(file))
+            return;
+        const text = readFileSync(file, 'utf8').replace(/\r\n?/g, '\n');
+        seen.set(file, text);
+        for (const m of text.matchAll(RELATIVE_IMPORT)) {
+            const dep = resolveImport(file, m[1]);
+            if (dep)
+                visit(dep);
+        }
+    };
+    const root = resolve(modulePath);
+    visit(root);
+    const keyed = [...seen].map(([file, text]) => [file === root ? '<module>' : relative(dirname(root), file).split('\\').join('/'), text]);
+    const hash = createHash('sha256');
+    for (const [key, text] of keyed.sort((a, b) => (a[0] < b[0] ? -1 : 1)))
+        hash.update(key).update('\0').update(text).update('\0');
+    return hash.digest('hex').slice(0, 12);
+}
+//# sourceMappingURL=version.js.map

package/dist/src/version.js.map

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

package/dist/src/webdriver.d.ts

@@ -0,0 +1,83 @@
+import { type Platform } from './platform.js';
+import { type Selector } from './selectors.js';
+export type FetchLike = (url: string, init?: any) => Promise<Response>;
+export interface CommandLogEntry {
+    cmd: string;
+    t: number;
+    ms: number;
+    status: number;
+    [k: string]: unknown;
+}
+export declare const realSleep: (ms: number) => Promise<void>;
+export declare class WdError extends Error {
+    readonly wdError: string;
+    constructor(message: string, wdError: string);
+}
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface DriverOptions {
+    hub: string;
+    fetch?: FetchLike;
+    log: CommandLogEntry[];
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    headers?: Record<string, string>;
+    bundleId: string;
+    /** Default iOS. */
+    platform?: Platform;
+}
+/** A minimal W3C WebDriver client that times every command, sent to returned. */
+export declare class Driver {
+    readonly bundleId: string;
+    readonly platform: Platform;
+    readonly headers: Record<string, string>;
+    readonly hub: string;
+    readonly fetch: FetchLike;
+    readonly log: CommandLogEntry[];
+    readonly now: () => number;
+    readonly sleep: (ms: number) => Promise<void>;
+    sessionId: string | null;
+    context: Record<string, unknown>;
+    private viewport;
+    private readonly rects;
+    constructor(o: DriverOptions);
+    cmd(method: string, path: string, body?: unknown): Promise<any>;
+    start(capabilities: Record<string, unknown>): Promise<any>;
+    execute(script: string, arg?: unknown): Promise<any>;
+    /** The first match, inside `parent` when given, or null. */
+    find(using: string, value: string, parent?: string): Promise<string | null>;
+    findAll(using: string, value: string, parent?: string): Promise<string[]>;
+    screen(): Promise<Rect>;
+    /** On screen: in the tree with a frame that overlaps the window. `full` asks for the whole frame inside it. */
+    onScreen(el: string, full?: boolean): Promise<boolean>;
+    /** The first element the selector matches on screen, or null. */
+    findShown(sel: Selector, full?: boolean): Promise<string | null>;
+    /**
+     * For each selector, whether an element it matches is on screen: what `findShown` answers, one by one. With `group` the
+     * selectors that are only an id are asked together in one lookup (when the platform has one), then each match is told
+     * apart by its resource id; that costs one tree walk however many are missing, where one by one costs a walk for each.
+     */
+    shownMany(sels: readonly Selector[], group: boolean): Promise<boolean[]>;
+    click(el: string): Promise<void>;
+    /**
+     * A touch at the centre of the element's frame (inside the window), not WDA's element click, which looks for a
+     * hittable point and misses a full-screen container such as a video tile.
+     */
+    tapElement(el: string): Promise<void>;
+    /** One finger from to to over durationMs, in window points. */
+    drag(from: {
+        x: number;
+        y: number;
+    }, to: {
+        x: number;
+        y: number;
+    }, durationMs: number): Promise<void>;
+    /** Stop, then start, so the process is a fresh one. */
+    relaunch(bundleId?: string): Promise<void>;
+    activate(bundleId?: string): Promise<any>;
+    end(): Promise<void>;
+}