@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,314 @@
+import { clampDepth, clampMaxChars, clipText, renderSnapshotText, SNAPSHOT_LIMITS, } from '../snapshot/format.js';
+import { parsePageSource, suggestionFor } from './xml-tree.js';
+/**
+ * XCUITest page source (XML) → snapshot tree with refs.
+ *
+ * The source is `<AppiumAUT><XCUIElementTypeApplication …>`, one element per accessibility
+ * element; attributes are `type`, `name` (the accessibility identifier, or the label when there
+ * is none), `label`, `value`, `placeholderValue`, `enabled`, `visible`, `accessible`, `selected`,
+ * `x`/`y`/`width`/`height` in points.
+ */
+/** XCUIElementType (without the prefix) → role. Types not listed are `group`. */
+export const IOS_ROLE_BY_TYPE = {
+    Button: 'button',
+    Link: 'link',
+    Icon: 'button',
+    MenuButton: 'button',
+    PopUpButton: 'button',
+    TextField: 'textfield',
+    SecureTextField: 'textfield',
+    TextView: 'textfield',
+    SearchField: 'search',
+    StaticText: 'text',
+    Image: 'image',
+    Cell: 'cell',
+    Switch: 'switch',
+    Toggle: 'switch',
+    CheckBox: 'checkbox',
+    RadioButton: 'radio',
+    Slider: 'slider',
+    Stepper: 'stepper',
+    Picker: 'picker',
+    PickerWheel: 'picker',
+    DatePicker: 'picker',
+    SegmentedControl: 'tablist',
+    TabBar: 'tablist',
+    TabGroup: 'tablist',
+    Tab: 'tab',
+    NavigationBar: 'toolbar',
+    Toolbar: 'toolbar',
+    StatusBar: 'statusbar',
+    Table: 'list',
+    CollectionView: 'list',
+    Outline: 'list',
+    ScrollView: 'scrollview',
+    WebView: 'webview',
+    Alert: 'alert',
+    Sheet: 'dialog',
+    Dialog: 'dialog',
+    Keyboard: 'keyboard',
+    Key: 'key',
+    ActivityIndicator: 'progressbar',
+    ProgressIndicator: 'progressbar',
+    PageIndicator: 'pager',
+    Map: 'map',
+    Menu: 'menu',
+    MenuItem: 'menuitem',
+    Application: 'screen',
+};
+const TYPE_PREFIX = 'XCUIElementType';
+export function iosTypeOf(element) {
+    const type = element.attrs.type || element.tag;
+    return type.startsWith(TYPE_PREFIX) ? type.slice(TYPE_PREFIX.length) : type;
+}
+export function iosRoleFor(element) {
+    return IOS_ROLE_BY_TYPE[iosTypeOf(element)] ?? 'group';
+}
+function num(value) {
+    if (value === undefined || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? Math.round(n) : null;
+}
+export function iosBounds(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 isSecure(element) {
+    return iosTypeOf(element) === 'SecureTextField';
+}
+/** The accessibility identifier: `name` when it differs from the label (XCUITest falls back to the label). */
+export function identifierOf(element) {
+    const { name, label, value } = element.attrs;
+    if (!name)
+        return '';
+    if (name === label)
+        return '';
+    // Static texts without a label report their text as the name.
+    if (!label && value && name === value)
+        return '';
+    return name;
+}
+/** What an element shows: its label, else (not for secure fields) its value, else its placeholder. */
+function shownName(element) {
+    const a = element.attrs;
+    if (a.label)
+        return a.label;
+    const type = iosTypeOf(element);
+    if (!isSecure(element) && a.value && ['StaticText', 'TextField', 'TextView', 'SearchField', 'Link'].includes(type))
+        return a.value;
+    if (['TextField', 'SecureTextField', 'TextView', 'SearchField'].includes(type) && a.placeholderValue)
+        return a.placeholderValue;
+    return '';
+}
+/** The value worth printing next to the name (not a switch's 0/1, never a secure field's). */
+function shownValue(element, name) {
+    const value = element.attrs.value ?? '';
+    if (!value || isSecure(element) || value === name)
+        return '';
+    if (['Switch', 'Toggle', 'CheckBox'].includes(iosTypeOf(element)))
+        return '';
+    return value;
+}
+function onScreen(bounds, screen) {
+    if (!bounds)
+        return true;
+    if (bounds.width <= 0 || bounds.height <= 0)
+        return false;
+    if (!screen)
+        return true;
+    return bounds.x < screen.x + screen.width && bounds.x + bounds.width > screen.x && bounds.y < screen.y + screen.height && bounds.y + bounds.height > screen.y;
+}
+function stateOf(element) {
+    const a = element.attrs;
+    const state = [];
+    const type = iosTypeOf(element);
+    if (['Switch', 'Toggle', 'CheckBox'].includes(type))
+        state.push(a.value === '1' || a.value === 'true' ? 'checked' : 'unchecked');
+    if (a.enabled === 'false')
+        state.push('disabled');
+    if (a.hasFocus === 'true' || a.focused === 'true')
+        state.push('focused');
+    if (a.selected === 'true')
+        state.push('selected');
+    if (isSecure(element))
+        state.push('password');
+    if (a.visible === 'false')
+        state.push('hidden');
+    return state;
+}
+/** Containers that carry nothing an agent needs: their children take their place. */
+function layoutOnly(element) {
+    const role = iosRoleFor(element);
+    const a = element.attrs;
+    if (role === 'image')
+        return !a.label && a.accessible !== 'true';
+    // Scroll indicators ("Vertical scroll bar, 2 pages", value "0%") are not part of the app.
+    if (role === 'group' && /scroll bar/i.test(a.label ?? '') && /^\d+%$/.test(a.value ?? ''))
+        return true;
+    const hollow = !a.label && !a.name && !a.value && a.accessible !== 'true';
+    if (role === 'group' || role === 'cell')
+        return hollow;
+    return false;
+}
+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]);
+}
+/**
+ * XCUITest queries return hidden elements too, so every element counts for `nth`; the
+ * application itself is not one of its descendants and never matches.
+ */
+function index(all) {
+    const counts = { name: new Map(), label: new Map(), text: new Map(), type: new Map() };
+    for (const element of all) {
+        if (iosTypeOf(element) === 'Application')
+            continue;
+        const a = element.attrs;
+        add(counts.name, a.name, element);
+        add(counts.label, a.label, element);
+        // `text` matches label or value.
+        add(counts.text, a.label, element);
+        if (!isSecure(element))
+            add(counts.text, a.value, element);
+        add(counts.type, a.type || element.tag, element);
+    }
+    return counts;
+}
+function withNth(target, list, element) {
+    if (!list || list.length <= 1)
+        return target;
+    return { ...target, nth: list.indexOf(element) };
+}
+/** `/AppiumAUT/XCUIElementTypeApplication[1]/…` → `//XCUIElementTypeApplication/…` (WDA's XML has no AppiumAUT root). */
+export function wdaXpath(xpath) {
+    return xpath.replace(/^\/AppiumAUT\/XCUIElementTypeApplication\[1\]/, '//XCUIElementTypeApplication');
+}
+/** Locator candidates, best first: id > label > text > class chain (fragile) > xpath (fragile). */
+export function iosCandidatesFor(element, counts) {
+    const out = [];
+    const a = element.attrs;
+    const id = identifierOf(element);
+    if (id && id.length <= 2000) {
+        const list = counts.name.get(id);
+        out.push({ target: withNth({ id }, list, element), fragile: (list?.length ?? 0) > 1 });
+    }
+    if (a.label && a.label.length <= 2000) {
+        const list = counts.label.get(a.label);
+        out.push({ target: withNth({ label: a.label }, list, element), fragile: (list?.length ?? 0) > 1 });
+    }
+    const value = a.value;
+    if (value && value !== a.label && !isSecure(element) && value.length <= 2000 && !['Switch', 'Toggle', 'CheckBox'].includes(iosTypeOf(element))) {
+        const list = counts.text.get(value);
+        out.push({ target: withNth({ text: value, exact: true }, list, element), fragile: (list?.length ?? 0) > 1 });
+    }
+    const type = a.type || element.tag;
+    const position = counts.type.get(type)?.indexOf(element) ?? -1;
+    if (position >= 0) {
+        // Class chain indexes are 1-based over every element of the type in document order.
+        out.push({ target: { class_chain: `**/${type}[${position + 1}]` }, fragile: true });
+    }
+    const xpath = wdaXpath(element.xpath);
+    if (xpath.length <= 500)
+        out.push({ target: { xpath }, fragile: true });
+    return out;
+}
+/** Builds the snapshot tree, text and refs from XCUITest page source XML. */
+export function iosSnapshotFromXml(xml, options = {}) {
+    const tree = parsePageSource(xml);
+    const app = tree.all.find((element) => iosTypeOf(element) === 'Application') ?? null;
+    const screenBounds = app ? iosBounds(app) : null;
+    const counts = index(tree.all);
+    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 bundleId = app?.attrs.bundleId || null;
+    const appName = app?.attrs.label || app?.attrs.name || null;
+    const root = { ref: 'e0', role: 'screen', ...(appName || bundleId ? { name: (appName ?? bundleId) } : {}) };
+    if (screenBounds)
+        root.bounds = { x: 0, y: 0, width: screenBounds.width, height: screenBounds.height };
+    /** `context` = the nearest emitted ancestor's name and role, to skip texts that repeat it. */
+    const convert = (element, depth, parent, context) => {
+        const a = element.attrs;
+        const bounds = iosBounds(element);
+        const role = iosRoleFor(element);
+        const name = shownName(element);
+        const hidden = a.visible === 'false' || !onScreen(bounds, screenBounds);
+        const id = identifierOf(element);
+        // A button or text inside a cell or button that says the same thing (same name, no other id) adds nothing.
+        const redundant = (role === 'text' || role === 'button') && name !== '' && name === context.name && (!id || id === context.id);
+        const decorative = role === 'image' && !a.label && context.interactive;
+        const skip = role === 'screen' || layoutOnly(element) || redundant || decorative || (hidden && !options.includeHidden);
+        if (skip) {
+            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 = shownValue(element, name);
+        if (value)
+            node.text = clipText(value);
+        if (id)
+            node.ids = { accessibility_id: id };
+        if (bounds)
+            node.bounds = bounds;
+        const state = stateOf(element);
+        if (state.length > 0)
+            node.state = state;
+        const { suggest, alternatives, fragile } = suggestionFor(iosCandidatesFor(element, counts));
+        refs[ref] = {
+            locate: { xpath: wdaXpath(element.xpath), ...(bounds ? { bounds } : {}), type: a.type || element.tag },
+            suggest,
+            alternatives,
+            fragile,
+            bounds: bounds ?? null,
+        };
+        (parent.children ??= []).push(node);
+        const interactive = context.interactive || ['button', 'cell', 'link', 'switch', 'checkbox', 'radio', 'tab'].includes(role);
+        for (const child of element.children)
+            convert(child, depth + 1, node, { name: name || context.name, id: id || context.id, interactive });
+    };
+    for (const child of tree.root.children)
+        convert(child, 1, root, { name: '', id: '', interactive: false });
+    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: screenBounds?.width ?? null,
+        height: screenBounds?.height ?? null,
+        rotation: null,
+        bundleId,
+        appName,
+    };
+}