@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,105 @@
+/**
+ * W3C capabilities for a UiAutomator2 session on one device. The app is installed and cleared
+ * by the runner (`noReset`, no `app` capability), so Appium never reinstalls or resets it itself.
+ */
+export function uiautomator2Capabilities(options) {
+    return {
+        platformName: 'Android',
+        'appium:automationName': 'UiAutomator2',
+        'appium:udid': options.serial,
+        'appium:systemPort': options.systemPort,
+        'appium:mjpegServerPort': options.mjpegServerPort,
+        'appium:appPackage': options.appPackage,
+        ...(options.appActivity ? { 'appium:appActivity': options.appActivity } : {}),
+        'appium:autoLaunch': false,
+        'appium:noReset': true,
+        'appium:dontStopAppOnReset': true,
+        'appium:autoGrantPermissions': true,
+        'appium:disableWindowAnimation': true,
+        'appium:skipUnlock': false,
+        'appium:newCommandTimeout': options.newCommandTimeoutSecs ?? 300,
+        'appium:uiautomator2ServerLaunchTimeout': 120_000,
+        'appium:uiautomator2ServerInstallTimeout': 120_000,
+        'appium:adbExecTimeout': 60_000,
+        'appium:androidInstallTimeout': 180_000,
+    };
+}
+/**
+ * W3C capabilities for an XCUITest session on one simulator or device. No `app` or `bundleId`:
+ * the runner installs and launches the app itself, so Appium never resets it on its own.
+ */
+export function xcuitestCapabilities(options) {
+    return {
+        platformName: 'iOS',
+        'appium:automationName': 'XCUITest',
+        'appium:udid': options.udid,
+        ...(options.platformVersion ? { 'appium:platformVersion': options.platformVersion } : {}),
+        'appium:wdaLocalPort': options.wdaLocalPort,
+        'appium:mjpegServerPort': options.mjpegServerPort,
+        'appium:derivedDataPath': options.derivedDataPath,
+        'appium:usePrebuiltWDA': options.usePrebuiltWDA,
+        'appium:noReset': true,
+        'appium:autoLaunch': false,
+        'appium:newCommandTimeout': options.newCommandTimeoutSecs ?? 300,
+        'appium:wdaLaunchTimeout': 240_000,
+        'appium:wdaConnectionTimeout': 240_000,
+        'appium:wdaStartupRetries': 2,
+        'appium:simulatorStartupTimeout': options.simulatorStartupTimeoutMs ?? 300_000,
+        'appium:appPushTimeout': 300_000,
+        'appium:reduceMotion': true,
+        'appium:connectHardwareKeyboard': false,
+        'appium:showXcodeLog': false,
+        ...(options.simulator
+            ? { 'appium:isHeadless': options.isHeadless ?? true }
+            : {
+                ...(options.teamId ? { 'appium:xcodeOrgId': options.teamId } : {}),
+                'appium:xcodeSigningId': options.signingId || 'Apple Development',
+                ...(options.wdaBundleId ? { 'appium:updatedWDABundleId': options.wdaBundleId } : {}),
+            }),
+    };
+}
+/** Opens a WebDriver session against a local Appium server. */
+export async function openSession(serverUrl, capabilities, connectionRetryTimeoutMs = 240_000) {
+    const url = new URL(serverUrl);
+    // Loaded lazily: web-only runners never pay for the WebDriver client.
+    const { default: WebDriver } = await import('webdriver');
+    await quietWdioLogs();
+    const client = await WebDriver.newSession({
+        protocol: url.protocol.replace(':', ''),
+        hostname: url.hostname,
+        port: Number(url.port),
+        path: '/',
+        logLevel: 'silent',
+        connectionRetryTimeout: connectionRetryTimeoutMs,
+        connectionRetryCount: 0,
+        capabilities: { alwaysMatch: capabilities, firstMatch: [{}] },
+    });
+    return client;
+}
+let quieted = false;
+/** The WebDriver client logs to stdout through @wdio/logger (a dependency of `webdriver`); keep the runner's output clean. */
+async function quietWdioLogs() {
+    if (quieted)
+        return;
+    quieted = true;
+    try {
+        const specifier = '@wdio/logger';
+        const { default: logger } = (await import(specifier));
+        for (const name of ['webdriver', '@wdio/utils', '@wdio/config'])
+            logger.setLevel(name, 'silent');
+    }
+    catch {
+        // not fatal: only log noise
+    }
+}
+/** Runs an Appium `mobile:` extension command. */
+export function mobile(client, command, args = {}) {
+    if (!/^[a-zA-Z]+$/.test(command))
+        throw new Error(`invalid mobile command '${command}'`);
+    return client.executeScript(`mobile: ${command}`, [args]);
+}
+/** WebDriver errors carry the Appium message after a prefix; keep the useful first line. */
+export function webdriverMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.split('\n')[0].replace(/^WebDriverError:\s*/, '').slice(0, 500);
+}

