@leera.io/qa-runner 1.0.0

package/dist/src/drivers/snapshot/aria.js

@@ -0,0 +1,351 @@
+import { clampDepth, clampMaxChars, clipText, renderSnapshotText, SNAPSHOT_LIMITS, } from './format.js';
+/** Roles whose accessible name comes from a label, so `{label}` is a good alternative. */
+const FIELD_ROLES = new Set(['textbox', 'searchbox', 'combobox', 'spinbutton', 'checkbox', 'radio', 'switch', 'slider', 'listbox']);
+/** Roles whose name is their visible text, so `{text}` is a good alternative. */
+const TEXT_ROLES = new Set(['button', 'link', 'heading', 'menuitem', 'tab', 'option', 'cell', 'listitem', 'paragraph', 'label']);
+const LAYOUT_ROLES = new Set(['generic', 'group', 'none', 'presentation']);
+const STATE_ATTRS = new Set(['checked', 'disabled', 'expanded', 'selected', 'pressed', 'required', 'readonly', 'invalid']);
+const REF_PATTERN = /^[a-z0-9]{1,16}$/i;
+/** Parses Playwright's aria snapshot text (the YAML-like list) into a forest. */
+export function parseAriaSnapshot(text) {
+    const roots = [];
+    const stack = [];
+    for (const raw of text.split('\n')) {
+        const match = /^(\s*)- (.*)$/.exec(raw);
+        if (!match)
+            continue;
+        const indent = match[1].length;
+        while (stack.length > 0 && stack.at(-1).indent >= indent)
+            stack.pop();
+        const parent = stack.at(-1)?.node;
+        const body = match[2];
+        if (body.startsWith('/')) {
+            const colon = body.indexOf(':');
+            if (parent && colon > 1)
+                parent.props[body.slice(1, colon)] = unquote(body.slice(colon + 1).trim());
+            continue;
+        }
+        const node = parseLine(body);
+        if (parent)
+            parent.children.push(node);
+        else
+            roots.push(node);
+        stack.push({ indent, node });
+    }
+    return roots;
+}
+function parseLine(body) {
+    let key = body;
+    let value;
+    // A key YAML had to quote: 'link "a: b" [ref=e4]': value
+    if (body.startsWith("'")) {
+        let i = 1;
+        let unquoted = '';
+        while (i < body.length) {
+            if (body[i] === "'" && body[i + 1] === "'") {
+                unquoted += "'";
+                i += 2;
+            }
+            else if (body[i] === "'") {
+                break;
+            }
+            else {
+                unquoted += body[i];
+                i += 1;
+            }
+        }
+        key = unquoted;
+        const rest = body.slice(i + 1).trim();
+        if (rest.startsWith(':'))
+            value = unquote(rest.slice(1).trim()) || undefined;
+    }
+    else {
+        const split = splitKeyValue(body);
+        key = split.key;
+        value = split.value;
+    }
+    const node = { role: '', attrs: {}, props: {}, children: [] };
+    let rest = key.trim();
+    const role = /^[a-zA-Z][\w-]*/.exec(rest);
+    node.role = role ? role[0] : rest;
+    rest = rest.slice(node.role.length).trim();
+    if (rest.startsWith('"')) {
+        const end = closingQuote(rest);
+        node.name = JSON.parse(rest.slice(0, end + 1));
+        rest = rest.slice(end + 1).trim();
+    }
+    for (const attr of rest.matchAll(/\[([\w-]+)(?:=([^\]]*))?\]/g)) {
+        const name = attr[1];
+        const attrValue = attr[2];
+        if (name === 'ref')
+            node.ref = attrValue ?? '';
+        else
+            node.attrs[name] = attrValue ?? true;
+    }
+    if (node.role === 'text' && value === undefined && node.name !== undefined) {
+        value = node.name;
+        delete node.name;
+    }
+    if (value !== undefined)
+        node.value = value;
+    return node;
+}
+/** Splits `role "name" [attr]: value`, ignoring colons inside the quoted name. */
+function splitKeyValue(body) {
+    let inQuote = false;
+    for (let i = 0; i < body.length; i += 1) {
+        const ch = body[i];
+        if (ch === '\\' && inQuote) {
+            i += 1;
+            continue;
+        }
+        if (ch === '"')
+            inQuote = !inQuote;
+        if (ch === ':' && !inQuote && (i === body.length - 1 || body[i + 1] === ' ')) {
+            const value = unquote(body.slice(i + 1).trim());
+            return value ? { key: body.slice(0, i), value } : { key: body.slice(0, i) };
+        }
+    }
+    return { key: body };
+}
+function closingQuote(text) {
+    for (let i = 1; i < text.length; i += 1) {
+        if (text[i] === '\\')
+            i += 1;
+        else if (text[i] === '"')
+            return i;
+    }
+    return text.length - 1;
+}
+function unquote(value) {
+    if (value.length >= 2 && value.startsWith('"') && value.endsWith('"')) {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return value.slice(1, -1);
+        }
+    }
+    if (value.length >= 2 && value.startsWith("'") && value.endsWith("'"))
+        return value.slice(1, -1).replace(/''/g, "'");
+    return value;
+}
+function parseBox(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const parts = value.split(',').map((part) => Math.round(Number(part)));
+    if (parts.length !== 4 || parts.some((part) => !Number.isFinite(part)))
+        return undefined;
+    const [x, y, width, height] = parts;
+    return { x, y, width, height };
+}
+/**
+ * Turns the parsed aria forest into a snapshot: invisible (zero-size) elements dropped unless
+ * `includeHidden`, unnamed layout wrappers hoisted, depth ≤ 25, ≤ 400 elements, text
+ * clipped to `maxChars`, and a suggested DSL target per ref.
+ */
+export function buildWebSnapshot(forest, options = {}) {
+    const maxDepth = clampDepth(options.depth);
+    const secretRefs = options.secretRefs ?? new Set();
+    let count = 0;
+    let truncated = false;
+    const ariaByRef = new Map();
+    const convert = (node, depth) => {
+        const bounds = parseBox(node.attrs.box);
+        if (!options.includeHidden && bounds && bounds.width === 0 && bounds.height === 0)
+            return [];
+        const childDepth = node.ref ? depth + 1 : depth;
+        const children = () => {
+            if (childDepth > maxDepth) {
+                if (node.children.some((child) => child.ref))
+                    truncated = true;
+                return [];
+            }
+            return node.children.flatMap((child) => convert(child, childDepth));
+        };
+        // Plain text lines, and elements without a ref, only contribute their children.
+        if (!node.ref || !REF_PATTERN.test(node.ref))
+            return node.role === 'text' ? [] : children();
+        const texts = node.children.filter((child) => child.role === 'text' && child.value).map((child) => child.value);
+        const layoutOnly = LAYOUT_ROLES.has(node.role) && !node.name && texts.length === 0 && !node.value && depth > 0;
+        if (layoutOnly)
+            return children();
+        if (count >= SNAPSHOT_LIMITS.nodes) {
+            truncated = true;
+            return [];
+        }
+        count += 1;
+        ariaByRef.set(node.ref, node);
+        const secret = secretRefs.has(node.ref);
+        const out = { ref: node.ref, role: node.role };
+        if (node.name)
+            out.name = clipText(node.name);
+        const text = secret ? undefined : (node.value ?? texts.join(' '));
+        if (text)
+            out.text = clipText(text);
+        if (bounds)
+            out.bounds = bounds;
+        const state = stateOf(node, secret);
+        if (state.length > 0)
+            out.state = state;
+        const kids = children();
+        if (kids.length > 0)
+            out.children = kids;
+        return [out];
+    };
+    const nodes = forest.flatMap((node) => convert(node, 0));
+    const root = nodes.length === 0 ? null : nodes.length === 1 ? nodes[0] : { ref: 'e0', role: 'document', children: nodes };
+    const rendered = renderSnapshotText(root, clampMaxChars(options.maxChars));
+    const refs = suggestTargets(root, ariaByRef, rendered.refs);
+    return {
+        platform: 'web',
+        taken_at: options.takenAt ?? new Date().toISOString(),
+        screen: options.screen ?? null,
+        root,
+        text: rendered.text,
+        refs,
+        element_count: count,
+        truncated: truncated || rendered.truncated,
+    };
+}
+function stateOf(node, secret) {
+    const state = [];
+    for (const [name, value] of Object.entries(node.attrs)) {
+        if (name === 'box' || name === 'ref')
+            continue;
+        if (name === 'active')
+            state.push('focused');
+        else if (name === 'cursor' && value === 'pointer')
+            state.push('clickable');
+        else if (name === 'level')
+            state.push(`level=${value}`);
+        else if (STATE_ATTRS.has(name))
+            state.push(value === true || value === 'true' ? name : `${name}=${value}`);
+    }
+    if (node.props.url)
+        state.push(`url=${clipText(node.props.url)}`);
+    if (node.props.placeholder)
+        state.push(`placeholder="${clipText(node.props.placeholder)}"`);
+    if (secret)
+        state.push('password');
+    return state;
+}
+/** Suggested locators: role+name first, then label/text/placeholder; duplicates get `nth` and a fallback. */
+function suggestTargets(root, aria, shown) {
+    const all = [];
+    const walk = (node) => {
+        const source = aria.get(node.ref);
+        if (source)
+            all.push({ node, ...candidates(source) });
+        for (const child of node.children ?? [])
+            walk(child);
+    };
+    if (root)
+        walk(root);
+    const seen = new Map();
+    const totals = new Map();
+    for (const entry of all) {
+        const key = JSON.stringify(entry.primary);
+        totals.set(key, (totals.get(key) ?? 0) + 1);
+    }
+    const refs = {};
+    for (const entry of all) {
+        const key = JSON.stringify(entry.primary);
+        const index = seen.get(key) ?? 0;
+        seen.set(key, index + 1);
+        let suggest = entry.primary;
+        let fragile = entry.fragile;
+        if ((totals.get(key) ?? 1) > 1) {
+            suggest = { ...entry.primary, nth: index };
+            fragile = true;
+            if (entry.alternatives[0])
+                suggest.fallbacks = [entry.alternatives[0]];
+        }
+        if (!shown.has(entry.node.ref))
+            continue;
+        refs[entry.node.ref] = {
+            locate: { aria_ref: entry.node.ref },
+            suggest,
+            alternatives: entry.alternatives,
+            fragile,
+            bounds: entry.node.bounds ?? null,
+        };
+    }
+    return refs;
+}
+function candidates(node) {
+    const alternatives = [];
+    const name = node.name && node.name.length <= SNAPSHOT_LIMITS.nameChars ? node.name : undefined;
+    if (name) {
+        if (FIELD_ROLES.has(node.role))
+            alternatives.push({ label: name, exact: true });
+        if (TEXT_ROLES.has(node.role))
+            alternatives.push({ text: name, exact: true });
+        if (node.props.placeholder)
+            alternatives.push({ placeholder: node.props.placeholder, exact: true });
+        return { primary: { role: node.role, name, exact: true }, alternatives, fragile: false };
+    }
+    if (node.props.placeholder) {
+        return { primary: { placeholder: node.props.placeholder, exact: true }, alternatives: [{ role: node.role }], fragile: false };
+    }
+    const text = node.value ?? node.children.find((child) => child.role === 'text' && child.value)?.value;
+    if (text && text.length <= SNAPSHOT_LIMITS.nameChars && !FIELD_ROLES.has(node.role)) {
+        return { primary: { text, exact: true }, alternatives: [{ role: node.role }], fragile: false };
+    }
+    return { primary: { role: node.role }, alternatives: [], fragile: true };
+}
+/** The page's screen: viewport, URL and title. */
+export async function webScreen(page) {
+    const viewport = page.viewportSize();
+    return {
+        width: viewport?.width ?? null,
+        height: viewport?.height ?? null,
+        scale: null,
+        orientation: viewport ? (viewport.width >= viewport.height ? 'landscape' : 'portrait') : null,
+        activity: null,
+        url: page.url(),
+        title: await page.title().catch(() => null),
+        package: null,
+    };
+}
+/** Takes a web snapshot of `page`; password field values are left out. */
+export async function webSnapshot(page, options = {}) {
+    const depth = clampDepth(options.depth);
+    const yaml = await page.ariaSnapshot({ mode: 'ai', boxes: true, depth: depth + 5 });
+    const forest = parseAriaSnapshot(yaml);
+    const secretRefs = new Set();
+    const fields = [];
+    const collect = (nodes) => {
+        for (const node of nodes) {
+            if (node.ref && node.role === 'textbox' && REF_PATTERN.test(node.ref))
+                fields.push(node.ref);
+            collect(node.children);
+        }
+    };
+    collect(forest);
+    for (const ref of fields.slice(0, 100)) {
+        const secret = await page
+            .locator(`aria-ref=${ref}`)
+            .evaluate((element) => element instanceof HTMLInputElement && element.type === 'password', undefined, { timeout: 1_000 })
+            .catch(() => true);
+        if (secret)
+            secretRefs.add(ref);
+    }
+    return buildWebSnapshot(forest, {
+        depth,
+        ...(options.includeHidden !== undefined ? { includeHidden: options.includeHidden } : {}),
+        ...(options.maxChars !== undefined ? { maxChars: options.maxChars } : {}),
+        secretRefs,
+        screen: await webScreen(page),
+    });
+}
+/** The selector for a snapshot ref, or null when `locate` is not a web ref. */
+export function ariaRefSelector(locate) {
+    const ref = locate?.aria_ref;
+    return typeof ref === 'string' && REF_PATTERN.test(ref) ? `aria-ref=${ref}` : null;
+}
+/** The ref at the top of an element's own AI-mode aria snapshot. */
+export function refFromElementSnapshot(yaml) {
+    const match = /\[ref=([a-z0-9]{1,16})\]/i.exec(yaml);
+    return match ? match[1] : null;
+}

