@xylentis/testgen 0.0.0-stage → 1.1.0

package/runtime/selenium/engine.js

@@ -0,0 +1,426 @@
+// testgen locator engine.
+//
+// testgen (@xylentis/testgen), Copyright (C) 2026 Xylentis. Licensed under AGPL-3.0-only with an additional
+// permission: as part of tests generated by testgen, this file may be used, modified and distributed under
+// terms of your choice (see NOTICE in @xylentis/testgen).
+//
+// Runs inside the page through WebDriver's executeScript and resolves Playwright-style locator
+// steps (role, text, label, test id, CSS, XPath, filters) to elements, so that Selenium tests
+// find elements the way the Playwright recorder chose them. Shared by the Selenium support files
+// of every language: it must stay one self-contained function.
+//
+// A step is one of:
+//   { t: 'css' | 'xpath', v }                     { t: 'role', role, name?, exact?, attrs? }
+//   { t: 'text' | 'label' | 'placeholder' | 'alt' | 'title', v, exact? }
+//   { t: 'testid', attr, v }                      { t: 'hasText', v, exact?, not? }
+//   { t: 'has', steps, not? }                     { t: 'visible', v }
+//   { t: 'nth', v }                               { t: 'and' | 'or', steps }
+// where a text value v is a string or { source, flags } for a regular expression.
+function testgenResolve(stepsJson) {
+  const steps = typeof stepsJson === 'string' ? JSON.parse(stepsJson) : stepsJson;
+  const skipText = new Set(['script', 'style', 'noscript', 'template', 'head']);
+  const textCache = new Map();
+
+  const isElement = node => !!node && node.nodeType === 1;
+  const normalize = text => String(text == null ? '' : text).replace(/​/g, '').trim().replace(/\s+/g, ' ');
+  const unique = list => [...new Set(list)];
+  const parentOf = el => el.parentElement || (el.parentNode && el.parentNode.host) || null;
+
+  // Playwright semantics: strings match case-insensitively as substrings unless exact.
+  const matches = (value, expected, exact) => {
+    const text = normalize(value);
+    if (expected && typeof expected === 'object')
+      return new RegExp(expected.source, expected.flags.replace(/[gy]/g, '')).test(text);
+    const wanted = normalize(expected);
+    return exact ? text === wanted : text.toLowerCase().includes(wanted.toLowerCase());
+  };
+
+  // Elements below `root` in document order, including open shadow roots.
+  const descendants = root => {
+    const result = [];
+    const visit = node => {
+      for (let child = node.firstElementChild; child; child = child.nextElementSibling) {
+        result.push(child);
+        if (child.shadowRoot)
+          visit(child.shadowRoot);
+        visit(child);
+      }
+    };
+    visit(root);
+    return result;
+  };
+
+  const childrenOf = el => [...el.children, ...(el.shadowRoot ? el.shadowRoot.children : [])];
+
+  const elementText = el => {
+    if (textCache.has(el))
+      return textCache.get(el);
+    let text = '';
+    if (el.localName === 'input' && ['button', 'submit', 'reset'].includes(el.type)) {
+      text = el.value;
+    } else {
+      const add = node => {
+        for (let child = node.firstChild; child; child = child.nextSibling) {
+          if (child.nodeType === 3)
+            text += child.data;
+          else if (isElement(child) && !skipText.has(child.localName))
+            text += elementText(child);
+        }
+      };
+      if (el.shadowRoot)
+        add(el.shadowRoot);
+      add(el);
+    }
+    textCache.set(el, text);
+    return text;
+  };
+
+  const isVisible = el => {
+    const target = /^(option|optgroup)$/.test(el.localName) ? (el.closest('select') || el) : el;
+    const style = getComputedStyle(target);
+    if (style.visibility === 'hidden')
+      return false;
+    if (style.display === 'contents')
+      return childrenOf(target).some(isVisible);
+    const rect = target.getBoundingClientRect();
+    return rect.width > 0 && rect.height > 0;
+  };
+
+  // Hidden from assistive technology: getByRole skips these unless includeHidden is set.
+  const isHiddenForAria = el => {
+    for (let node = el; node; node = parentOf(node)) {
+      if (node.getAttribute('aria-hidden') === 'true')
+        return true;
+    }
+    const target = /^(option|optgroup)$/.test(el.localName) ? (el.closest('select') || el) : el;
+    const style = getComputedStyle(target);
+    if (style.display === 'contents')
+      return false;
+    if (typeof target.checkVisibility === 'function')
+      return !target.checkVisibility({ visibilityProperty: true });
+    return style.display === 'none' || style.visibility === 'hidden';
+  };
+
+  const inputRole = el => {
+    const type = (el.getAttribute('type') || 'text').toLowerCase();
+    if (type === 'hidden')
+      return null;
+    if (type === 'search')
+      return el.hasAttribute('list') ? 'combobox' : 'searchbox';
+    if (['email', 'tel', 'text', 'url', ''].includes(type))
+      return el.hasAttribute('list') ? 'combobox' : 'textbox';
+    if (type === 'file')
+      return 'button';
+    const roles = { button: 'button', checkbox: 'checkbox', image: 'button', number: 'spinbutton', radio: 'radio', range: 'slider', reset: 'button', submit: 'button' };
+    return roles[type] || 'textbox';
+  };
+
+  const hasExplicitName = el => !!(normalize(el.getAttribute('aria-label')) || el.getAttribute('aria-labelledby') || normalize(el.getAttribute('title')));
+  const sectioningAncestor = el => !!(parentOf(el) && parentOf(el).closest('article, aside, main, nav, section'));
+
+  const implicitRole = el => {
+    const tag = el.localName;
+    switch (tag) {
+      case 'a': case 'area': return el.hasAttribute('href') ? 'link' : null;
+      case 'article': return 'article';
+      case 'aside': return 'complementary';
+      case 'blockquote': return 'blockquote';
+      case 'button': return 'button';
+      case 'caption': return 'caption';
+      case 'code': return 'code';
+      case 'datalist': return 'listbox';
+      case 'dd': return 'definition';
+      case 'del': return 'deletion';
+      case 'details': return 'group';
+      case 'dfn': case 'dt': return 'term';
+      case 'dialog': return 'dialog';
+      case 'em': return 'emphasis';
+      case 'fieldset': return 'group';
+      case 'figure': return 'figure';
+      case 'footer': return sectioningAncestor(el) ? null : 'contentinfo';
+      case 'form': return hasExplicitName(el) ? 'form' : null;
+      case 'h1': case 'h2': case 'h3': case 'h4': case 'h5': case 'h6': return 'heading';
+      case 'header': return sectioningAncestor(el) ? null : 'banner';
+      case 'hr': return 'separator';
+      case 'html': return 'document';
+      case 'img': return el.getAttribute('alt') === '' && !el.getAttribute('title') ? 'presentation' : 'img';
+      case 'input': return inputRole(el);
+      case 'ins': return 'insertion';
+      case 'li': return 'listitem';
+      case 'main': return 'main';
+      case 'mark': return 'mark';
+      case 'math': return 'math';
+      case 'menu': case 'ol': case 'ul': return 'list';
+      case 'meter': return 'meter';
+      case 'nav': return 'navigation';
+      case 'optgroup': return 'group';
+      case 'option': return 'option';
+      case 'output': return 'status';
+      case 'p': return 'paragraph';
+      case 'progress': return 'progressbar';
+      case 'search': return 'search';
+      case 'section': return hasExplicitName(el) ? 'region' : null;
+      case 'select': return el.multiple || el.size > 1 ? 'listbox' : 'combobox';
+      case 'strong': return 'strong';
+      case 'sub': return 'subscript';
+      case 'sup': return 'superscript';
+      case 'svg': return 'img';
+      case 'table': return 'table';
+      case 'tbody': case 'tfoot': case 'thead': return 'rowgroup';
+      case 'td': {
+        const tableRole = el.closest('table') && el.closest('table').getAttribute('role');
+        return tableRole === 'grid' || tableRole === 'treegrid' ? 'gridcell' : 'cell';
+      }
+      case 'textarea': return 'textbox';
+      case 'th': return el.getAttribute('scope') === 'row' ? 'rowheader' : 'columnheader';
+      case 'time': return 'time';
+      case 'tr': return 'row';
+    }
+    return null;
+  };
+
+  const roleOf = el => {
+    const explicit = (el.getAttribute('role') || '').trim().split(/\s+/)[0].toLowerCase();
+    if (explicit)
+      return explicit === 'none' ? 'presentation' : explicit;
+    return implicitRole(el);
+  };
+
+  const textOfIds = (el, ids) => ids.trim().split(/\s+/).map(id => {
+    const root = el.getRootNode();
+    const target = (root.getElementById && root.getElementById(id)) || document.getElementById(id);
+    return target ? elementText(target) : '';
+  }).join(' ');
+
+  // Text of a <label>, without the labelled control itself.
+  const labelText = (label, control) => {
+    let text = '';
+    const visit = node => {
+      for (let child = node.firstChild; child; child = child.nextSibling) {
+        if (child === control)
+          continue;
+        if (child.nodeType === 3)
+          text += child.data;
+        else if (isElement(child) && !skipText.has(child.localName))
+          visit(child);
+      }
+    };
+    visit(label);
+    return text;
+  };
+
+  // Name computed from content (buttons, links, headings, ...): descendant text, alt texts and
+  // aria-labels, skipping hidden parts.
+  const contentText = el => {
+    let text = '';
+    const visit = node => {
+      for (let child = node.firstChild; child; child = child.nextSibling) {
+        if (child.nodeType === 3) {
+          text += child.data;
+          continue;
+        }
+        if (!isElement(child) || skipText.has(child.localName) || child.getAttribute('aria-hidden') === 'true')
+          continue;
+        const style = getComputedStyle(child);
+        if (style.display === 'none' || style.visibility === 'hidden')
+          continue;
+        const pad = style.display.startsWith('inline') || style.display === 'contents' ? '' : ' ';
+        const label = normalize(child.getAttribute('aria-label'));
+        if (label)
+          text += ' ' + label + ' ';
+        else if (child.localName === 'img')
+          text += ' ' + (child.getAttribute('alt') || '') + ' ';
+        else if (child.localName === 'input' && ['button', 'submit', 'reset'].includes(child.type))
+          text += ' ' + child.value + ' ';
+        else {
+          text += pad;
+          visit(child.shadowRoot || child);
+          text += pad;
+        }
+      }
+    };
+    visit(el.shadowRoot || el);
+    return text;
+  };
+
+  const nameFromContent = new Set(['button', 'cell', 'checkbox', 'columnheader', 'gridcell', 'heading', 'link', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'radio', 'row', 'rowheader', 'switch', 'tab', 'tooltip', 'treeitem']);
+
+  const accessibleName = (el, role) => {
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy) {
+      const text = normalize(textOfIds(el, labelledBy));
+      if (text)
+        return text;
+    }
+    const ariaLabel = normalize(el.getAttribute('aria-label'));
+    if (ariaLabel)
+      return ariaLabel;
+    const tag = el.localName;
+    if (tag === 'input' && ['button', 'submit', 'reset'].includes(el.type))
+      return normalize(el.value) || { submit: 'Submit', reset: 'Reset' }[el.type] || '';
+    if (tag === 'input' && el.type === 'image')
+      return normalize(el.getAttribute('alt')) || normalize(el.value) || 'Submit';
+    if (el.labels && el.labels.length) {
+      const text = normalize([...el.labels].map(label => labelText(label, el)).join(' '));
+      if (text)
+        return text;
+    }
+    if (tag === 'img' || tag === 'area') {
+      const alt = normalize(el.getAttribute('alt'));
+      if (alt)
+        return alt;
+    }
+    const captionTag = { fieldset: 'legend', table: 'caption', figure: 'figcaption' }[tag];
+    if (captionTag) {
+      const caption = [...el.children].find(child => child.localName === captionTag);
+      const text = caption ? normalize(contentText(caption)) : '';
+      if (text)
+        return text;
+    }
+    if (nameFromContent.has(role)) {
+      const text = normalize(contentText(el));
+      if (text)
+        return text;
+    }
+    const title = normalize(el.getAttribute('title'));
+    if (title)
+      return title;
+    if (tag === 'input' || tag === 'textarea')
+      return normalize(el.getAttribute('placeholder'));
+    return '';
+  };
+
+  const roleStates = {
+    checked: el => el.localName === 'input' && ['checkbox', 'radio'].includes(el.type) ? el.checked : (el.getAttribute('aria-checked') === 'mixed' ? 'mixed' : el.getAttribute('aria-checked') === 'true'),
+    disabled: el => !!el.disabled || !!el.closest('[aria-disabled=true]'),
+    expanded: el => el.getAttribute('aria-expanded') === 'true',
+    // Native heading levels win over aria-level, as in Playwright.
+    level: el => /^h[1-6]$/.test(el.localName) ? Number(el.localName[1]) : (Number(el.getAttribute('aria-level')) || 0),
+    pressed: el => el.getAttribute('aria-pressed') === 'mixed' ? 'mixed' : el.getAttribute('aria-pressed') === 'true',
+    selected: el => el.localName === 'option' ? el.selected : el.getAttribute('aria-selected') === 'true',
+  };
+
+  const byRole = (root, step) => {
+    const attrs = step.attrs || {};
+    return descendants(root).filter(el => {
+      if (roleOf(el) !== step.role)
+        return false;
+      if (!attrs.includeHidden && isHiddenForAria(el))
+        return false;
+      for (const [name, value] of Object.entries(attrs)) {
+        if (roleStates[name] && roleStates[name](el) !== value)
+          return false;
+      }
+      return step.name === undefined || matches(accessibleName(el, step.role), step.name, step.exact);
+    });
+  };
+
+  // getByText picks the smallest elements whose text matches.
+  const byText = (root, expected, exact) => {
+    const found = descendants(root).filter(el => !skipText.has(el.localName) && !el.closest('head') && matches(elementText(el), expected, exact));
+    const set = new Set(found);
+    return found.filter(el => !childrenOf(el).some(child => set.has(child)));
+  };
+
+  const labelsOf = el => {
+    const texts = [];
+    if (el.labels) {
+      for (const label of el.labels)
+        texts.push(labelText(label, el));
+    }
+    const labelledBy = el.getAttribute('aria-labelledby');
+    if (labelledBy)
+      texts.push(textOfIds(el, labelledBy));
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel)
+      texts.push(ariaLabel);
+    return texts;
+  };
+
+  const byCss = (root, selector) => {
+    const roots = [root, ...descendants(root).filter(el => el.shadowRoot).map(el => el.shadowRoot)];
+    return roots.flatMap(scope => [...scope.querySelectorAll(selector)]);
+  };
+
+  const byXPath = (root, expression) => {
+    if (isElement(root) && expression.startsWith('/'))
+      expression = '.' + expression;
+    const result = [];
+    const snapshot = document.evaluate(expression, root, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null);
+    for (let i = 0; i < snapshot.snapshotLength; i++) {
+      if (isElement(snapshot.snapshotItem(i)))
+        result.push(snapshot.snapshotItem(i));
+    }
+    return result;
+  };
+
+  const byAttribute = (root, name, expected, exact) => descendants(root).filter(el => el.hasAttribute(name) && matches(el.getAttribute(name), expected, exact));
+
+  const search = (root, step) => {
+    switch (step.t) {
+      case 'css': return byCss(root, step.v);
+      case 'xpath': return byXPath(root, step.v);
+      case 'role': return byRole(root, step);
+      case 'text': return byText(root, step.v, step.exact);
+      case 'label': return descendants(root).filter(el => labelsOf(el).some(text => matches(text, step.v, step.exact)));
+      case 'placeholder': return byAttribute(root, 'placeholder', step.v, step.exact);
+      case 'alt': return byAttribute(root, 'alt', step.v, step.exact);
+      case 'title': return byAttribute(root, 'title', step.v, step.exact);
+      case 'testid': return descendants(root).filter(el => {
+        const value = el.getAttribute(step.attr);
+        if (value === null)
+          return false;
+        return typeof step.v === 'object' ? new RegExp(step.v.source, step.v.flags).test(value) : value === step.v;
+      });
+    }
+    return undefined;
+  };
+
+  const searchKinds = new Set(['css', 'xpath', 'role', 'text', 'label', 'placeholder', 'alt', 'title', 'testid']);
+  const inDocumentOrder = list => list.sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING) ? -1 : 1);
+
+  // Search steps look below the current elements; filters apply to the current elements themselves
+  // (at the start that is the root, so a leading filter matches nothing, as in Playwright).
+  const resolve = (list, roots) => {
+    let current = roots;
+    let scopes = roots;
+    for (const step of list) {
+      if (step.t === 'frame')
+        throw new Error('testgen: frames are only supported in the main locator chain');
+      if (searchKinds.has(step.t)) {
+        scopes = current;
+        current = unique(current.flatMap(root => search(root, step)));
+        continue;
+      }
+      switch (step.t) {
+        case 'hasText':
+          current = current.filter(el => isElement(el) && matches(elementText(el), step.v, step.exact) !== !!step.not);
+          break;
+        case 'visible':
+          current = current.filter(el => isElement(el) && isVisible(el) === step.v);
+          break;
+        case 'has':
+          current = current.filter(el => (resolve(step.steps, [el]).length > 0) !== !!step.not);
+          break;
+        case 'nth': {
+          const index = step.v < 0 ? current.length + step.v : step.v;
+          current = index >= 0 && index < current.length ? [current[index]] : [];
+          break;
+        }
+        case 'and': {
+          const other = new Set(resolve(step.steps, scopes));
+          current = current.filter(el => other.has(el));
+          break;
+        }
+        case 'or':
+          current = inDocumentOrder(unique([...current, ...resolve(step.steps, scopes)]));
+          break;
+        default:
+          throw new Error('testgen: unknown locator step ' + JSON.stringify(step));
+      }
+    }
+    return current.filter(isElement);
+  };
+
+  return resolve(steps, [document]);
+}