@leera.io/qa-runner 1.0.0

package/dist/src/drivers/webdriver/dom.js

@@ -0,0 +1,213 @@
+import { readFileSync } from 'node:fs';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Unsupported } from '../driver.js';
+import { elementIdOf } from './locate.js';
+/**
+ * Locators for WebDriver-backed web views (Tauri, contracts §L). Elements are found by the
+ * runner-owned `dom-locate.js`, executed with W3C `execute/sync`; no other script is ever run.
+ */
+export const DOM_LOCATORS = ['css', 'text', 'test_id', 'xpath'];
+export const MAX_XPATH_CHARS = 500;
+/** Elements one locate call returns (a `nth` beyond it is fetched on demand). */
+export const DOM_LOCATE_LIMIT = 50;
+const scripts = new Map();
+/** The file as shipped next to this module (copied into dist by the build). */
+export function domScriptSource(name) {
+    return readFileSync(new URL(`./${name}.js`, import.meta.url), 'utf8');
+}
+/** The `execute/sync` body for a runner-owned script: the file's function applied to the arguments. */
+export function domScript(name) {
+    let script = scripts.get(name);
+    if (!script) {
+        const source = domScriptSource(name)
+            .replace(/^\s*\/\*[\s\S]*?\*\/\s*/, '')
+            .trim();
+        if (!source.startsWith('(function') || !source.endsWith(')'))
+            throw new Error(`${name}.js is not a function expression`);
+        script = `return (${source}).apply(null, arguments);`;
+        scripts.set(name, script);
+    }
+    return script;
+}
+/** W3C web element reference for script arguments and actions. */
+export const ELEMENT_KEY = 'element-6066-11e4-a52e-4f735466cecf';
+export function elementRef(elementId) {
+    return { [ELEMENT_KEY]: elementId };
+}
+/** The locator key a target uses, after checking it is one tauri understands. */
+export function domLocatorKey(target, platform = 'tauri') {
+    const keys = Object.keys(target).filter((key) => !['exact', 'nth', 'fallbacks', 'locate'].includes(key) && target[key] !== undefined);
+    const foreign = keys.find((key) => !DOM_LOCATORS.includes(key));
+    if (foreign)
+        throw new Unsupported(`target.${foreign} is not a ${platform} locator; use css, text, test_id or xpath`);
+    if (keys.length !== 1)
+        throw new Unsupported('target needs exactly one of css, text, test_id, xpath');
+    const key = keys[0];
+    const value = target[key];
+    if (typeof value !== 'string' || value.length === 0)
+        throw new Unsupported(`target.${key} must be a non-empty string`);
+    if (key === 'xpath' && value.length > MAX_XPATH_CHARS)
+        throw new Unsupported(`target.xpath is longer than ${MAX_XPATH_CHARS} characters`);
+    if (target.nth !== undefined && (!Number.isInteger(target.nth) || target.nth < 0 || target.nth > 1_000)) {
+        throw new Unsupported('target.nth must be a whole number from 0 to 1000');
+    }
+    return key;
+}
+/** Checks a target and its fallbacks (≤5, not nested) before anything runs. */
+export function validateDomTarget(target, platform = 'tauri') {
+    domLocatorKey(target, platform);
+    const fallbacks = target.fallbacks ?? [];
+    if (!Array.isArray(fallbacks) || fallbacks.length > 5)
+        throw new Unsupported('target.fallbacks must be a list of at most 5 targets');
+    fallbacks.forEach((fallback, i) => {
+        if (fallback.fallbacks !== undefined)
+            throw new Unsupported(`target.fallbacks[${i}] cannot have fallbacks`);
+        try {
+            domLocatorKey(fallback, platform);
+        }
+        catch (error) {
+            throw new Unsupported(error.message.replace(/^target\./, `target.fallbacks[${i}].`));
+        }
+    });
+}
+/** The request `dom-locate.js` takes for one target (placeholders rendered). */
+export function domLocateRequest(target, render = (t) => t, limit = DOM_LOCATE_LIMIT) {
+    const key = domLocatorKey(target);
+    const value = render(target[key]);
+    const request = { [key]: value };
+    if (key === 'text' && target.exact !== undefined)
+        request.exact = target.exact;
+    return { target: request, limit: Math.max(1, Math.min(1_000, limit)) };
+}
+/** Parses what `dom-locate.js` returned. */
+export function parseDomMatches(raw) {
+    if (!raw || typeof raw !== 'object')
+        throw new Error('the locator script returned nothing');
+    const value = raw;
+    const elements = Array.isArray(value.elements) ? value.elements : [];
+    const visible = Array.isArray(value.visible) ? value.visible.map((v) => v === true) : [];
+    return {
+        count: typeof value.count === 'number' ? value.count : elements.length,
+        elementIds: elements.map(elementIdOf),
+        visible,
+    };
+}
+/** Candidates in order: the target itself, then its fallbacks. */
+export function domCandidates(target) {
+    const { fallbacks, locate: _locate, ...primary } = target;
+    return [primary, ...(fallbacks ?? []).map(({ fallbacks: _nested, locate: _l, ...rest }) => rest)];
+}
+/** All matches of one target (no fallbacks). */
+export async function domFindAll(client, target, render, limit) {
+    const raw = await client.executeScript(domScript('dom-locate'), [domLocateRequest(target, render, limit ?? Math.max(DOM_LOCATE_LIMIT, (target.nth ?? 0) + 1))]);
+    return parseDomMatches(raw);
+}
+/** One pass over the target and its fallbacks; null when nothing matches at `nth`. */
+export async function domLocateOnce(client, target, render) {
+    for (const candidate of domCandidates(target)) {
+        const found = await domFindAll(client, candidate, render);
+        const nth = candidate.nth ?? 0;
+        const elementId = found.elementIds[nth];
+        if (elementId)
+            return { elementId, target: candidate, count: found.count, visible: found.visible[nth] ?? false };
+    }
+    return null;
+}
+/** Polls until the target (or a fallback) matches (and is visible, when asked) or the time is up. */
+export async function domLocate(client, target, timeoutMs, options = {}) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = await domLocateOnce(client, target, options.render);
+        if (found && (!options.visible || found.visible))
+            return found;
+        if (Date.now() >= deadline)
+            return options.visible ? null : found;
+        await sleep(options.pollMs ?? 200);
+    }
+}
+export function describeDomTarget(target) {
+    if (target.test_id !== undefined)
+        return `test id "${target.test_id}"`;
+    if (target.text !== undefined)
+        return `text "${target.text}"`;
+    if (target.css !== undefined)
+        return `element "${target.css}"`;
+    if (target.xpath !== undefined)
+        return `xpath ${target.xpath}`;
+    return 'element';
+}
+/** W3C WebDriver key codes for named keys (Playwright-style names, case-insensitive). */
+const NAMED_KEYS = {
+    enter: '',
+    return: '',
+    tab: '',
+    escape: '',
+    esc: '',
+    backspace: '',
+    delete: '',
+    insert: '',
+    space: ' ',
+    arrowup: '',
+    arrowdown: '',
+    arrowleft: '',
+    arrowright: '',
+    up: '',
+    down: '',
+    left: '',
+    right: '',
+    home: '',
+    end: '',
+    pageup: '',
+    pagedown: '',
+    f1: '',
+    f2: '',
+    f3: '',
+    f4: '',
+    f5: '',
+    f6: '',
+    f7: '',
+    f8: '',
+    f9: '',
+    f10: '',
+    f11: '',
+    f12: '',
+};
+const MODIFIERS = {
+    shift: '',
+    control: '',
+    ctrl: '',
+    alt: '',
+    option: '',
+    meta: '',
+    cmd: '',
+    command: '',
+};
+/**
+ * A key or chord (`Enter`, `Control+A`, `ctrl+s`, `ControlOrMeta+V`) as WebDriver key values:
+ * modifiers first, then the key. Throws `Unsupported` for names it does not know.
+ */
+export function webdriverKeys(key, platform = process.platform) {
+    const parts = key.length > 1 && key.includes('+') ? key.split('+') : [key];
+    const last = parts.pop() ?? '';
+    const modifiers = parts.map((part) => {
+        const name = part.trim().toLowerCase();
+        if (name === 'controlormeta')
+            return platform === 'darwin' ? MODIFIERS.meta : MODIFIERS.control;
+        const code = MODIFIERS[name];
+        if (!code)
+            throw new Unsupported(`'${part}' is not a modifier key; use Shift, Control, Alt or Meta`);
+        return code;
+    });
+    if (last.length === 1)
+        return { modifiers, key: last };
+    const named = NAMED_KEYS[last.toLowerCase()] ?? MODIFIERS[last.toLowerCase()];
+    if (!named)
+        throw new Unsupported(`'${last}' is not a key this runner knows`);
+    return { modifiers, key: named };
+}
+/** A W3C key action sequence pressing and releasing a chord. */
+export function keyActions(keys) {
+    const down = [...keys.modifiers, keys.key].map((value) => ({ type: 'keyDown', value }));
+    const up = [keys.key, ...[...keys.modifiers].reverse()].map((value) => ({ type: 'keyUp', value }));
+    return [{ type: 'key', id: 'keyboard', actions: [...down, ...up] }];
+}