package/dist/src/drivers/snapshot/format.js

@@ -0,0 +1,106 @@
+export const SNAPSHOT_LIMITS = {
+    depth: 25,
+    nodes: 400,
+    textChars: 12_000,
+    maxTextChars: 60_000,
+    nameChars: 80,
+};
+export function emptyScreen() {
+    return { width: null, height: null, scale: null, orientation: null, activity: null, url: null, title: null, package: null };
+}
+/** Clamps a requested `max_chars` to 1 000–60 000 (default 12 000). */
+export function clampMaxChars(requested) {
+    if (requested === undefined || !Number.isFinite(requested))
+        return SNAPSHOT_LIMITS.textChars;
+    return Math.max(1_000, Math.min(SNAPSHOT_LIMITS.maxTextChars, Math.floor(requested)));
+}
+/** Clamps a requested depth to 1–25 (default 25). */
+export function clampDepth(requested) {
+    if (requested === undefined || !Number.isFinite(requested))
+        return SNAPSHOT_LIMITS.depth;
+    return Math.max(1, Math.min(SNAPSHOT_LIMITS.depth, Math.floor(requested)));
+}
+export function clipText(value, max = SNAPSHOT_LIMITS.nameChars) {
+    const single = value.replace(/\s+/g, ' ').trim();
+    return single.length > max ? `${single.slice(0, max - 1)}…` : single;
+}
+function quote(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** One node as a line, without indentation: `[e4] button id=login_button "Sign in" {48,760,984,140} clickable`. */
+export function formatNodeLine(node) {
+    const parts = [`[${node.ref}]`, node.role];
+    if (node.ids?.resource_id)
+        parts.push(`id=${node.ids.resource_id}`);
+    if (node.ids?.accessibility_id)
+        parts.push(`aid=${node.ids.accessibility_id}`);
+    if (node.ids?.test_id && node.ids.test_id !== node.ids.resource_id && node.ids.test_id !== node.ids.accessibility_id) {
+        parts.push(`tid=${node.ids.test_id}`);
+    }
+    if (node.name)
+        parts.push(quote(node.name));
+    if (node.text && node.text !== node.name)
+        parts.push(`text=${quote(node.text)}`);
+    if (node.bounds) {
+        const { x, y, width, height } = node.bounds;
+        parts.push(`{${x},${y},${width},${height}}`);
+    }
+    if (node.state && node.state.length > 0)
+        parts.push(node.state.join(' '));
+    return parts.join(' ');
+}
+/**
+ * Renders the tree depth-first, two spaces per level. Stops before a line would push the
+ * text past `maxChars` and says how many elements were left out.
+ */
+export function renderSnapshotText(root, maxChars = SNAPSHOT_LIMITS.textChars) {
+    const lines = [];
+    const refs = new Set();
+    let used = 0;
+    let count = 0;
+    let omitted = 0;
+    const budget = Math.max(0, maxChars - 120); // room for the truncation note
+    const visit = (node, depth) => {
+        count += 1;
+        const line = `${'  '.repeat(depth)}${formatNodeLine(node)}`;
+        if (omitted === 0 && used + line.length + 1 <= budget) {
+            lines.push(line);
+            refs.add(node.ref);
+            used += line.length + 1;
+        }
+        else {
+            omitted += 1;
+        }
+        for (const child of node.children ?? [])
+            visit(child, depth + 1);
+    };
+    if (root)
+        visit(root, 0);
+    const truncated = omitted > 0;
+    if (truncated) {
+        lines.push(`… ${omitted} more element${omitted === 1 ? '' : 's'} not shown (use find, a smaller depth, or a larger max_chars)`);
+    }
+    return { text: lines.join('\n'), truncated, refs, count };
+}
+/** Builds the session-result `snapshot` object; refs are limited to the elements shown in the text. */
+export function toSnapshotResult(snapshot) {
+    return {
+        text: snapshot.text,
+        refs: snapshot.refs,
+        element_count: snapshot.element_count,
+        truncated: snapshot.truncated ?? false,
+    };
+}
+/** Walks a tree depth-first. */
+export function* walkNodes(root) {
+    if (!root)
+        return;
+    const stack = [root];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        yield node;
+        const children = node.children ?? [];
+        for (let i = children.length - 1; i >= 0; i -= 1)
+            stack.push(children[i]);
+    }
+}