feat(Playwright): visibleLocator config option

Appends Playwright's locator.visible() (1.63+) to locators, so actions
match only visible elements. Resolved per step: stepOpts({ visibleLocator })
overrides the helper config, following exact/strictMode/elementIndex.

seeElementInDOM, dontSeeElementInDOM and seeNumberOfElements opt out by
setting the step option, since they assert DOM presence regardless of
visibility.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D6RydiYkagn6C8Pts2Leou

Author: DavertMik

docs/helpers/Playwright.md

@@ -78,8 +78,9 @@ Type: [object][6]
 *   `ignoreHTTPSErrors` **[boolean][27]?** Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
 *   `bypassCSP` **[boolean][27]?** bypass Content Security Policy or CSP
 *   `highlightElement` **[boolean][27]?** highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+*   `visibleLocator` **[boolean][27]?** append [`visible()`][49] to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`, which check the DOM regardless of visibility. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
 *   `recordHar` **[object][6]?** record HAR and will be saved to `output/har`. See more of [HAR options][3].
-*   `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][49].
+*   `testIdAttribute` **[string][9]?** locate elements based on the testIdAttribute. See more of [locate by test id][50].
 *   `storageState` **([string][9] | [object][6])?** Playwright storage state (path to JSON file or object)
     passed directly to `browser.newContext`.
     If a Scenario is declared with a `cookies` option (e.g. `Scenario('name', { cookies: [...] }, fn)`),
@@ -97,6 +98,7 @@ Returns elements array if role locator, null otherwise
 
 *   `context`  
 *   `locator`  
+*   `visible`  
 
 
 
@@ -2967,4 +2969,6 @@ Returns **void** automatically synchronized promise through #recorder
 
 [48]: https://playwright.dev/docs/api/class-consolemessage#console-message-type
 
-[49]: https://playwright.dev/docs/locators#locate-by-test-id
+[49]: https://playwright.dev/docs/api/class-locator#locator-visible
+
+[50]: https://playwright.dev/docs/locators#locate-by-test-id

lib/helper/Playwright.js

