refactor(codeceptq): build per-strategy XPath fragments

Replaces the post-hoc regex pre-resolver with strategy-level construction.
Each semantic locator (--click/--field/--checkable) is built as a list of
XPath branches; doc-wide subqueries (label[@for] resolution, ids by visible
text) are evaluated once and inlined as literal predicates instead of
sitting nested inside outer per-element predicates that the engine
re-executes on every match.

Eval loop runs each branch separately and sorts results by source offset
to preserve the document-order contract of XPath unions.

Github 'Sign up' --click: 9000ms → 264ms (independent of XPath engine —
fontoxpath benched the same as xpath@0.0.34 on the original union).
All 45 runner tests pass with identical line/snippet output.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: DavertMik

lib/command/query.js

@@ -14,40 +14,42 @@ export default async function query(locator, context, options = {}) {
     return
   }
 
-  let xpathExpr
-  let contextExpr = null
+  const { doc, source } = htmlToDoc(html)
+
+  let xpathBranches
+  let contextBranches = null
   try {
-    xpathExpr = buildXPath(locator, options)
-    if (context) contextExpr = buildXPath(context, {})
+    xpathBranches = buildXPaths(locator, options, doc)
+    if (context) contextBranches = buildXPaths(context, {}, doc)
   } catch (err) {
     console.error(`codeceptq: cannot build XPath: ${err.message}`)
     process.exitCode = 2
     return
   }
 
