perf(locator): guard aria-labelledby branch with attr-existence predicate

The wide clickable / labelContains field XPath includes:
  .//*[@aria-labelledby = //*[@id][normalize-space(string(.)) = X]/@id]

That predicate forces every element to evaluate the inner //*[@id] subquery,
which is O(N²) on any non-trivial document for pure-JS XPath engines (xpath
npm: 7641ms on a 2k-line page; fontoxpath: 7057ms on the same branch).
Browser engines optimize via join-pushdown.

Adding [@aria-labelledby] as a left-to-right filter predicate first cuts
the slow comparison to only elements that actually have the attribute:

  .//*[@aria-labelledby][@aria-labelledby = //*[@id][...]/@id]

7641ms → 52ms (147×). Semantics identical: in XPath, [A][B] and [A and B]
produce the same result-set, but predicates are evaluated left-to-right,
so the cheap attr-existence check filters out the bulk first.

This is a single-character XPath change — codeceptq goes from 9000ms →
325ms on test/data/github.html with no special-case code. Reverted the
per-strategy reimplementation in lib/command/query.js (back to using
Locator.clickable.wide / Locator.field.byText directly).

Added two unit tests for the aria-labelledby branch in
Locator.clickable.wide (positive + negative).

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

Author: DavertMik

lib/command/query.js

@@ -14,42 +14,38 @@ export default async function query(locator, context, options = {}) {
     return
   }
 
-  const { doc, source } = htmlToDoc(html)
-
-  let xpathBranches
-  let contextBranches = null
+  let xpathExpr
+  let contextExpr = null
   try {
-    xpathBranches = buildXPaths(locator, options, doc)
-    if (context) contextBranches = buildXPaths(context, {}, doc)
+    xpathExpr = buildXPath(locator, options)
+    if (context) contextExpr = buildXPath(context, {})
   } catch (err) {
     console.error(`codeceptq: cannot build XPath: ${err.message}`)
     process.exitCode = 2
     return
   }
 
-  const xpathExpr = xpathBranches.join(' | ')
-  const contextExpr = contextBranches ? contextBranches.join(' | ') : null
+  const { doc, source } = htmlToDoc(html)
 
   let nodes
   try {
-    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 (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))) {
           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: ${err.message}`)
+    console.error(`codeceptq: XPath evaluation failed for "${xpathExpr}": ${err.message}`)
     process.exitCode = 2
     return
   }
@@ -101,100 +97,23 @@ export default async function query(locator, context, options = {}) {
   if (nodes.length === 0) process.exitCode = 1
 }
 
-// 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)
+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)
   if (options.select) {
-    return [Locator.select.byVisibleText(lit).replace(/\.\/(option|optgroup)/g, './/$1')]
+    return Locator.select.byVisibleText(literal).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 [...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 || '')
-}
-
-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)
-      }
-    }
+  if (loc.type === 'fuzzy') {
+    return xpathLocator.combine([Locator.clickable.wide(literal), Locator.field.byText(literal)])
   }
-  return out
+  return loc.toXPath()
 }
 
 function htmlToDoc(html) {

lib/locator.js

@@ -589,7 +589,7 @@ Locator.clickable = {
       `.//button[./@name = ${literal}]`,
       `.//*[@aria-label = ${literal}]`,
       `.//*[@title = ${literal}]`,
-      `.//*[@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id ]`,
+      `.//*[@aria-labelledby][@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id]`,
       `.//*[@role='button'][normalize-space(.)=${literal}]`,
       `.//*[@role='tab' or @role='link' or @role='menuitem' or @role='menuitemcheckbox' or @role='menuitemradio' or @role='option' or @role='treeitem'][contains(normalize-space(string(.)), ${literal})]`,
     ]),
@@ -632,7 +632,7 @@ Locator.field = {
       `.//label[contains(normalize-space(string(.)), ${literal})]//.//*[self::input | self::textarea | self::select][not(./@type = 'submit' or ./@type = 'image' or ./@type = 'hidden')]`,
       `.//*[@aria-label = ${literal}]`,
       `.//*[@title = ${literal}]`,
-      `.//*[@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id ]`,
+      `.//*[@aria-labelledby][@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id]`,
     ]),
 
   /**

test/unit/locator_test.js

@@ -766,6 +766,33 @@ describe('Locator', () => {
       expect(tabMatches[0].getAttribute('data-tab')).to.eql('description')
     })
 
+    it('matches an element labelled via aria-labelledby pointing at text', () => {
+      const xml = `<root>
+        <button id="open" aria-labelledby="lbl"></button>
+        <span id="lbl">Open dialog</span>
+        <button>Other</button>
+      </root>`
+      const xdoc = new DOMParser().parseFromString(xml, 'text/xml')
+      const root = xpath.select1('//root', xdoc)
+      const xp = Locator.clickable.wide("'Open dialog'")
+      const nodes = xpath.select(xp, root)
+      const buttons = nodes.filter(n => n.tagName === 'button' && n.getAttribute('id') === 'open')
+      expect(buttons).to.have.length(1, xp)
+    })
+
+    it('does not match elements without aria-labelledby when no other branch hits', () => {
+      const xml = `<root>
+        <span id="lbl">Some text</span>
+        <button>Unrelated</button>
+      </root>`
+      const xdoc = new DOMParser().parseFromString(xml, 'text/xml')
+      const root = xpath.select1('//root', xdoc)
+      const xp = Locator.clickable.wide("'Some text'")
+      const nodes = xpath.select(xp, root)
+      // No buttons or links match; only the <span> via .//label[contains...] won't fire either.
+      expect(nodes.filter(n => n.tagName === 'button')).to.have.length(0, xp)
+    })
+
     it('matches role="menuitem" by text', () => {
       const menuXml = `<root>
         <ul role="menu">