package/dist/src/drivers/webdriver/xml-tree-desktop.js

@@ -0,0 +1,425 @@
+import { clampDepth, clampMaxChars, clipText, renderSnapshotText, SNAPSHOT_LIMITS, } from '../snapshot/format.js';
+import { MAC_ROLE_BY_TYPE, WINDOWS_CONTROL_TYPES } from './native-locate.js';
+import { parsePageSource, suggestionFor } from './xml-tree.js';
+function num(value) {
+    if (value === undefined || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.round(n) : null;
+}
+function boundsOf(element) {
+    const x = num(element.attrs.x);
+    const y = num(element.attrs.y);
+    const width = num(element.attrs.width);
+    const height = num(element.attrs.height);
+    if (x === null || y === null || width === null || height === null)
+        return null;
+    return { x, y, width, height };
+}
+function add(map, key, element) {
+    if (!key)
+        return;
+    const list = map.get(key);
+    if (list) {
+        if (list.at(-1) !== element)
+            list.push(element);
+    }
+    else
+        map.set(key, [element]);
+}
+function withNth(target, list, element) {
+    if (!list || list.length <= 1)
+        return target;
+    return { ...target, nth: list.indexOf(element) };
+}
+function build(tree, rules, options, rootName) {
+    const depthLimit = clampDepth(options.depth);
+    const maxNodes = Math.min(options.maxNodes ?? SNAPSHOT_LIMITS.nodes, SNAPSHOT_LIMITS.nodes);
+    let next = options.firstRef ?? 1;
+    let emitted = 0;
+    let truncated = false;
+    const refs = {};
+    const rootBounds = boundsOf(tree.root);
+    const root = { ref: 'e0', role: 'screen', ...(rootName ? { name: clipText(rootName) } : {}) };
+    if (rootBounds)
+        root.bounds = rootBounds;
+    const convert = (element, depth, parent, context) => {
+        const bounds = boundsOf(element);
+        const hidden = rules.hidden(element, bounds);
+        if (hidden && !options.includeHidden)
+            return;
+        const role = rules.role(element);
+        const name = rules.name(element);
+        // A text inside a control that says the same thing adds nothing.
+        const redundant = role === 'text' && name !== '' && name === context && !rules.id(element);
+        if (rules.layoutOnly(element) || redundant) {
+            for (const child of element.children)
+                convert(child, depth, parent, context);
+            return;
+        }
+        if (emitted >= maxNodes || depth > depthLimit) {
+            truncated = true;
+            return;
+        }
+        emitted += 1;
+        const ref = `e${next}`;
+        next += 1;
+        const node = { ref, role };
+        if (name)
+            node.name = clipText(name);
+        const value = rules.value(element, name);
+        if (value)
+            node.text = clipText(value);
+        const id = rules.id(element);
+        if (id)
+            node.ids = { accessibility_id: id };
+        if (bounds)
+            node.bounds = bounds;
+        const state = rules.state(element);
+        if (hidden)
+            state.push('hidden');
+        if (state.length > 0)
+            node.state = state;
+        const { suggest, alternatives, fragile } = suggestionFor(rules.candidates(element));
+        refs[ref] = { locate: { ...rules.locate(element), ...(bounds ? { bounds } : {}) }, suggest, alternatives, fragile, bounds: bounds ?? null };
+        (parent.children ??= []).push(node);
+        for (const child of element.children)
+            convert(child, depth + 1, node, name || context);
+    };
+    for (const child of tree.root.children)
+        convert(child, 1, root, '');
+    const rendered = renderSnapshotText(root, clampMaxChars(options.maxChars));
+    for (const ref of Object.keys(refs)) {
+        if (!rendered.refs.has(ref))
+            delete refs[ref];
+    }
+    return {
+        root,
+        text: rendered.text,
+        refs,
+        element_count: emitted,
+        truncated: truncated || rendered.truncated,
+        width: rootBounds?.width ?? null,
+        height: rootBounds?.height ?? null,
+        rotation: null,
+        appName: rootName,
+    };
+}
+// ---------------------------------------------------------------------------------------------
+// macOS
+// ---------------------------------------------------------------------------------------------
+const MAC_PREFIX = 'XCUIElementType';
+export function macTypeOf(element) {
+    return element.tag.startsWith(MAC_PREFIX) ? element.tag.slice(MAC_PREFIX.length) : element.tag;
+}
+/** XCUIElementType (without prefix) → snapshot role. Types not listed are `group`. */
+export const MAC_SNAPSHOT_ROLES = {
+    Button: 'button',
+    ToolbarButton: 'button',
+    MenuButton: 'button',
+    DisclosureTriangle: 'button',
+    PopUpButton: 'popupbutton',
+    ComboBox: 'combobox',
+    CheckBox: 'checkbox',
+    Switch: 'switch',
+    Toggle: 'switch',
+    RadioButton: 'radio',
+    RadioGroup: 'radiogroup',
+    TextField: 'textfield',
+    SecureTextField: 'textfield',
+    SearchField: 'search',
+    TextView: 'textfield',
+    StaticText: 'text',
+    Link: 'link',
+    Image: 'image',
+    Icon: 'image',
+    Window: 'window',
+    Sheet: 'dialog',
+    Dialog: 'dialog',
+    Alert: 'alert',
+    Popover: 'dialog',
+    MenuBar: 'menubar',
+    MenuBarItem: 'menuitem',
+    Menu: 'menu',
+    MenuItem: 'menuitem',
+    Toolbar: 'toolbar',
+    TabGroup: 'tablist',
+    Tab: 'tab',
+    SegmentedControl: 'tablist',
+    Table: 'table',
+    Outline: 'tree',
+    TableRow: 'row',
+    OutlineRow: 'row',
+    Cell: 'cell',
+    CollectionView: 'list',
+    Browser: 'list',
+    Slider: 'slider',
+    Stepper: 'stepper',
+    IncrementArrow: 'button',
+    DecrementArrow: 'button',
+    ProgressIndicator: 'progressbar',
+    ActivityIndicator: 'progressbar',
+    LevelIndicator: 'progressbar',
+    DatePicker: 'picker',
+    ColorWell: 'button',
+    ScrollView: 'scrollview',
+    ScrollBar: 'scrollbar',
+    WebView: 'webview',
+    SplitGroup: 'group',
+    Splitter: 'separator',
+    Group: 'group',
+    Other: 'group',
+};
+export function macRoleFor(element) {
+    return MAC_SNAPSHOT_ROLES[macTypeOf(element)] ?? 'group';
+}
+const MAC_TOGGLES = ['CheckBox', 'Switch', 'Toggle', 'RadioButton'];
+const MAC_TEXT_INPUTS = ['TextField', 'SecureTextField', 'SearchField', 'TextView', 'ComboBox'];
+function macName(element) {
+    const a = element.attrs;
+    if (a.title)
+        return a.title;
+    if (a.label)
+        return a.label;
+    const type = macTypeOf(element);
+    if (type === 'StaticText' && a.value)
+        return a.value;
+    if (MAC_TEXT_INPUTS.includes(type) && a.placeholderValue)
+        return a.placeholderValue;
+    return '';
+}
+function macValue(element, name) {
+    const type = macTypeOf(element);
+    const value = element.attrs.value ?? '';
+    if (!value || value === name || type === 'SecureTextField' || MAC_TOGGLES.includes(type))
+        return '';
+    if (['Slider', 'ProgressIndicator', 'LevelIndicator', 'ScrollBar', 'ValueIndicator', 'Splitter'].includes(type))
+        return '';
+    return value;
+}
+function macState(element) {
+    const a = element.attrs;
+    const type = macTypeOf(element);
+    const state = [];
+    if (MAC_TOGGLES.includes(type))
+        state.push(a.value === '1' || a.value === 'true' ? 'checked' : 'unchecked');
+    if (a.enabled === 'false')
+        state.push('disabled');
+    if (a.selected === 'true')
+        state.push('selected');
+    if (type === 'SecureTextField')
+        state.push('password');
+    return state;
+}
+function macLayoutOnly(element) {
+    const type = macTypeOf(element);
+    const a = element.attrs;
+    if (!['Group', 'Other', 'SplitGroup', 'ScrollView', 'LayoutArea', 'LayoutItem', 'Matte', 'Unknown'].includes(type))
+        return false;
+    return !a.identifier && !a.title && !a.label && !a.value;
+}
+const GENERATED_IDENTIFIER = /^_NS:\d+$/;
+/** An XCUIElementType the class chain can name (`**\/XCUIElementTypeButton[3]`, 1-based). */
+function macClassChain(element, position) {
+    return `**/${element.tag}[${position + 1}]`;
+}
+/**
+ * macOS page source → snapshot. Zero-sized elements (items of closed menus, collapsed views)
+ * are hidden unless `includeHidden`. Every element counts for `nth`: Mac2 queries return
+ * hidden elements too.
+ */
+export function macSnapshotFromXml(xml, options = {}) {
+    const tree = parsePageSource(xml);
+    const identifiers = new Map();
+    const titles = new Map();
+    const types = new Map();
+    for (const element of tree.all) {
+        add(identifiers, element.attrs.identifier, element);
+        // `title` matches title or label.
+        add(titles, element.attrs.title, element);
+        if (element.attrs.label !== element.attrs.title)
+            add(titles, element.attrs.label, element);
+        add(types, element.tag, element);
+    }
+    const rules = {
+        role: macRoleFor,
+        name: macName,
+        value: macValue,
+        id: (element) => element.attrs.identifier ?? '',
+        state: macState,
+        hidden: (_element, bounds) => bounds !== null && (bounds.width <= 0 || bounds.height <= 0),
+        layoutOnly: macLayoutOnly,
+        candidates: (element) => {
+            const out = [];
+            const a = element.attrs;
+            // `_NS:34`-style identifiers are generated by Interface Builder and change between builds.
+            if (a.identifier && !GENERATED_IDENTIFIER.test(a.identifier) && a.identifier.length <= 2000) {
+                const list = identifiers.get(a.identifier);
+                out.push({ target: withNth({ identifier: a.identifier }, list, element), fragile: (list?.length ?? 0) > 1 });
+            }
+            const title = a.title || a.label;
+            if (title && title.length <= 2000) {
+                const list = titles.get(title);
+                out.push({ target: withNth({ title }, list, element), fragile: (list?.length ?? 0) > 1 });
+            }
+            const list = types.get(element.tag) ?? [];
+            const position = list.indexOf(element);
+            const role = MAC_ROLE_BY_TYPE[macTypeOf(element)];
+            if (role && position >= 0)
+                out.push({ target: list.length > 1 ? { role, nth: position } : { role }, fragile: list.length > 1 });
+            if (position >= 0)
+                out.push({ target: { class_chain: macClassChain(element, position) }, fragile: true });
+            return out;
+        },
+        locate: (element) => {
+            const position = (types.get(element.tag) ?? []).indexOf(element);
+            return { class_chain: macClassChain(element, Math.max(0, position)), type: element.tag };
+        },
+    };
+    const app = tree.root;
+    const name = app.attrs.title || app.attrs.label || null;
+    return build(tree, rules, options, name);
+}
+// ---------------------------------------------------------------------------------------------
+// Windows
+// ---------------------------------------------------------------------------------------------
+/** UIA control type → snapshot role. Types not listed are `group`. */
+export const WINDOWS_SNAPSHOT_ROLES = {
+    Button: 'button',
+    SplitButton: 'button',
+    Edit: 'textfield',
+    Document: 'document',
+    Text: 'text',
+    CheckBox: 'checkbox',
+    RadioButton: 'radio',
+    ComboBox: 'combobox',
+    List: 'list',
+    ListItem: 'listitem',
+    Menu: 'menu',
+    MenuBar: 'menubar',
+    MenuItem: 'menuitem',
+    Tab: 'tablist',
+    TabItem: 'tab',
+    Tree: 'tree',
+    TreeItem: 'treeitem',
+    Window: 'window',
+    TitleBar: 'titlebar',
+    Hyperlink: 'link',
+    Image: 'image',
+    Slider: 'slider',
+    Spinner: 'spinbutton',
+    ToolBar: 'toolbar',
+    StatusBar: 'statusbar',
+    ScrollBar: 'scrollbar',
+    ProgressBar: 'progressbar',
+    DataGrid: 'grid',
+    DataItem: 'row',
+    Table: 'table',
+    Header: 'header',
+    HeaderItem: 'columnheader',
+    ToolTip: 'tooltip',
+    Separator: 'separator',
+    Calendar: 'grid',
+    AppBar: 'toolbar',
+    Pane: 'group',
+    Group: 'group',
+    Custom: 'group',
+    Thumb: 'group',
+};
+export function windowsRoleFor(element) {
+    return WINDOWS_SNAPSHOT_ROLES[element.tag] ?? 'group';
+}
+function isTrueish(value) {
+    return value?.toLowerCase() === 'true';
+}
+function windowsChecked(element) {
+    const a = element.attrs;
+    const toggle = a['Toggle.ToggleState'] ?? a.ToggleState;
+    if (toggle !== undefined)
+        return toggle === '1' || toggle.toLowerCase() === 'on';
+    const selected = a['SelectionItem.IsSelected'];
+    if (selected !== undefined && element.tag === 'RadioButton')
+        return isTrueish(selected);
+    return null;
+}
+function windowsState(element) {
+    const a = element.attrs;
+    const state = [];
+    if (element.tag === 'CheckBox' || element.tag === 'RadioButton') {
+        const checked = windowsChecked(element);
+        if (checked !== null)
+            state.push(checked ? 'checked' : 'unchecked');
+    }
+    if (a.IsEnabled !== undefined && !isTrueish(a.IsEnabled))
+        state.push('disabled');
+    if (isTrueish(a.HasKeyboardFocus))
+        state.push('focused');
+    if (isTrueish(a['SelectionItem.IsSelected']) && element.tag !== 'RadioButton')
+        state.push('selected');
+    if (isTrueish(a.IsPassword))
+        state.push('password');
+    return state;
+}
+function windowsValue(element, name) {
+    const a = element.attrs;
+    if (isTrueish(a.IsPassword))
+        return '';
+    const value = a['Value.Value'] ?? '';
+    return value && value !== name ? value : '';
+}
+function windowsLayoutOnly(element) {
+    const a = element.attrs;
+    if (!['Pane', 'Custom', 'Group', 'Thumb'].includes(element.tag))
+        return false;
+    return !a.Name && !a.AutomationId && !isTrueish(a.IsKeyboardFocusable);
+}
+/**
+ * Windows page source → snapshot. `IsOffscreen="True"` elements are hidden unless
+ * `includeHidden`; every element counts for `nth` (WinAppDriver finds off-screen ones too).
+ */
+export function windowsSnapshotFromXml(xml, options = {}) {
+    const tree = parsePageSource(xml);
+    const automationIds = new Map();
+    const names = new Map();
+    const types = new Map();
+    // The top-level window is part of the searchable tree (`//Window` matches it).
+    for (const element of [tree.root, ...tree.all]) {
+        add(automationIds, element.attrs.AutomationId, element);
+        add(names, element.attrs.Name, element);
+        add(types, element.tag, element);
+    }
+    const rules = {
+        role: windowsRoleFor,
+        // A password box's Name is its label; UI Automation never exposes the typed value there.
+        name: (element) => element.attrs.Name ?? '',
+        value: windowsValue,
+        id: (element) => element.attrs.AutomationId ?? '',
+        state: windowsState,
+        hidden: (element, bounds) => isTrueish(element.attrs.IsOffscreen) || (bounds !== null && (bounds.width <= 0 || bounds.height <= 0)),
+        layoutOnly: windowsLayoutOnly,
+        candidates: (element) => {
+            const out = [];
+            const a = element.attrs;
+            if (a.AutomationId && a.AutomationId.length <= 2000) {
+                const list = automationIds.get(a.AutomationId);
+                out.push({ target: withNth({ automation_id: a.AutomationId }, list, element), fragile: (list?.length ?? 0) > 1 });
+            }
+            if (a.Name && a.Name.length <= 2000) {
+                const list = names.get(a.Name);
+                out.push({ target: withNth({ name: a.Name }, list, element), fragile: (list?.length ?? 0) > 1 });
+            }
+            if (WINDOWS_CONTROL_TYPES.includes(element.tag)) {
+                const list = types.get(element.tag) ?? [];
+                const position = list.indexOf(element);
+                if (position >= 0) {
+                    out.push({ target: list.length > 1 ? { control_type: element.tag, nth: position } : { control_type: element.tag }, fragile: list.length > 1 });
+                }
+            }
+            if (element.xpath.length <= 500)
+                out.push({ target: { xpath: element.xpath }, fragile: true });
+            return out;
+        },
+        locate: (element) => ({ xpath: element.xpath, type: element.tag }),
+    };
+    return build(tree, rules, options, tree.root.attrs.Name || null);
+}