package/dist/src/drivers/webdriver/ios-actions.js

@@ -0,0 +1,299 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { clip, expectWithin, matches, verb } from '../common.js';
+import { NotFound, Unsupported } from '../driver.js';
+import { checkDeepLink, gestureArea, orientationValue, swipeDistance } from './actions.js';
+import { describeIosTarget, iosFindAll, iosLocate } from './ios-locate.js';
+import { elementIdOf } from './locate.js';
+import { mobile, webdriverMessage } from './session.js';
+/** Named ios keys (plan §3). There is no `back` key on iOS. */
+export const IOS_KEYS = ['home', 'return', 'delete', 'volume_up', 'volume_down'];
+/** How a key is pressed: a hardware button, or a character typed into the focused element. */
+export function iosKeyAction(key) {
+    switch (key.trim().toLowerCase()) {
+        case 'home':
+            return { kind: 'button', name: 'home' };
+        case 'volume_up':
+            return { kind: 'button', name: 'volumeup' };
+        case 'volume_down':
+            return { kind: 'button', name: 'volumedown' };
+        case 'return':
+        case 'enter':
+            return { kind: 'type', text: '\n' };
+        case 'delete':
+            return { kind: 'type', text: '\b' };
+        case 'back':
+            throw new Unsupported("iOS has no back key; tap the app's back button (for example its navigation bar button)");
+        default:
+            throw new Unsupported(`'${key}' is not an ios key; use ${IOS_KEYS.join(', ')}`);
+    }
+}
+export const IOS_ACTIONS = [
+    'launch',
+    'terminate',
+    'reset',
+    'deep_link',
+    'tap',
+    'double_tap',
+    'long_press',
+    'type',
+    'clear',
+    'press',
+    'swipe',
+    'scroll_to',
+    'set_orientation',
+    'accept_alert',
+    'dismiss_alert',
+    'wait',
+    'wait_for',
+    'screenshot',
+    'expect_visible',
+    'expect_hidden',
+    'expect_text',
+];
+function requireTarget(action) {
+    if (!action.target)
+        throw new Error(`'${action.type}' needs a target`);
+    return action.target;
+}
+async function element(ctx, target, timeoutMs) {
+    const found = await iosLocate(ctx.client, target, timeoutMs, ctx.render);
+    if (!found)
+        throw new NotFound(`${describeIosTarget(target)} was not found within ${Math.round(timeoutMs / 100) / 10} s`);
+    ctx.onLocated?.(found);
+    return found;
+}
+async function visibleCount(ctx, target) {
+    const ids = await iosFindAll(ctx.client, { ...target, fallbacks: undefined }, ctx.render);
+    const pool = target.nth === undefined ? ids : ids.slice(target.nth, target.nth + 1);
+    let count = 0;
+    for (const id of pool) {
+        if (await ctx.client.isElementDisplayed(id).catch(() => false))
+            count += 1;
+    }
+    return count;
+}
+/** The text an element shows: its label, else its value (XCUITest's element text is one of them). */
+export async function iosElementText(client, elementId) {
+    const label = await client.getElementAttribute(elementId, 'label').catch(() => null);
+    if (label?.trim())
+        return label.trim();
+    const value = await client.getElementAttribute(elementId, 'value').catch(() => null);
+    if (value?.trim())
+        return value.trim();
+    return ((await client.getElementText(elementId).catch(() => '')) ?? '').trim();
+}
+function checkDirection(direction, fallback) {
+    const value = (direction ?? fallback);
+    if (!['up', 'down', 'left', 'right'].includes(value))
+        throw new Error(`direction must be up, down, left or right, not '${direction}'`);
+    return value;
+}
+/** Start and end points of a swipe of `distance` (0.1–1) across `area`, the finger moving in `direction`. */
+export function swipePoints(area, direction, distance) {
+    const cx = area.left + area.width / 2;
+    const cy = area.top + area.height / 2;
+    const dx = (area.width * distance) / 2;
+    const dy = (area.height * distance) / 2;
+    const points = {
+        up: { fromX: cx, fromY: cy + dy, toX: cx, toY: cy - dy },
+        down: { fromX: cx, fromY: cy - dy, toX: cx, toY: cy + dy },
+        left: { fromX: cx + dx, fromY: cy, toX: cx - dx, toY: cy },
+        right: { fromX: cx - dx, fromY: cy, toX: cx + dx, toY: cy },
+    }[direction];
+    return { fromX: Math.round(points.fromX), fromY: Math.round(points.fromY), toX: Math.round(points.toX), toY: Math.round(points.toY) };
+}
+async function pressKey(ctx, key) {
+    const action = iosKeyAction(key);
+    if (action.kind === 'button') {
+        try {
+            await mobile(ctx.client, 'pressButton', { name: action.name });
+        }
+        catch (error) {
+            throw new Error(`the ${key} button could not be pressed: ${webdriverMessage(error)}`);
+        }
+        return;
+    }
+    if (!ctx.client.getActiveElement)
+        throw new Unsupported(`pressing ${key} is not available with this driver`);
+    let active;
+    try {
+        active = elementIdOf(await ctx.client.getActiveElement());
+    }
+    catch {
+        throw new Error(`nothing has keyboard focus to press ${key} in; tap a text field first`);
+    }
+    await ctx.client.elementSendKeys(active, action.text);
+}
+/** Performs one ios DSL action (or a session-only `home`). */
+export async function runIosAction(ctx, action) {
+    const timeout = action.timeout_ms ?? ctx.defaultTimeoutMs;
+    const { client, bundleId } = ctx;
+    switch (action.type) {
+        case 'launch':
+            if (action.activity)
+                throw new Unsupported('launch activities are an android feature; iOS launches the app by its bundle id');
+            await mobile(client, 'launchApp', { bundleId });
+            return {};
+        case 'terminate':
+            await mobile(client, 'terminateApp', { bundleId });
+            return {};
+        case 'reset':
+            await mobile(client, 'terminateApp', { bundleId });
+            if (!ctx.resetApp)
+                throw new Unsupported('reset is not available for this app');
+            await ctx.resetApp();
+            await mobile(client, 'launchApp', { bundleId });
+            return {};
+        case 'deep_link': {
+            const url = checkDeepLink(ctx.render(action.url ?? ''));
+            try {
+                await mobile(client, 'deepLink', { url, bundleId });
+            }
+            catch (error) {
+                throw new Error(`the deep link could not be opened: ${webdriverMessage(error)}`);
+            }
+            return {};
+        }
+        case 'tap': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await client.elementClick(found.elementId);
+            return {};
+        }
+        case 'double_tap': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await mobile(client, 'doubleTap', { elementId: found.elementId });
+            return {};
+        }
+        case 'long_press': {
+            const ms = action.ms ?? 1_000;
+            if (ms < 300 || ms > 10_000)
+                throw new Error('long_press ms must be between 300 and 10000');
+            const found = await element(ctx, requireTarget(action), timeout);
+            await mobile(client, 'touchAndHold', { elementId: found.elementId, duration: ms / 1_000 });
+            return {};
+        }
+        case 'type': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            if (action.clear)
+                await client.elementClear(found.elementId);
+            await client.elementSendKeys(found.elementId, ctx.render(action.value ?? ''));
+            return {};
+        }
+        case 'clear': {
+            const found = await element(ctx, requireTarget(action), timeout);
+            await client.elementClear(found.elementId);
+            return {};
+        }
+        case 'press':
+            await pressKey(ctx, action.key ?? '');
+            return {};
+        case 'home':
+            await pressKey(ctx, 'home');
+            return {};
+        case 'back':
+            iosKeyAction('back');
+            return {};
+        case 'hide_keyboard':
+            throw new Unsupported("'hide_keyboard' is not an ios action; use press {key: return}");
+        case 'swipe': {
+            const direction = checkDirection(action.direction, 'up');
+            const distance = swipeDistance(action.distance);
+            let area;
+            if (action.target) {
+                const found = await element(ctx, action.target, timeout);
+                const rect = await client.getElementRect(found.elementId);
+                area = { left: rect.x, top: rect.y, width: rect.width, height: rect.height };
+            }
+            else {
+                area = gestureArea(await client.getWindowRect());
+            }
+            await mobile(client, 'dragFromToWithVelocity', { ...swipePoints(area, direction, distance), pressDuration: 0.05, holdDuration: 0.05, velocity: 2_000 });
+            return {};
+        }
+        case 'scroll_to': {
+            const target = requireTarget(action);
+            const direction = checkDirection(action.direction, 'down');
+            const maxSwipes = action.max_swipes ?? 10;
+            if (!Number.isInteger(maxSwipes) || maxSwipes < 1 || maxSwipes > 20)
+                throw new Error('max_swipes must be 1-20');
+            // Scrolling down reveals what is below: the finger moves up.
+            const finger = { down: 'up', up: 'down', left: 'right', right: 'left' }[direction];
+            for (let swipe = 0;; swipe += 1) {
+                const found = await iosLocate(client, target, 500, ctx.render);
+                if (found && (await client.isElementDisplayed(found.elementId).catch(() => false))) {
+                    ctx.onLocated?.(found);
+                    return {};
+                }
+                if (swipe >= maxSwipes)
+                    break;
+                const area = gestureArea(await client.getWindowRect());
+                await mobile(client, 'dragFromToWithVelocity', { ...swipePoints(area, finger, 0.6), pressDuration: 0.05, holdDuration: 0.05, velocity: 1_500 });
+            }
+            throw new Error(`${describeIosTarget(target)} did not appear after scrolling ${direction} ${maxSwipes} times`);
+        }
+        case 'set_orientation':
+            await client.setOrientation(orientationValue(action.value));
+            return {};
+        case 'accept_alert':
+        case 'dismiss_alert': {
+            const deadline = Date.now() + timeout;
+            for (;;) {
+                try {
+                    if (action.type === 'accept_alert')
+                        await client.acceptAlert();
+                    else
+                        await client.dismissAlert();
+                    return {};
+                }
+                catch (error) {
+                    if (Date.now() >= deadline)
+                        throw new Error(`no alert was showing: ${webdriverMessage(error)}`);
+                    await sleep(300);
+                }
+            }
+        }
+        case 'wait':
+            await sleep(Math.min(Math.max(action.ms ?? 0, 0), 30_000));
+            return {};
+        case 'screenshot':
+            return { screenshot: Buffer.from(await client.takeScreenshot(), 'base64') };
+        case 'wait_for':
+        case 'expect_visible': {
+            const target = requireTarget(action);
+            await expectWithin(timeout, async () => {
+                const found = await iosLocate(client, target, 0, ctx.render);
+                if (!found)
+                    return false;
+                const shown = await client.isElementDisplayed(found.elementId).catch(() => false);
+                if (shown)
+                    ctx.onLocated?.(found);
+                return shown;
+            }, `${describeIosTarget(target)} to be visible`);
+            return {};
+        }
+        case 'expect_hidden': {
+            const target = requireTarget(action);
+            await expectWithin(timeout, async () => (await visibleCount(ctx, target)) === 0, `${describeIosTarget(target)} to be hidden`);
+            return {};
+        }
+        case 'expect_text': {
+            const target = requireTarget(action);
+            const expected = ctx.render(action.value ?? '');
+            let actual = '';
+            await expectWithin(timeout, async () => {
+                const found = await iosLocate(client, target, 0, ctx.render);
+                if (!found) {
+                    actual = '(not found)';
+                    return false;
+                }
+                actual = await iosElementText(client, found.elementId);
+                return matches(actual, expected, action.match);
+            }, () => `text of ${describeIosTarget(target)} to ${verb(action.match)} "${expected}", found "${clip(actual)}"`);
+            return {};
+        }
+        case 'goto':
+            throw new Unsupported(`'goto' is not an ios action; use deep_link`);
+        default:
+            throw new Unsupported(`'${action.type}' is not an ios action`);
+    }
+}