@@ -101,6 +101,7 @@ const pathSeparator = path.sep
  * @prop {boolean} [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
  * @prop {boolean} [bypassCSP] - bypass Content Security Policy or CSP
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+ * @prop {boolean} [visibleLocator=false] - append [`visible()`](https://playwright.dev/docs/api/class-locator#locator-visible) to locators, so only visible elements are matched. Requires Playwright 1.63 or newer. Switch it off for a single step with `stepOpts({ visibleLocator: false })`. Not applied to `dragAndDrop`, which passes selectors to Playwright directly, nor to `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`, which check the DOM regardless of visibility. When enabled, a locator matching only hidden elements fails as "element not found" instead of timing out on actionability, `strict` mode ignores hidden duplicates, and elements hidden by CSS (like a custom checkbox built on a visually hidden `input`) are no longer found.
  * @prop {object} [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
  * @prop {string} [testIdAttribute=data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
  * @prop {string|object} [storageState] - Playwright storage state (path to JSON file or object)
@@ -398,6 +399,7 @@ class Playwright extends Helper {
       storageState: undefined,
       onResponse: null,
       strict: false,
+      visibleLocator: false,
     }
 
     process.env.testIdAttribute = 'data-testid'
@@ -2008,6 +2010,7 @@ class Playwright extends Helper {
    * {{> seeElementInDOM }}
    */
   async seeElementInDOM(locator) {
+    disableVisibleLocatorForStep()
     const els = await this._locate(locator)
     try {
       return empty('elements on page').negate(els.filter(v => v).fill('ELEMENT'))
@@ -2020,6 +2023,7 @@ class Playwright extends Helper {
    * {{> dontSeeElementInDOM }}
    */
   async dontSeeElementInDOM(locator) {
+    disableVisibleLocatorForStep()
     const els = await this._locate(locator)
     try {
       return empty('elements on a page').assert(els.filter(v => v).fill('ELEMENT'))
@@ -2397,11 +2401,12 @@ class Playwright extends Helper {
     // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
     const comboboxSearchCtx = contextEl || pageContext
-    let els = await findByRole(comboboxSearchCtx, { role: 'combobox', name: matchedLocator.value })
+    const visible = useVisibleLocator(this)
+    let els = await findByRole(comboboxSearchCtx, { role: 'combobox', name: matchedLocator.value }, visible)
     if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try listbox
-    els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value })
+    els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value }, visible)
     if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try native select
@@ -2546,6 +2551,7 @@ class Playwright extends Helper {
    *
    */
   async seeNumberOfElements(locator, num) {
+    disableVisibleLocatorForStep()
     const elements = await this._locate(locator)
     return equals(`expected number of elements (${new Locator(locator)}) is ${num}, but found ${elements.length}`).assert(elements.length, num)
   }
@@ -4192,12 +4198,29 @@ export function buildLocatorString(locator) {
   return locator.simplify()
 }
 
+function disableVisibleLocatorForStep() {
+  const opts = store.currentStep?.opts
+  if (opts && opts.visibleLocator === undefined) opts.visibleLocator = false
+}
+
+function useVisibleLocator(helper) {
+  return store.currentStep?.opts?.visibleLocator ?? helper.options.visibleLocator
+}
+
+export function withVisibleLocator(locator, enabled) {
+  if (!enabled) return locator
+  if (typeof locator.visible !== 'function') {
+    throw new Error('visibleLocator option requires Playwright 1.63 or newer. Upgrade the playwright package or disable visibleLocator in helper config')
+  }
+  return locator.visible()
+}
+
 /**
  * Handles role locator objects by converting them to Playwright's getByRole() API
  * Accepts both raw objects ({role: 'button', text: 'Submit'}) and Locator-wrapped role objects.
  * Returns elements array if role locator, null otherwise
  */
-async function handleRoleLocator(context, locator) {
+async function handleRoleLocator(context, locator, visible) {
   const loc = new Locator(locator)
   if (!loc.isRole()) return null
 
@@ -4207,31 +4230,32 @@ async function handleRoleLocator(context, locator) {
   if (roleObj.name) options.name = roleObj.name
   if (roleObj.exact !== undefined) options.exact = roleObj.exact
 
-  return context.getByRole(roleObj.role, Object.keys(options).length > 0 ? options : undefined).all()
+  return withVisibleLocator(context.getByRole(roleObj.role, Object.keys(options).length > 0 ? options : undefined), visible).all()
 }
 
-async function findByRole(context, locator) {
+async function findByRole(context, locator, visible) {
   if (!locator || !locator.role) return null
   const options = {}
   if (locator.name) options.name = locator.name
   if (locator.exact !== undefined) options.exact = locator.exact
-  return context.getByRole(locator.role, Object.keys(options).length > 0 ? options : undefined).all()
+  return withVisibleLocator(context.getByRole(locator.role, Object.keys(options).length > 0 ? options : undefined), visible).all()
 }
 
 async function findElements(matcher, locator) {
+  const visible = useVisibleLocator(this)
   const isPwLocator = locator.type === 'pw' || (locator.locator && locator.locator.pw) || locator.pw
 
-  if (isPwLocator) return findByPlaywrightLocator.call(this, matcher, locator)
+  if (isPwLocator) return findByPlaywrightLocator.call(this, matcher, locator, visible)
 
   // Handle role locators with text/exact options (e.g., {role: 'button', text: 'Submit', exact: true})
-  const roleElements = await handleRoleLocator(matcher, locator)
+  const roleElements = await handleRoleLocator(matcher, locator, visible)
   if (roleElements) return roleElements
 
   locator = new Locator(locator, 'css')
 
   const locatorString = buildLocatorString(locator)
 
-  return matcher.locator(locatorString).all()
+  return withVisibleLocator(matcher.locator(locatorString), visible).all()
 }
 
 async function findElement(matcher, locator) {
@@ -4306,16 +4330,17 @@ async function findClickable(matcher, locator) {
 
   let els
   const literal = xpathLocator.literal(matchedLocator.value)
+  const visible = useVisibleLocator(this)
 
   try {
-    els = await matcher.getByRole('button', { name: matchedLocator.value }).all()
+    els = await withVisibleLocator(matcher.getByRole('button', { name: matchedLocator.value }), visible).all()
     if (els.length) return els
   } catch (err) {
     // getByRole not supported or failed
   }
 
   try {
-    els = await matcher.getByRole('link', { name: matchedLocator.value }).all()
+    els = await withVisibleLocator(matcher.getByRole('link', { name: matchedLocator.value }), visible).all()
     if (els.length) return els
   } catch (err) {
     // getByRole not supported or failed
@@ -4376,7 +4401,7 @@ async function findCheckable(locator, context) {
   }
 
   // Handle role locators with text/exact options
-  const roleElements = await handleRoleLocator(contextEl, locator)
+  const roleElements = await handleRoleLocator(contextEl, locator, useVisibleLocator(this))
   if (roleElements) return roleElements
 
   const matchedLocator = new Locator(locator)
@@ -4417,7 +4442,7 @@ async function findFields(locator, context = null) {
     : loc => this._locate(loc)
 
   const matcher = contextEl || (await this.page)
-  const roleElements = await handleRoleLocator(matcher, locator)
+  const roleElements = await handleRoleLocator(matcher, locator, useVisibleLocator(this))
   if (roleElements) return roleElements
 
   const matchedLocator = new Locator(locator)

lib/helper/extras/PlaywrightLocator.js

@@ -1,10 +1,12 @@
-async function findByPlaywrightLocator(matcher, locator) {
+import { withVisibleLocator } from '../Playwright.js'
+
+async function findByPlaywrightLocator(matcher, locator, visible) {
   const pwLocator = locator.locator || locator
   if (pwLocator && pwLocator.toString && pwLocator.toString().includes(process.env.testIdAttribute)) {
     return matcher.getByTestId(pwLocator.pw.value.split('=')[1])
   }
   const pwValue = typeof pwLocator.pw === 'string' ? pwLocator.pw : pwLocator.pw
-  return matcher.locator(pwValue).all()
+  return withVisibleLocator(matcher.locator(pwValue), visible).all()
 }
 
 export { findByPlaywrightLocator }

lib/step/config.js

@@ -4,6 +4,7 @@
  * @property {boolean} [exact] - Enable strict mode for this step. Throws if multiple elements match.
  * @property {boolean} [strictMode] - Alias for exact.
  * @property {boolean} [ignoreCase] - Perform case-insensitive text matching.
+ * @property {boolean} [visibleLocator] - Match only visible elements. Overrides the Playwright helper `visibleLocator` config option for this step.
  */
 
 /**

package.json

@@ -177,7 +177,7 @@
     "jsdoc": "^3.6.11",
     "jsdoc-typeof-plugin": "1.0.0",
     "json-server": "0.17.4",
-    "playwright": "^1.59.0",
+    "playwright": "^1.63.0",
     "prettier": "^3.3.2",
     "puppeteer": "24.36.0",
     "qrcode-terminal": "0.12.0",

test/helper/webapi.js

@@ -2799,4 +2799,98 @@ export function tests() {
       await I.click('#grab-multiple a')
     })
   })
+
+  describe('#visibleLocator step option', () => {
+    beforeEach(function () {
+      if (!isHelper('Playwright')) this.skip()
+    })
+
+    afterEach(() => {
+      store.currentStep = null
+      I.options.visibleLocator = false
+      I.options.strict = false
+    })
+
+    it('should match hidden elements when disabled', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.strict = true
+      let err
+      try {
+        await I.click({ css: 'button' })
+      } catch (e) {
+        err = e
+      }
+      expect(err).to.exist
+      expect(err.constructor.name).to.equal('MultipleElementsFound')
+    })
+
+    it('should match only visible elements when enabled in config', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.visibleLocator = true
+      I.options.strict = true
+      await I.click({ css: 'button' })
+    })
+
+    it('should be enabled for a single step', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.strict = true
+      store.currentStep = { opts: { visibleLocator: true } }
+      await I.click({ css: 'button' })
+    })
+
+    it('should be disabled for a single step', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.visibleLocator = true
+      I.options.strict = true
+      store.currentStep = { opts: { visibleLocator: false } }
+      let err
+      try {
+        await I.click({ css: 'button' })
+      } catch (e) {
+        err = e
+      }
+      expect(err).to.exist
+      expect(err.constructor.name).to.equal('MultipleElementsFound')
+    })
+
+    it('should not find elements which are all hidden', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.visibleLocator = true
+      let err
+      try {
+        await I.click({ css: 'button[style]' })
+      } catch (e) {
+        err = e
+      }
+      expect(err).to.exist
+      expect(err.message).to.include('Clickable element')
+      expect(err.message).to.include('was not found')
+    })
+
+    it('should keep DOM assertions unaffected', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.visibleLocator = true
+      store.currentStep = { opts: {} }
+      await I.seeElementInDOM({ css: 'button[style]' })
+      await I.seeNumberOfElements('button', 3)
+      store.currentStep = { opts: {} }
+      await I.dontSeeElementInDOM({ css: 'button[data-missing]' })
+    })
+
+    it('should select from a custom combobox', async () => {
+      await I.amOnPage('/form/custom_select')
+      I.options.visibleLocator = true
+      await I.selectOption('Country', 'Porto')
+      await I.see('country: pt', '#result')
+    })
+
+    it('should interact with fields and checkboxes', async () => {
+      await I.amOnPage('/invisible_elements')
+      I.options.visibleLocator = true
+      await I.checkOption('#ts')
+      await I.seeCheckboxIsChecked('#ts')
+      await I.fillField('#basic', 'Pascal')
+      await I.seeInField('#basic', 'Pascal')
+    })
+  })
 }