@leera.io/qa-runner 1.0.0

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

@@ -0,0 +1,376 @@
+/*
+ * Runner-owned snapshot script for WebDriver-backed web views (Tauri, contracts §L).
+ * Executed with W3C `execute/sync` as `return (<this file>).apply(null, arguments);`, never
+ * with user-provided script. Walks the document and returns a compact tree the runner turns
+ * into a session snapshot (plan §7.3): role from ARIA or the tag, accessible name, text
+ * (≤80 characters), data-testid, id, bounds and state. Invisible elements are dropped unless
+ * `includeHidden`; layout-only elements are hoisted; depth and node count are capped.
+ *
+ * request: { depth?, includeHidden?, maxNodes?, viewportOnly? }
+ * returns: { viewport: {width, height, scale}, url, title, truncated, count,
+ *            nodes: RawNode[], elements: Element[] }
+ * RawNode: { i, role, name?, text?, test_id?, id?, bounds?, state?, xpath,
+ *            test_id_count?, test_id_index?, id_selector?, id_count?, text_key?, text_count?, text_index?,
+ *            children? }  (`i` indexes `elements`)
+ */
+(function domSnapshot(request) {
+  const options = request || {};
+  const viewport = { width: window.innerWidth, height: window.innerHeight, scale: window.devicePixelRatio || 1 };
+  if (options.viewportOnly) return { viewport: viewport, url: String(location.href), title: document.title };
+
+  const MAX_DEPTH = Math.max(1, Math.min(25, Number(options.depth) || 25));
+  const MAX_NODES = Math.max(1, Math.min(400, Number(options.maxNodes) || 400));
+  const MAX_TEXT = 80;
+  const includeHidden = options.includeHidden === true;
+  const SKIP = { SCRIPT: 1, STYLE: 1, NOSCRIPT: 1, TEMPLATE: 1, HEAD: 1, META: 1, LINK: 1, TITLE: 1, BR: 1 };
+  const CONTENT_NAMED = { button: 1, link: 1, heading: 1, menuitem: 1, tab: 1, option: 1, cell: 1, columnheader: 1, listitem: 1, label: 1, paragraph: 1 };
+  const LEAF_ROLES = { button: 1, link: 1, heading: 1, menuitem: 1, tab: 1, option: 1, paragraph: 1, label: 1 };
+  const INTERACTIVE = { button: 1, link: 1, textbox: 1, searchbox: 1, checkbox: 1, radio: 1, combobox: 1, listbox: 1, slider: 1, spinbutton: 1, switch: 1, tab: 1, menuitem: 1, option: 1 };
+
+  function normalize(value) {
+    return String(value == null ? '' : value)
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  function clip(value) {
+    const text = normalize(value);
+    return text.length > MAX_TEXT ? `${text.slice(0, MAX_TEXT - 1)}…` : text;
+  }
+
+  function inputType(element) {
+    return (element.getAttribute('type') || 'text').toLowerCase();
+  }
+
+  function roleOf(element) {
+    const explicit = normalize(element.getAttribute('role')).split(' ')[0];
+    if (explicit) return explicit;
+    const tag = element.tagName;
+    switch (tag) {
+      case 'A':
+        return element.hasAttribute('href') ? 'link' : 'generic';
+      case 'BUTTON':
+      case 'SUMMARY':
+        return 'button';
+      case 'INPUT': {
+        const type = inputType(element);
+        if (type === 'hidden') return null;
+        if (type === 'button' || type === 'submit' || type === 'reset' || type === 'image') return 'button';
+        if (type === 'checkbox') return 'checkbox';
+        if (type === 'radio') return 'radio';
+        if (type === 'range') return 'slider';
+        if (type === 'number') return 'spinbutton';
+        if (type === 'search') return 'searchbox';
+        return 'textbox';
+      }
+      case 'SELECT':
+        return element.multiple || element.size > 1 ? 'listbox' : 'combobox';
+      case 'TEXTAREA':
+        return 'textbox';
+      case 'OPTION':
+        return 'option';
+      case 'IMG':
+        return 'img';
+      case 'H1':
+      case 'H2':
+      case 'H3':
+      case 'H4':
+      case 'H5':
+      case 'H6':
+        return 'heading';
+      case 'UL':
+      case 'OL':
+        return 'list';
+      case 'LI':
+        return 'listitem';
+      case 'NAV':
+        return 'navigation';
+      case 'MAIN':
+        return 'main';
+      case 'HEADER':
+        return 'banner';
+      case 'FOOTER':
+        return 'contentinfo';
+      case 'ASIDE':
+        return 'complementary';
+      case 'FORM':
+        return 'form';
+      case 'TABLE':
+        return 'table';
+      case 'TR':
+        return 'row';
+      case 'TD':
+        return 'cell';
+      case 'TH':
+        return 'columnheader';
+      case 'DIALOG':
+        return 'dialog';
+      case 'P':
+        return 'paragraph';
+      case 'LABEL':
+        return 'label';
+      case 'FIELDSET':
+      case 'DETAILS':
+        return 'group';
+      case 'PROGRESS':
+        return 'progressbar';
+      case 'ARTICLE':
+        return 'article';
+      case 'SECTION':
+        return 'region';
+      case 'IFRAME':
+        return 'iframe';
+      default:
+        return 'generic';
+    }
+  }
+
+  function isVisible(element) {
+    if (typeof element.checkVisibility === 'function') {
+      if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true })) return false;
+    } else {
+      const style = window.getComputedStyle(element);
+      if (style.visibility === 'hidden' || style.display === 'none' || style.opacity === '0') return false;
+    }
+    const rect = element.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  }
+
+  function labelText(element) {
+    const labelledBy = element.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const parts = [];
+      labelledBy.split(/\s+/).forEach((id) => {
+        const ref = id && document.getElementById(id);
+        if (ref) parts.push(normalize(ref.textContent));
+      });
+      if (parts.join(' ').trim()) return parts.join(' ').trim();
+    }
+    if (element.labels && element.labels.length > 0) {
+      const texts = [];
+      for (let i = 0; i < element.labels.length; i += 1) texts.push(controlLabel(element.labels[i], element));
+      const joined = normalize(texts.join(' '));
+      if (joined) return joined;
+    }
+    return '';
+  }
+
+  /** A label's text without the text of the control it wraps (a select's options, say). */
+  function controlLabel(label, control) {
+    if (!label.contains(control)) return normalize(label.textContent);
+    let text = '';
+    const walker = document.createTreeWalker(label, NodeFilter.SHOW_TEXT);
+    for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+      if (!control.contains(node)) text += ` ${node.nodeValue}`;
+    }
+    return normalize(text);
+  }
+
+  function nameOf(element, role) {
+    const aria = normalize(element.getAttribute('aria-label'));
+    if (aria) return aria;
+    const tag = element.tagName;
+    if (tag === 'INPUT' || tag === 'SELECT' || tag === 'TEXTAREA') {
+      const type = tag === 'INPUT' ? inputType(element) : '';
+      if (type === 'button' || type === 'submit' || type === 'reset') return normalize(element.value) || normalize(element.title);
+      if (type === 'image') return normalize(element.alt) || normalize(element.title);
+      return labelText(element) || normalize(element.getAttribute('placeholder')) || normalize(element.title);
+    }
+    const labelled = labelText(element);
+    if (labelled) return labelled;
+    if (tag === 'IMG') return normalize(element.getAttribute('alt')) || normalize(element.title);
+    if (tag === 'LABEL') {
+      const control = element.querySelector('select, textarea');
+      if (control) return controlLabel(element, control) || normalize(element.title);
+    }
+    if (CONTENT_NAMED[role]) return normalize(element.textContent) || normalize(element.title);
+    return normalize(element.title);
+  }
+
+  /** Text directly inside the element (not in child elements). */
+  function ownText(element) {
+    let text = '';
+    for (let node = element.firstChild; node; node = node.nextSibling) {
+      if (node.nodeType === 3) text += ` ${node.nodeValue}`;
+    }
+    return normalize(text);
+  }
+
+  /** The text a text locator compares (same rules as dom-locate.js). */
+  function locatorText(element) {
+    if (element.tagName === 'INPUT') {
+      const type = inputType(element);
+      return type === 'button' || type === 'submit' || type === 'reset' ? normalize(element.value) : '';
+    }
+    return normalize(element.textContent);
+  }
+
+  function xpathOf(element) {
+    const steps = [];
+    for (let node = element; node && node.nodeType === 1; node = node.parentElement) {
+      const tag = node.tagName.toLowerCase();
+      let index = 1;
+      let same = 0;
+      for (let sibling = node.parentElement ? node.parentElement.firstElementChild : null; sibling; sibling = sibling.nextElementSibling) {
+        if (sibling.tagName === node.tagName) {
+          same += 1;
+          if (sibling === node) index = same;
+        }
+      }
+      steps.unshift(same > 1 ? `${tag}[${index}]` : tag);
+    }
+    return `/${steps.join('/')}`;
+  }
+
+  function stateOf(element, role) {
+    const state = [];
+    const tag = element.tagName;
+    if (element.disabled === true || element.getAttribute('aria-disabled') === 'true') state.push('disabled');
+    if ((tag === 'INPUT' && (element.type === 'checkbox' || element.type === 'radio') && element.checked) || element.getAttribute('aria-checked') === 'true') {
+      state.push('checked');
+    }
+    if ((tag === 'OPTION' && element.selected) || element.getAttribute('aria-selected') === 'true') state.push('selected');
+    if (element.getAttribute('aria-expanded') === 'true') state.push('expanded');
+    if (element.required === true || element.getAttribute('aria-required') === 'true') state.push('required');
+    if (element.readOnly === true || element.getAttribute('aria-readonly') === 'true') state.push('readonly');
+    if (document.activeElement === element && element !== document.body) state.push('focused');
+    if (tag === 'INPUT' && inputType(element) === 'password') state.push('password');
+    if (role === 'heading' && /^H[1-6]$/.test(tag)) state.push(`level=${tag.slice(1)}`);
+    if (INTERACTIVE[role] || element.hasAttribute('onclick') || (element.tabIndex >= 0 && element.hasAttribute('tabindex'))) {
+      state.push('clickable');
+    } else {
+      try {
+        if (window.getComputedStyle(element).cursor === 'pointer') state.push('clickable');
+      } catch {
+        // Detached or odd element: no state.
+      }
+    }
+    return state;
+  }
+
+  function cssEscape(value) {
+    if (window.CSS && typeof window.CSS.escape === 'function') return window.CSS.escape(value);
+    return String(value).replace(/[^a-zA-Z0-9_-]/g, (ch) => `\\${ch}`);
+  }
+
+  // Duplicates for suggestions: data-testid values and innermost exact texts across the document.
+  const testIdCounts = {};
+  const testIdSeen = {};
+  const textCounts = {};
+  const textSeen = {};
+  const innermost = typeof WeakMap === 'function' ? new WeakMap() : null;
+  if (document.body) {
+    const every = document.body.querySelectorAll('*');
+    for (let k = 0; k < every.length; k += 1) {
+      const element = every[k];
+      if (SKIP[element.tagName]) continue;
+      const tid = element.getAttribute('data-testid');
+      if (tid !== null) testIdCounts[tid] = (testIdCounts[tid] || 0) + 1;
+      const text = locatorText(element);
+      if (!text || text.length > MAX_TEXT || !innermost) continue;
+      let inner = true;
+      for (let child = element.firstElementChild; child; child = child.nextElementSibling) {
+        if (!SKIP[child.tagName] && locatorText(child) === text) {
+          inner = false;
+          break;
+        }
+      }
+      if (!inner) continue;
+      textCounts[text] = (textCounts[text] || 0) + 1;
+      innermost.set(element, text);
+    }
+  }
+
+  const elements = [];
+  let truncated = false;
+  let count = 0;
+
+  function hasInterestingDescendant(element) {
+    const all = element.querySelectorAll('a[href],button,input,select,textarea,[role],[data-testid],[tabindex],[onclick]');
+    return all.length > 0;
+  }
+
+  function visit(element, depth) {
+    if (SKIP[element.tagName]) return [];
+    if (!includeHidden && !isVisible(element)) {
+      // `display: contents` wrappers have no box but visible children.
+      const style = window.getComputedStyle(element);
+      if (style.display !== 'contents') return [];
+    }
+    const role = roleOf(element);
+    if (role === null) return [];
+    const name = nameOf(element, role);
+    const testId = element.getAttribute('data-testid');
+    const id = element.id || '';
+    const own = element.tagName === 'INPUT' || element.tagName === 'TEXTAREA' ? '' : ownText(element);
+    const layoutOnly = (role === 'generic' || role === 'group' || role === 'none' || role === 'presentation') && !name && !own && testId === null;
+    const interactiveish = INTERACTIVE[role] || element.hasAttribute('onclick');
+
+    function children(nextDepth) {
+      let out = [];
+      for (let child = element.firstElementChild; child; child = child.nextElementSibling) {
+        out = out.concat(visit(child, nextDepth));
+      }
+      return out;
+    }
+
+    if (layoutOnly && !interactiveish) return children(depth);
+    if (depth >= MAX_DEPTH) {
+      truncated = true;
+      return [];
+    }
+    if (count >= MAX_NODES) {
+      truncated = true;
+      return [];
+    }
+    count += 1;
+    const node = { i: elements.length, role: role, xpath: xpathOf(element) };
+    elements.push(element);
+    if (name) node.name = clip(name);
+    const password = element.tagName === 'INPUT' && inputType(element) === 'password';
+    let text = '';
+    if ((element.tagName === 'INPUT' || element.tagName === 'TEXTAREA') && !password && role === 'textbox') text = normalize(element.value);
+    else if (!CONTENT_NAMED[role] || !name) text = own;
+    if (text && text !== name) node.text = clip(text);
+    if (testId !== null) {
+      node.test_id = testId;
+      node.test_id_count = testIdCounts[testId] || 1;
+      testIdSeen[testId] = (testIdSeen[testId] || 0) + 1;
+      node.test_id_index = testIdSeen[testId] - 1;
+    }
+    if (id) {
+      node.id = id;
+      node.id_selector = `#${cssEscape(id)}`;
+      try {
+        node.id_count = document.querySelectorAll(node.id_selector).length;
+      } catch {
+        node.id_count = 0;
+      }
+    }
+    const key = innermost ? innermost.get(element) : undefined;
+    if (key !== undefined) {
+      node.text_key = key;
+      node.text_count = textCounts[key] || 1;
+      textSeen[key] = (textSeen[key] || 0) + 1;
+      node.text_index = textSeen[key] - 1;
+    }
+    const rect = element.getBoundingClientRect();
+    if (rect.width > 0 || rect.height > 0) {
+      node.bounds = { x: Math.round(rect.left), y: Math.round(rect.top), width: Math.round(rect.width), height: Math.round(rect.height) };
+    }
+    const state = stateOf(element, role);
+    if (state.length > 0) node.state = state;
+    if (!(LEAF_ROLES[role] && !hasInterestingDescendant(element))) {
+      const kids = children(depth + 1);
+      if (kids.length > 0) node.children = kids;
+    }
+    return [node];
+  }
+
+  let nodes = document.body ? visit(document.body, 0) : [];
+  // The body itself is layout: its children are the top level.
+  if (nodes.length === 1 && elements[nodes[0].i] === document.body && nodes[0].role === 'generic' && !nodes[0].name) {
+    nodes = nodes[0].children || [];
+  }
+  return { viewport: viewport, url: String(location.href), title: document.title, truncated: truncated, count: count, nodes: nodes, elements: elements };
+})

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

