@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,393 @@
+import { XMLParser } from 'fast-xml-parser';
+import { clampDepth, clampMaxChars, clipText, renderSnapshotText, SNAPSHOT_LIMITS, } from '../snapshot/format.js';
+import { escapeUiSelector } from './locate.js';
+const parser = new XMLParser({
+    preserveOrder: true,
+    ignoreAttributes: false,
+    attributeNamePrefix: '',
+    parseAttributeValue: false,
+    parseTagValue: false,
+    trimValues: false,
+    processEntities: true,
+});
+function tagOf(node) {
+    for (const key of Object.keys(node)) {
+        if (key !== ':@' && !key.startsWith('#') && !key.startsWith('?'))
+            return key;
+    }
+    return null;
+}
+function num(value) {
+    if (value === undefined || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/** Parses UiAutomator2's page source. Throws when it is not XML with a `hierarchy` root. */
+export function parsePageSource(xml) {
+    const doc = parser.parse(xml);
+    const top = doc.find((node) => tagOf(node) !== null);
+    if (!top)
+        throw new Error('the page source has no root element');
+    const all = [];
+    const build = (node, xpath) => {
+        const tag = tagOf(node);
+        const element = { tag, attrs: node[':@'] ?? {}, children: [], xpath, order: -1 };
+        const kids = node[tag] ?? [];
+        const seen = new Map();
+        for (const kid of kids) {
+            const kidTag = tagOf(kid);
+            if (!kidTag)
+                continue;
+            const position = (seen.get(kidTag) ?? 0) + 1;
+            seen.set(kidTag, position);
+            element.children.push(build(kid, `${xpath}/${kidTag}[${position}]`));
+        }
+        return element;
+    };
+    const topTag = tagOf(top);
+    const root = build(top, `/${topTag}`);
+    // Document order, excluding the synthetic root.
+    const visit = (element) => {
+        element.order = all.length;
+        all.push(element);
+        for (const child of element.children)
+            visit(child);
+    };
+    for (const child of root.children)
+        visit(child);
+    return {
+        root,
+        all,
+        width: num(root.attrs.width),
+        height: num(root.attrs.height),
+        rotation: num(root.attrs.rotation),
+    };
+}
+/** `[l,t][r,b]` → bounds, or null. */
+export function parseBounds(value) {
+    if (!value)
+        return null;
+    const match = /^\[(-?\d+),(-?\d+)\]\[(-?\d+),(-?\d+)\]$/.exec(value.trim());
+    if (!match)
+        return null;
+    const [l, t, r, b] = match.slice(1).map(Number);
+    return { x: l, y: t, width: r - l, height: b - t };
+}
+/** Simple class name → role. Classes not listed are `group` (layouts) unless they are interactive. */
+const ROLE_BY_CLASS = {
+    Button: 'button',
+    ImageButton: 'button',
+    MaterialButton: 'button',
+    FloatingActionButton: 'button',
+    ExtendedFloatingActionButton: 'button',
+    Chip: 'button',
+    EditText: 'textfield',
+    AutoCompleteTextView: 'textfield',
+    MultiAutoCompleteTextView: 'textfield',
+    TextInputEditText: 'textfield',
+    SearchView: 'search',
+    TextView: 'text',
+    CheckedTextView: 'text',
+    ImageView: 'image',
+    CheckBox: 'checkbox',
+    Switch: 'switch',
+    SwitchCompat: 'switch',
+    SwitchMaterial: 'switch',
+    MaterialSwitch: 'switch',
+    ToggleButton: 'switch',
+    RadioButton: 'radio',
+    RadioGroup: 'radiogroup',
+    Spinner: 'combobox',
+    SeekBar: 'slider',
+    RatingBar: 'slider',
+    ProgressBar: 'progressbar',
+    RecyclerView: 'list',
+    ListView: 'list',
+    GridView: 'grid',
+    ScrollView: 'scrollview',
+    NestedScrollView: 'scrollview',
+    HorizontalScrollView: 'scrollview',
+    ViewPager: 'pager',
+    ViewPager2: 'pager',
+    WebView: 'webview',
+    TabWidget: 'tablist',
+    TabLayout: 'tablist',
+    Toolbar: 'toolbar',
+    ActionBar: 'toolbar',
+    NumberPicker: 'picker',
+    DatePicker: 'picker',
+    TimePicker: 'picker',
+    VideoView: 'video',
+    Image: 'image',
+};
+export function simpleClass(className) {
+    const cleaned = className.replace(/\$.*/, '');
+    return cleaned.slice(cleaned.lastIndexOf('.') + 1);
+}
+export function roleFor(element) {
+    const cls = element.attrs.class || element.tag;
+    const role = ROLE_BY_CLASS[simpleClass(cls)];
+    if (role)
+        return role;
+    if (element.attrs.checkable === 'true')
+        return 'checkbox';
+    if (element.attrs.scrollable === 'true')
+        return 'scrollview';
+    if (element.attrs.clickable === 'true' || element.attrs['long-clickable'] === 'true')
+        return 'button';
+    return 'group';
+}
+/** `com.acme:id/login` → `login` for the app's own package; other packages keep the full id. */
+export function shortResourceId(resourceId, appPackage) {
+    if (!resourceId)
+        return '';
+    if (appPackage && resourceId.startsWith(`${appPackage}:id/`))
+        return resourceId.slice(appPackage.length + 4);
+    return resourceId;
+}
+function isTrue(value) {
+    return value === 'true';
+}
+function isVisible(element, width, height) {
+    if (element.attrs.displayed === 'false')
+        return false;
+    const bounds = parseBounds(element.attrs.bounds);
+    if (!bounds)
+        return true;
+    if (bounds.width <= 0 || bounds.height <= 0)
+        return false;
+    if (width !== null && (bounds.x >= width || bounds.x + bounds.width <= 0))
+        return false;
+    if (height !== null && (bounds.y >= height || bounds.y + bounds.height <= 0))
+        return false;
+    return true;
+}
+function isPassword(element) {
+    return isTrue(element.attrs.password);
+}
+/** Window scaffolding ids that never help a script (`android:id/content`, `…:id/action_bar_root`). */
+const FRAMEWORK_CONTAINER = /^(android:id\/.*|.*:id\/(action_bar_root|decor_content_parent|content|statusBarBackground|navigationBarBackground))$/;
+/** A layout that carries nothing an agent needs: its children take its place. */
+function layoutOnly(element) {
+    const a = element.attrs;
+    return (roleFor(element) === 'group' &&
+        !a.text &&
+        !a['content-desc'] &&
+        (!a['resource-id'] || FRAMEWORK_CONTAINER.test(a['resource-id'])) &&
+        !isTrue(a.clickable) &&
+        !isTrue(a['long-clickable']) &&
+        !isTrue(a.checkable) &&
+        !isTrue(a.scrollable));
+}
+/** A plain container whose only feature is a resource id (wrapper chains such as `…:id/main_content`). */
+function wrapperWithId(element) {
+    const a = element.attrs;
+    return roleFor(element) === 'group' && Boolean(a['resource-id']) && !a.text && !a['content-desc'] && !isTrue(a.clickable) && !isTrue(a['long-clickable']) && !isTrue(a.checkable) && !isTrue(a.scrollable);
+}
+function isDescendant(ancestor, element) {
+    return element.xpath.startsWith(`${ancestor.xpath}/`);
+}
+/** The first non-empty, non-password text in an element's subtree. */
+function firstText(element) {
+    for (const child of element.children) {
+        if (child.attrs.text && !isPassword(child) && child.attrs.displayed !== 'false')
+            return child.attrs.text;
+        const nested = firstText(child);
+        if (nested)
+            return nested;
+    }
+    return '';
+}
+function stateOf(element, role) {
+    const a = element.attrs;
+    const state = [];
+    if (isTrue(a.clickable) && role !== 'button')
+        state.push('clickable');
+    if (isTrue(a['long-clickable']))
+        state.push('long-clickable');
+    if (isTrue(a.checkable))
+        state.push(isTrue(a.checked) ? 'checked' : 'unchecked');
+    if (a.enabled === 'false')
+        state.push('disabled');
+    if (isTrue(a.focused))
+        state.push('focused');
+    if (isTrue(a.selected))
+        state.push('selected');
+    if (isTrue(a.scrollable))
+        state.push('scrollable');
+    if (isPassword(element))
+        state.push('password');
+    if (a.displayed === 'false')
+        state.push('hidden');
+    return state;
+}
+function index(all) {
+    const counts = { desc: new Map(), id: new Map(), text: new Map(), cls: new Map() };
+    const add = (map, key, element) => {
+        if (!key)
+            return;
+        const list = map.get(key);
+        if (list)
+            list.push(element);
+        else
+            map.set(key, [element]);
+    };
+    for (const element of all) {
+        // UiAutomator2 does not return elements it reports as not displayed, so they do not shift `nth`.
+        if (element.attrs.displayed === 'false')
+            continue;
+        add(counts.desc, element.attrs['content-desc'], element);
+        add(counts.id, element.attrs['resource-id'], element);
+        if (!isPassword(element))
+            add(counts.text, element.attrs.text, element);
+        add(counts.cls, element.attrs.class || element.tag, element);
+    }
+    return counts;
+}
+function withNth(target, list, element) {
+    if (!list || list.length <= 1)
+        return target;
+    return { ...target, nth: list.indexOf(element) };
+}
+/**
+ * Locator candidates for an element, best first: desc > id > exact text > UiSelector
+ * instance (fragile) > xpath (fragile). Duplicated values carry `nth` (document order).
+ */
+export function candidatesFor(element, counts, appPackage) {
+    const out = [];
+    const a = element.attrs;
+    const desc = a['content-desc'];
+    if (desc && desc.length <= 2000) {
+        const list = counts.desc.get(desc);
+        out.push({ target: withNth({ desc }, list, element), fragile: (list?.length ?? 0) > 1 });
+    }
+    const rid = a['resource-id'];
+    if (rid) {
+        const list = counts.id.get(rid);
+        out.push({ target: withNth({ id: shortResourceId(rid, appPackage) }, list, element), fragile: (list?.length ?? 0) > 1 });
+    }
+    const text = a.text;
+    if (text && !isPassword(element) && text.length <= 2000) {
+        const list = counts.text.get(text);
+        out.push({ target: withNth({ text, exact: true }, list, element), fragile: (list?.length ?? 0) > 1 });
+    }
+    if (!text && !desc && isTrue(a.clickable)) {
+        // A clickable row without its own label: its first text finds a child inside the row, and tapping that taps the row.
+        const inner = firstText(element);
+        const list = inner ? counts.text.get(inner) : undefined;
+        if (inner && list && inner.length <= 2000) {
+            const child = list.find((candidate) => isDescendant(element, candidate));
+            if (child)
+                out.push({ target: withNth({ text: inner, exact: true }, list, child), fragile: list.length > 1 });
+        }
+    }
+    const cls = a.class || element.tag;
+    const instance = counts.cls.get(cls)?.indexOf(element) ?? -1;
+    if (instance >= 0) {
+        out.push({ target: { uiautomator: `new UiSelector().className("${escapeUiSelector(cls)}").instance(${instance})` }, fragile: true });
+    }
+    if (element.xpath.length <= 500)
+        out.push({ target: { xpath: element.xpath }, fragile: true });
+    return out;
+}
+/**
+ * Suggestion + alternatives: the first candidate that is unique wins (preference order kept);
+ * when none is, the best one gets `nth` and the next-best strategy as `fallbacks[0]`.
+ */
+export function suggestionFor(candidates) {
+    if (candidates.length === 0)
+        return { suggest: {}, alternatives: [], fragile: true };
+    const uniqueIndex = candidates.findIndex((c) => !c.fragile);
+    const chosen = uniqueIndex >= 0 ? uniqueIndex : 0;
+    const best = candidates[chosen];
+    const rest = candidates.filter((_, i) => i !== chosen);
+    let suggest = best.target;
+    if (best.target.nth !== undefined && rest[0]) {
+        suggest = { ...best.target, fallbacks: [rest[0].target] };
+    }
+    return { suggest, alternatives: rest.map((c) => c.target), fragile: best.fragile };
+}
+/** Builds the snapshot tree, text and refs from page source XML. */
+export function snapshotFromXml(xml, options) {
+    const tree = parsePageSource(xml);
+    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 appPackage = options.appPackage ?? tree.all.find((e) => e.attrs.package)?.attrs.package ?? null;
+    const root = { ref: 'e0', role: 'screen', ...(appPackage ? { name: appPackage } : {}) };
+    if (tree.width !== null && tree.height !== null)
+        root.bounds = { x: 0, y: 0, width: tree.width, height: tree.height };
+    const convert = (element, depth, parent) => {
+        if (!options.includeHidden && !isVisible(element, tree.width, tree.height))
+            return;
+        const visibleKids = options.includeHidden ? element.children : element.children.filter((c) => isVisible(c, tree.width, tree.height));
+        if (layoutOnly(element) || (wrapperWithId(element) && visibleKids.length === 1)) {
+            for (const child of element.children)
+                convert(child, depth, parent);
+            return;
+        }
+        if (emitted >= maxNodes || depth > depthLimit) {
+            truncated = true;
+            return;
+        }
+        emitted += 1;
+        const role = roleFor(element);
+        const a = element.attrs;
+        const ref = `e${next}`;
+        next += 1;
+        const node = { ref, role };
+        const desc = a['content-desc'];
+        const text = isPassword(element) ? '' : (a.text ?? '');
+        const hint = a.hint ?? '';
+        // A clickable row without a label of its own is named after the first text inside it.
+        const inner = !desc && !text && role === 'button' ? firstText(element) : '';
+        const name = desc || text || (role === 'textfield' ? hint : '') || inner;
+        if (name)
+            node.name = clipText(name);
+        if (text && desc && text !== desc)
+            node.text = clipText(text);
+        const rid = a['resource-id'];
+        // content-desc is already the name; only the resource id is worth a separate field.
+        if (rid)
+            node.ids = { resource_id: shortResourceId(rid, appPackage) };
+        const bounds = parseBounds(a.bounds);
+        if (bounds)
+            node.bounds = bounds;
+        const state = stateOf(element, role);
+        if (state.length > 0)
+            node.state = state;
+        const { suggest, alternatives, fragile } = suggestionFor(candidatesFor(element, counts, appPackage));
+        refs[ref] = {
+            locate: { xpath: element.xpath, ...(bounds ? { bounds } : {}), class: a.class || element.tag },
+            suggest,
+            alternatives,
+            fragile,
+            bounds: bounds ?? null,
+        };
+        (parent.children ??= []).push(node);
+        for (const child of element.children)
+            convert(child, depth + 1, node);
+    };
+    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: tree.width,
+        height: tree.height,
+        rotation: tree.rotation,
+    };
+}