From 35d635778a0ddea36e012f885eaa5ae5862b6fef Mon Sep 17 00:00:00 2001
From: DavertMik <davert@testomat.io>
Date: Wed, 9 Sep 2026 03:09:31 +0300
Subject: [PATCH] refactor(locator): find ARIA checkables in Locator, not in
 each helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Locator.checkable already knows how to find a control by its label. It just
hard-coded the tag. Headless component libraries express the same semantics
with a role, so generalise the tag test to a tag-or-role test and skip
aria-hidden elements.

    self::input[@type='checkbox' or @type='radio']
      or @role='checkbox' or @role='radio' or @role='switch'

This replaces the three per-helper implementations added in #5704 — a
getByRole loop in Playwright, a role-scoped ::-p-aria loop in Puppeteer, and a
hoisted aria/ lookup plus keepCheckable filter in WebDriver — with one XPath
predicate that all three helpers inherit, since they all call
Locator.checkable.byText. Puppeteer's and WebDriver's ARIA fallbacks return to
their original position after the XPath.

An XPath predicate is role-scoped by construction, so there is no precision
trade-off to manage: a heading sharing the label text cannot match, and the
per-helper filtering that guarded against it is no longer needed.

The aria-hidden guard is what skips the hidden mirror input that libraries
render and point <label for> at, so the visible control is resolved instead.

Behaviour is unchanged for native controls: on existing fixtures the generated
XPath returns an identical node set.

Verified against real radix-ui@1.6.7 and @base-ui/react@1.8.0 components:
checkOption and seeCheckboxIsChecked work for Checkbox, Switch, Radio Group and
Checkbox Group on both libraries, standalone and inside a form.

Playwright 53 passing, Puppeteer 49 passing, WebDriver 41 passing (3 pending),
unit 815 + 81 locator, lint clean. Net -25 lines of library code.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TcwzSXPnfaig8nBZD2Vxfi
---
 lib/helper/Playwright.js  | 12 -----------
 lib/helper/Puppeteer.js   | 22 ++++++++------------
 lib/helper/WebDriver.js   | 30 ++++++++-------------------
 lib/locator.js            |  9 ++++++--
 test/unit/locator_test.js | 43 +++++++++++++++++++++++++++++++++++++++
 5 files changed, 67 insertions(+), 49 deletions(-)

diff --git a/lib/helper/Playwright.js b/lib/helper/Playwright.js
index c4cabf115..91f90bffd 100644
--- a/lib/helper/Playwright.js
+++ b/lib/helper/Playwright.js
@@ -50,7 +50,6 @@ let defaultSelectorEnginesInitialized = false
 const popupStore = new Popup()
 const consoleLogStore = new Console()
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron']
-const checkableRoles = ['checkbox', 'radio', 'switch']
 
 import { setRestartStrategy, restartsSession, restartsContext, restartsBrowser } from './extras/PlaywrightRestartOpts.js'
 import { createValueEngine, createDisabledEngine } from './extras/PlaywrightPropEngine.js'
@@ -4389,17 +4388,6 @@ async function findCheckable(locator, context) {
     return findElements.call(this, contextEl, matchedLocator)
   }
 