package/dist/src/drivers/webdriver/ios-locate.js

@@ -0,0 +1,121 @@
+import { setTimeout as sleep } from 'node:timers/promises';
+import { candidates, elementIdOf } from './locate.js';
+/** iOS locator keys (plan §3); exactly one is set on a target. */
+export const IOS_LOCATORS = ['id', 'label', 'text', 'test_id', 'type', 'predicate', 'class_chain', 'xpath'];
+/** DSL `type` values → XCUIElementType class names (plan §3). */
+export const IOS_TYPES = {
+    button: 'XCUIElementTypeButton',
+    textfield: 'XCUIElementTypeTextField',
+    securetextfield: 'XCUIElementTypeSecureTextField',
+    statictext: 'XCUIElementTypeStaticText',
+    cell: 'XCUIElementTypeCell',
+    switch: 'XCUIElementTypeSwitch',
+    image: 'XCUIElementTypeImage',
+    other: 'XCUIElementTypeOther',
+};
+/** `button` → `XCUIElementTypeButton`; a full `XCUIElementType…` name is accepted as is. */
+export function iosElementType(value) {
+    const lower = value.trim().toLowerCase();
+    const mapped = IOS_TYPES[lower];
+    if (mapped)
+        return mapped;
+    if (/^XCUIElementType[A-Za-z]+$/.test(value.trim()))
+        return value.trim();
+    throw new Error(`type '${value}' is not an iOS element type; use ${Object.keys(IOS_TYPES).join(', ')}`);
+}
+/** Quotes a string literal for an NSPredicate (double quotes, backslash escapes). */
+export function predicateString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * Maps one ios target (without fallbacks/nth) to the selectors to try, in order.
+ * `render` resolves `{{placeholders}}` in the value first.
+ *
+ * - `id` / `test_id` (React Native / Expo `testID`): the accessibility identifier.
+ * - `label`: the accessibility label, exact unless `exact: false` (then contains).
+ * - `text`: label or value containing the text, exact when `exact: true`.
+ * - `type`: an element type (`button`, `textfield`, …).
+ * - `predicate`, `class_chain`, `xpath`: used as they are.
+ */
+export function iosSelectors(target, render = (t) => t) {
+    if (target.id !== undefined)
+        return [{ using: 'accessibility id', value: render(target.id) }];
+    if (target.test_id !== undefined)
+        return [{ using: 'accessibility id', value: render(target.test_id) }];
+    if (target.label !== undefined) {
+        const label = predicateString(render(target.label));
+        return [{ using: '-ios predicate string', value: target.exact === false ? `label CONTAINS ${label}` : `label == ${label}` }];
+    }
+    if (target.text !== undefined) {
+        const text = predicateString(render(target.text));
+        const op = target.exact === true ? '==' : 'CONTAINS';
+        return [{ using: '-ios predicate string', value: `label ${op} ${text} OR value ${op} ${text}` }];
+    }
+    if (target.type !== undefined)
+        return [{ using: 'class name', value: iosElementType(render(target.type)) }];
+    if (target.predicate !== undefined)
+        return [{ using: '-ios predicate string', value: render(target.predicate).trim() }];
+    if (target.class_chain !== undefined)
+        return [{ using: '-ios class chain', value: render(target.class_chain).trim() }];
+    if (target.xpath !== undefined)
+        return [{ using: 'xpath', value: render(target.xpath) }];
+    const named = Object.keys(target).filter((key) => !['exact', 'nth', 'fallbacks', 'locate'].includes(key));
+    throw new Error(named.length > 0 ? `'${named[0]}' is not an ios locator; use one of ${IOS_LOCATORS.join(', ')}` : 'the target names no locator');
+}
+export function describeIosTarget(target) {
+    if (target.id !== undefined)
+        return `id "${target.id}"`;
+    if (target.test_id !== undefined)
+        return `test id "${target.test_id}"`;
+    if (target.label !== undefined)
+        return `element labelled "${target.label}"`;
+    if (target.text !== undefined)
+        return `text "${target.text}"`;
+    if (target.type !== undefined)
+        return `${target.type}`;
+    if (target.predicate !== undefined)
+        return `predicate ${target.predicate}`;
+    if (target.class_chain !== undefined)
+        return `class chain ${target.class_chain}`;
+    if (target.xpath !== undefined)
+        return `xpath ${target.xpath}`;
+    return 'element';
+}
+/** Elements matching one target (no fallbacks), in document order. */
+export async function iosFindAll(client, target, render) {
+    for (const selector of iosSelectors(target, render)) {
+        const found = await client.findElements(selector.using, selector.value).catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            // A malformed predicate, class chain or xpath is the script's problem, not a missing element.
+            if (/invalid selector|InvalidSelector|Unable to parse|parse the format|is not a valid/i.test(message) && !/no such element/i.test(message)) {
+                throw error;
+            }
+            return [];
+        });
+        if (found.length > 0)
+            return found.map(elementIdOf);
+    }
+    return [];
+}
+/** One pass over the target and its fallbacks; null when nothing matches (at `nth`). */
+export async function iosLocateOnce(client, target, render) {
+    for (const candidate of candidates(target)) {
+        const ids = await iosFindAll(client, candidate, render);
+        const nth = candidate.nth ?? 0;
+        if (ids.length > nth)
+            return { elementId: ids[nth], target: candidate, count: ids.length };
+    }
+    return null;
+}
+/** Polls until the target (or a fallback) matches or `timeoutMs` passes. */
+export async function iosLocate(client, target, timeoutMs, render, pollMs = 300) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const found = await iosLocateOnce(client, target, render);
+        if (found)
+            return found;
+        if (Date.now() >= deadline)
+            return null;
+        await sleep(pollMs);
+    }
+}