@@ -0,0 +1,118 @@
+import { clampMaxChars, clipText, renderSnapshotText, } from '../snapshot/format.js';
+import { MAX_XPATH_CHARS } from './dom.js';
+import { elementIdOf } from './locate.js';
+/** The screen a DOM snapshot (or its viewport-only form) describes. */
+export function domScreen(raw, appId = null) {
+    const width = numberOrNull(raw.viewport?.width);
+    const height = numberOrNull(raw.viewport?.height);
+    return {
+        width,
+        height,
+        scale: numberOrNull(raw.viewport?.scale),
+        orientation: width !== null && height !== null ? (width >= height ? 'landscape' : 'portrait') : null,
+        activity: null,
+        url: typeof raw.url === 'string' ? raw.url : null,
+        title: typeof raw.title === 'string' ? raw.title : null,
+        package: appId,
+    };
+}
+function numberOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+/** The locators a node can be found with, best first. */
+export function domCandidatesFor(node) {
+    const out = [];
+    if (node.test_id)
+        out.push({ target: { test_id: node.test_id }, count: node.test_id_count ?? 1, index: node.test_id_index ?? 0 });
+    if (node.id_selector && node.id_count === 1)
+        out.push({ target: { css: node.id_selector }, count: 1, index: 0 });
+    if (node.text_key && !node.state?.includes('password')) {
+        out.push({ target: { text: node.text_key, exact: true }, count: node.text_count ?? 1, index: node.text_index ?? 0 });
+    }
+    if (node.xpath && node.xpath.length <= MAX_XPATH_CHARS)
+        out.push({ target: { xpath: node.xpath }, count: 1, index: 0 });
+    return out;
+}
+/** The suggestion for a node: unique best candidate, or the best with `nth` plus the next-best as a fallback. */
+export function suggestFor(node) {
+    const candidates = domCandidatesFor(node);
+    const first = candidates[0];
+    if (!first)
+        return { suggest: { xpath: node.xpath }, alternatives: [], fragile: true };
+    const alternatives = candidates.slice(1).map((candidate) => (candidate.count > 1 ? { ...candidate.target, nth: candidate.index } : candidate.target));
+    if (first.count <= 1)
+        return { suggest: first.target, alternatives, fragile: 'xpath' in first.target };
+    const next = candidates.slice(1).find((candidate) => candidate.count <= 1) ?? candidates[1];
+    const suggest = { ...first.target, nth: first.index };
+    if (next)
+        suggest.fallbacks = [next.count > 1 ? { ...next.target, nth: next.index } : next.target];
+    return { suggest, alternatives, fragile: true };
+}
+/** Builds the snapshot and the ref → element map from the script's result. */
+export function buildDomSnapshot(raw, options = {}) {
+    const rawElements = Array.isArray(raw.elements) ? raw.elements : [];
+    const elements = new Map();
+    const sources = new Map();
+    let next = 1;
+    const convert = (node) => {
+        const ref = `e${next++}`;
+        const reference = rawElements[node.i];
+        if (reference !== undefined) {
+            try {
+                elements.set(ref, elementIdOf(reference));
+            }
+            catch {
+                // Not an element reference: the node stays in the tree without a ref target.
+            }
+        }
+        sources.set(ref, node);
+        const out = { ref, role: String(node.role || 'generic') };
+        if (node.name)
+            out.name = clipText(node.name);
+        if (node.text)
+            out.text = clipText(node.text);
+        const ids = {};
+        if (node.test_id)
+            ids.test_id = node.test_id;
+        if (node.id)
+            ids.resource_id = node.id;
+        if (Object.keys(ids).length > 0)
+            out.ids = ids;
+        if (node.bounds)
+            out.bounds = node.bounds;
+        if (node.state && node.state.length > 0)
+            out.state = node.state;
+        const children = (node.children ?? []).map(convert);
+        if (children.length > 0)
+            out.children = children;
+        return out;
+    };
+    const forest = (raw.nodes ?? []).map(convert);
+    const root = forest.length === 0 ? null : forest.length === 1 ? forest[0] : { ref: 'e0', role: 'document', ...(raw.title ? { name: clipText(raw.title) } : {}), children: forest };
+    const rendered = renderSnapshotText(root, clampMaxChars(options.maxChars));
+    const refs = {};
+    for (const [ref, node] of sources) {
+        if (!rendered.refs.has(ref) || !elements.has(ref))
+            continue;
+        refs[ref] = { locate: { dom_ref: ref }, ...suggestFor(node), bounds: node.bounds ?? null };
+    }
+    return {
+        snapshot: {
+            platform: options.platform ?? 'tauri',
+            taken_at: options.takenAt ?? new Date().toISOString(),
+            screen: domScreen(raw, options.appId ?? null),
+            ...(options.appId ? { app: { id: options.appId } } : {}),
+            root,
+            text: rendered.text,
+            refs,
+            element_count: typeof raw.count === 'number' ? raw.count : sources.size,
+            truncated: raw.truncated === true || rendered.truncated,
+        },
+        elements,
+    };
+}
+/** The ref a `locate` from a DOM snapshot names, or null. */
+export function domRefOf(locate) {
+    const ref = locate?.dom_ref;
+    return typeof ref === 'string' && /^e\d{1,6}$/.test(ref) ? ref : null;
+}