-  for (const exact of [true, false]) {
-    for (const role of checkableRoles) {
-      try {
-        const roleEls = await contextEl.getByRole(role, { name: matchedLocator.value, exact }).all()
-        if (roleEls.length) return roleEls
-      } catch (err) {
-        // getByRole not supported or failed
-      }
-    }
-  }
-
   const literal = xpathLocator.literal(matchedLocator.value)
   let els = await findElements.call(this, contextEl, Locator.checkable.byText(literal))
   if (els.length) {
diff --git a/lib/helper/Puppeteer.js b/lib/helper/Puppeteer.js
index 7e147e757..3d1f7a02e 100644
--- a/lib/helper/Puppeteer.js
+++ b/lib/helper/Puppeteer.js
@@ -64,7 +64,6 @@ function wrapError(e) {
 let perfTiming
 const popupStore = new Popup()
 const consoleLogStore = new Console()
-const checkableRoles = ['checkbox', 'radio', 'switch']
 
 /**
  * ## Configuration
@@ -3196,19 +3195,8 @@ async function findCheckable(locator, context) {
     return findElements.call(this, contextEl, matchedLocator)
   }
 
-  // Try ARIA selector for accessible name
-  let els
-  for (const role of checkableRoles) {
-    try {
-      els = await contextEl.$$(`::-p-aria([name="${matchedLocator.value}"][role="${role}"])`)
-      if (els.length) return els
-    } catch (err) {
-      // ARIA selector not supported or failed
-    }
-  }
-
   const literal = xpathLocator.literal(matchedLocator.value)
-  els = await findElements.call(this, contextEl, Locator.checkable.byText(literal))
+  let els = await findElements.call(this, contextEl, Locator.checkable.byText(literal))
   if (els.length) {
     return els
   }
@@ -3217,6 +3205,14 @@ async function findCheckable(locator, context) {
     return els
   }
 
+  // Try ARIA selector for accessible name
+  try {
+    els = await contextEl.$$(`::-p-aria(${matchedLocator.value})`)
+    if (els.length) return els
+  } catch (err) {
+    // ARIA selector not supported or failed
+  }
+
   return findElements.call(this, contextEl, matchedLocator.value)
 }
 
diff --git a/lib/helper/WebDriver.js b/lib/helper/WebDriver.js
index a52d85d9d..1d12b7f41 100644
--- a/lib/helper/WebDriver.js
+++ b/lib/helper/WebDriver.js
@@ -3248,14 +3248,6 @@ async function findCheckable(locator, locateFn) {
   if (locator.isRole()) return locateFn(locator, true)
   if (!locator.isFuzzy()) return locateFn(locator, true)
 
-  // Try ARIA selector for accessible name
-  try {
-    els = await keepCheckable.call(this, await locateFn(`aria/${locator.value}`))
-    if (els.length) return els
-  } catch (e) {
-    // ARIA selector not supported or failed
-  }
-
   const literal = xpathLocator.literal(locator.value)
   els = await locateFn(Locator.checkable.byText(literal))
   if (els.length) return els
@@ -3263,23 +3255,17 @@ async function findCheckable(locator, locateFn) {
   els = await locateFn(Locator.checkable.byName(literal))
   if (els.length) return els
 
+  // Try ARIA selector for accessible name
+  try {
+    els = await locateFn(`aria/${locator.value}`)
+    if (els.length) return els
+  } catch (e) {
+    // ARIA selector not supported or failed
+  }
+
   return await locateFn(locator.value) // by css or xpath
 }
 
-async function keepCheckable(els) {
-  if (!els || !els.length) return []
-
-  const checkable = await this.browser.execute(function () {
-    return Array.prototype.slice.call(arguments).map(function (el) {
-      if (!el) return false
-      const role = el.getAttribute('role')
-      if (role) return ['checkbox', 'radio', 'switch'].indexOf(role) > -1
-      return el.tagName === 'INPUT' && (el.type === 'checkbox' || el.type === 'radio')
-    })
-  }, ...els)
-
-  return els.filter((el, index) => checkable[index])
-}
 
 function withStrictLocator(locator) {
   locator = new Locator(locator)
diff --git a/lib/locator.js b/lib/locator.js
index 6a47b71d2..913fdd2dd 100644
--- a/lib/locator.js
+++ b/lib/locator.js
@@ -649,6 +649,9 @@ Locator.field = {
     ]),
 }
 
+const checkable = `self::input[@type = 'checkbox' or @type = 'radio'] or @role = 'checkbox' or @role = 'radio' or @role = 'switch'`
+const visibleCheckable = `.//*[${checkable}][not(@aria-hidden = 'true')]`
+
 Locator.checkable = {
   /**
    * @param {string} literal
@@ -656,8 +659,10 @@ Locator.checkable = {
    */
   byText: literal =>
     xpathLocator.combine([
-      `.//input[@type = 'checkbox' or @type = 'radio'][(@id = //label[@for][contains(normalize-space(string(.)), ${literal})]/@for) or @placeholder = ${literal}]`,
-      `.//label[contains(normalize-space(string(.)), ${literal})]//input[@type = 'radio' or @type = 'checkbox']`,
+      `${visibleCheckable}[(@id = //label[@for][contains(normalize-space(string(.)), ${literal})]/@for) or @placeholder = ${literal}]`,
+      `.//label[contains(normalize-space(string(.)), ${literal})]//*[${checkable}][not(@aria-hidden = 'true')]`,
+      `${visibleCheckable}[@aria-labelledby = //*[@id][contains(normalize-space(string(.)), ${literal})]/@id]`,
+      `${visibleCheckable}[@aria-label = ${literal}]`,
     ]),
 
   /**
diff --git a/test/unit/locator_test.js b/test/unit/locator_test.js
index 9c59216ae..706ddc4ca 100644
--- a/test/unit/locator_test.js
+++ b/test/unit/locator_test.js
@@ -808,4 +808,47 @@ describe('Locator', () => {
       expect(items[0].getAttribute('id')).to.eql('rename')
     })
   })
+
+  describe('Locator.checkable.byText', () => {
+    const select = (xml, literal) => {
+      const doc = new DOMParser().parseFromString(xml, 'text/xml')
+      return xpath.select(Locator.checkable.byText(literal), xpath.select1('//root', doc))
+    }
+
+    it('matches a native input labelled by label[for]', () => {
+      const nodes = select('<root><input type="checkbox" id="a"/><label for="a">I Agree</label></root>', "'I Agree'")
+      expect(nodes).to.have.length(1)
+      expect(nodes[0].getAttribute('id')).to.eql('a')
+    })
+
+    it('matches a role=checkbox labelled by label[for]', () => {
+      const nodes = select('<root><button role="checkbox" id="a"></button><label for="a">Accept terms</label></root>', "'Accept terms'")
+      expect(nodes).to.have.length(1)
+      expect(nodes[0].tagName).to.eql('button')
+    })
+
+    it('matches a role=switch labelled by aria-labelledby', () => {
+      const nodes = select('<root><span role="switch" aria-labelledby="l"></span><label id="l">Airplane mode</label></root>', "'Airplane mode'")
+      expect(nodes).to.have.length(1)
+      expect(nodes[0].getAttribute('role')).to.eql('switch')
+    })
+
+    it('matches a role=radio named by aria-label', () => {
+      const nodes = select('<root><span role="radio" aria-label="Compact"></span></root>', "'Compact'")
+      expect(nodes).to.have.length(1)
+      expect(nodes[0].getAttribute('role')).to.eql('radio')
+    })
+
+    it('resolves the visible control, not the aria-hidden input the label points at', () => {
+      const xml =
+        '<root>' +
+        '<span role="checkbox" aria-labelledby="l" id="visible"></span>' +
+        '<input type="checkbox" id="mirror" aria-hidden="true"/>' +
+        '<label for="mirror" id="l">Accept terms</label>' +
+        '</root>'
+      const nodes = select(xml, "'Accept terms'")
+      expect(nodes).to.have.length(1)
+      expect(nodes[0].getAttribute('id')).to.eql('visible')
+    })
+  })
 })