-  const { doc, source } = htmlToDoc(html)
-  xpathExpr = preresolveIdLookups(xpathExpr, doc)
-  if (contextExpr) contextExpr = preresolveIdLookups(contextExpr, doc)
+  const xpathExpr = xpathBranches.join(' | ')
+  const contextExpr = contextBranches ? contextBranches.join(' | ') : null
 
   let nodes
   try {
-    if (contextExpr) {
-      const ctxNodes = toArray(xpath.select(contextExpr, doc))
-      const seen = new Set()
-      nodes = []
-      for (const ctx of ctxNodes) {
-        for (const m of toArray(xpath.select(xpathExpr, ctx))) {
+    const contexts = contextBranches ? collectNodes(contextBranches, doc) : [doc]
+    const seen = new Set()
+    nodes = []
+    for (const ctx of contexts) {
+      for (const branch of xpathBranches) {
+        for (const m of toArray(xpath.select(branch, ctx))) {
           if (!seen.has(m)) {
             seen.add(m)
             nodes.push(m)
           }
         }
       }
-    } else {
-      nodes = toArray(xpath.select(xpathExpr, doc))
     }
+    // XPath unions return nodes in document order. We evaluate branches
+    // separately so re-sort by source position to match that contract.
+    nodes.sort((a, b) => (a.__startOffset ?? 0) - (b.__startOffset ?? 0))
   } catch (err) {
-    console.error(`codeceptq: XPath evaluation failed for "${xpathExpr}": ${err.message}`)
+    console.error(`codeceptq: XPath evaluation failed: ${err.message}`)
     process.exitCode = 2
     return
   }
@@ -99,42 +101,100 @@ export default async function query(locator, context, options = {}) {
   if (nodes.length === 0) process.exitCode = 1
 }
 
-function buildXPath(input, options) {
-  const literal = xpathLocator.literal(input)
-  if (options.field) return Locator.field.byText(literal)
-  if (options.click || options.clickable) return Locator.clickable.wide(literal)
-  if (options.checkable) return Locator.checkable.byText(literal)
+// Returns the array of XPath branches for a given input + options.
+// The semantic locators (--click/--field/--checkable) bake doc-wide subqueries
+// (label[@for] resolution, id-by-visible-text) into literal values so the
+// evaluator sees flat predicates. Without this, xpath npm re-evaluates each
+// inner //path per outer node — O(N²) on any non-trivial document.
+function buildXPaths(input, options, doc) {
+  const lit = xpathLocator.literal(input)
+
+  if (options.field) return fieldByText(input, doc)
+  if (options.click || options.clickable) return clickableWide(input, doc)
+  if (options.checkable) return checkableByText(input, doc)
   if (options.select) {
-    // Locator.select.byVisibleText is meant to be evaluated within a <select>
-    // context (`./option`). Rewrite to descendant-of-document for standalone use.
-    return Locator.select.byVisibleText(literal).replace(/\.\/(option|optgroup)/g, './/$1')
+    return [Locator.select.byVisibleText(lit).replace(/\.\/(option|optgroup)/g, './/$1')]
   }
 
-  if (options.xpath) return new Locator({ xpath: input }).toXPath()
-  if (options.css) return new Locator({ css: input }).toXPath()
+  if (options.xpath) return [new Locator({ xpath: input }).toXPath()]
+  if (options.css) return [new Locator({ css: input }).toXPath()]
 
   const loc = new Locator(input)
-  if (loc.type === 'fuzzy') {
-    return xpathLocator.combine([Locator.clickable.wide(literal), Locator.field.byText(literal)])
-  }
-  return loc.toXPath()
+  if (loc.type === 'fuzzy') return [...clickableWide(input, doc), ...fieldByText(input, doc)]
+  return [loc.toXPath()]
+}
+
+function clickableWide(text, doc) {
+  const lit = xpathLocator.literal(text)
+  const labelledIds = idsByVisibleText(doc, text)
+  const ariaLabelledBy = labelledIds.length ? `.//*[${anyAttrEquals('@aria-labelledby', labelledIds)}]` : null
+
+  return [
+    `.//a[./@href][((contains(normalize-space(string(.)), ${lit})) or .//img[contains(./@alt, ${lit})])]`,
+    `.//input[./@type = 'submit' or ./@type = 'image' or ./@type = 'button'][contains(./@value, ${lit})]`,
+    `.//input[./@type = 'image'][contains(./@alt, ${lit})]`,
+    `.//button[contains(normalize-space(string(.)), ${lit})]`,
+    `.//label[contains(normalize-space(string(.)), ${lit})]`,
+    `.//input[./@type = 'submit' or ./@type = 'image' or ./@type = 'button'][./@name = ${lit}]`,
+    `.//button[./@name = ${lit}]`,
+    `.//*[@aria-label = ${lit}]`,
+    `.//*[@title = ${lit}]`,
+    ariaLabelledBy,
+    `.//*[@role='button'][normalize-space(.)=${lit}]`,
+    `.//*[@role='tab' or @role='link' or @role='menuitem' or @role='menuitemcheckbox' or @role='menuitemradio' or @role='option' or @role='treeitem'][contains(normalize-space(string(.)), ${lit})]`,
+  ].filter(Boolean)
+}
+
+function fieldByText(text, doc) {
+  const lit = xpathLocator.literal(text)
+  const fieldGuard = `[self::input | self::textarea | self::select][not(./@type = 'submit' or ./@type = 'image' or ./@type = 'hidden')]`
+
+  const labelFors = labelForsByContainsText(doc, text)
+  const idMatch = labelFors.length ? ` or ${anyAttrEquals('./@id', labelFors)}` : ''
+
+  return [
+    `.//*${fieldGuard}[((./@name = ${lit}) or ./@placeholder = ${lit}${idMatch})]`,
+    `.//label[contains(normalize-space(string(.)), ${lit})]//.//*${fieldGuard}`,
+  ]
+}
+
+function checkableByText(text, doc) {
+  const lit = xpathLocator.literal(text)
+  const labelFors = labelForsByContainsText(doc, text)
+  const idMatch = labelFors.length ? `${anyAttrEquals('@id', labelFors)} or ` : ''
+
+  return [
+    `.//input[@type = 'checkbox' or @type = 'radio'][${idMatch}@placeholder = ${lit}]`,
+    `.//label[contains(normalize-space(string(.)), ${lit})]//input[@type = 'radio' or @type = 'checkbox']`,
+  ]
+}
+
+function idsByVisibleText(doc, text) {
+  const lit = xpathLocator.literal(text)
+  return toArray(xpath.select(`//*[@id][normalize-space(string(.)) = ${lit}]/@id`, doc)).map(a => a.value || '')
 }
 
-// `Locator.clickable.wide` and `Locator.field.labelContains` emit
-// `[@aria-labelledby = //*[@id][normalize-space(string(.)) = '...']/@id]`.
-// xpath@0.0.34 re-runs the inner //* scan once per outer match — O(N²) on
-// any non-trivial document. Pre-resolve the inner subquery to a literal so
-// the engine sees a flat attribute compare. Dropped a 2k-line github fixture
-// from 8500ms to ~50ms.
-function preresolveIdLookups(expr, doc) {
-  return expr.replace(
-    /\/\/\*\[@id\]\[normalize-space\(string\(\.\)\)\s*=\s*('[^']*'|"[^"]*")\]\/@id/g,
-    sub => {
-      const ids = toArray(xpath.select(sub, doc)).map(a => a.value || '')
-      if (ids.length === 0) return "'__codeceptq_no_match__'"
-      return `'${ids[0].replace(/'/g, '&apos;')}'`
+function labelForsByContainsText(doc, text) {
+  const lit = xpathLocator.literal(text)
+  return toArray(xpath.select(`//label[@for][contains(normalize-space(string(.)), ${lit})]/@for`, doc)).map(a => a.value || '')
+}
+
+function anyAttrEquals(lhs, values) {
+  return values.map(v => `${lhs} = ${xpathLocator.literal(v)}`).join(' or ')
+}
+
+function collectNodes(branches, ctx) {
+  const seen = new Set()
+  const out = []
+  for (const expr of branches) {
+    for (const n of toArray(xpath.select(expr, ctx))) {
+      if (!seen.has(n)) {
+        seen.add(n)
+        out.push(n)
+      }
     }
-  )
+  }
+  return out
 }
 
 function htmlToDoc(html) {