codeceptjs 4.2.0-beta.1 → 4.2.0-beta.2

package/docs/advanced.md

@@ -79,7 +79,7 @@ Data(function*() {
 }).Scenario() // ...
 ```
 
-*HINT: If you don't use DataTable. add `toString()` method to each object added to data set, so the data could be pretty printed in a test name*
+Objects in a data set are serialized as JSON in the test name.
 
 
 ## Debug

package/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)`),
@@ -2967,4 +2968,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

package/lib/data/context.js

@@ -72,13 +72,11 @@ function replaceTitle(title, dataRow) {
     return `${title} | ${dataRow.data.getMasked()}`
   }
 
-  // if `dataRow` is object and has own `toString()` method,
-  // it should be printed
-  if (Object.prototype.toString.call(dataRow.data) === Object().toString() && dataRow.data.toString() !== Object().toString()) {
-    return `${title} | ${dataRow.data}`
-  }
+  return `${title} | ${JSON.stringify(dataRow.data, maskSecret)}`
+}
 
-  return `${title} | ${JSON.stringify(dataRow.data)}`
+function maskSecret(key, value) {
+  return typeof value?.getMasked === 'function' ? value.getMasked() : value
 }
 
 function isTableDataRow(row) {

package/lib/helper/Playwright.js

@@ -50,6 +50,7 @@ let defaultSelectorEnginesInitialized = false
 const popupStore = new Popup()
 const consoleLogStore = new Console()
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron']
+const domPresenceSteps = ['seeElementInDOM', 'dontSeeElementInDOM', 'seeNumberOfElements']
 const checkableRoles = ['checkbox', 'radio', 'switch']
 
 import { setRestartStrategy, restartsSession, restartsContext, restartsBrowser } from './extras/PlaywrightRestartOpts.js'
@@ -102,6 +103,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)
@@ -399,6 +401,7 @@ class Playwright extends Helper {
       storageState: undefined,
       onResponse: null,
       strict: false,
+      visibleLocator: false,
     }
 
     process.env.testIdAttribute = 'data-testid'
@@ -555,6 +558,10 @@ class Playwright extends Helper {
     }
   }
 
+  _beforeStep(step) {
+    store.visibleLocator = step.opts?.visibleLocator ?? (this.options.visibleLocator && !domPresenceSteps.includes(step.helperMethod))
+  }
+
   async _before(test) {
     // Skip browser operations in dry-run mode (used by check command)
     if (store.dryRun) {
@@ -4197,6 +4204,14 @@ export function buildLocatorString(locator) {
   return locator.simplify()
 }
 
+function withVisibleLocator(locator) {
+  if (!store.visibleLocator) 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.
@@ -4212,7 +4227,7 @@ 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)).all()
 }
 
 async function findByRole(context, locator) {
@@ -4220,13 +4235,13 @@ async function findByRole(context, locator) {
   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)).all()
 }
 
 async function findElements(matcher, locator) {
   const isPwLocator = locator.type === 'pw' || (locator.locator && locator.locator.pw) || locator.pw
 
-  if (isPwLocator) return findByPlaywrightLocator.call(this, matcher, locator)
+  if (isPwLocator) return withVisibleLocator(findByPlaywrightLocator.call(this, matcher, locator)).all()
 
   // Handle role locators with text/exact options (e.g., {role: 'button', text: 'Submit', exact: true})
   const roleElements = await handleRoleLocator(matcher, locator)
@@ -4236,11 +4251,11 @@ async function findElements(matcher, locator) {
 
   const locatorString = buildLocatorString(locator)
 
-  return matcher.locator(locatorString).all()
+  return withVisibleLocator(matcher.locator(locatorString)).all()
 }
 
 async function findElement(matcher, locator) {
-  if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
+  if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator).first()
 
   locator = new Locator(locator, 'css')
 
@@ -4313,14 +4328,14 @@ async function findClickable(matcher, locator) {
   const literal = xpathLocator.literal(matchedLocator.value)
 
   try {
-    els = await matcher.getByRole('button', { name: matchedLocator.value }).all()
+    els = await withVisibleLocator(matcher.getByRole('button', { name: matchedLocator.value })).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 })).all()
     if (els.length) return els
   } catch (err) {
     // getByRole not supported or failed
@@ -4389,17 +4404,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) {

package/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)
 }
 

package/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)

package/lib/helper/errors/MultipleElementsFound.js

@@ -1,5 +1,60 @@
 import Locator from '../../locator.js'
 
+export function splitXPath(xpath) {
+  if (typeof xpath !== 'string' || xpath.length === 0) return []
+  const withoutRoot = xpath.startsWith('//') ? xpath.slice(1) : xpath
+  return withoutRoot.split('/').filter(Boolean)
+}
+
+export function isAncestorXPath(ancestor, descendant) {
+  if (!ancestor || !descendant || ancestor === descendant) return false
+  const ancestorSegments = splitXPath(ancestor)
+  const descendantSegments = splitXPath(descendant)
+  if (ancestorSegments.length === 0 || ancestorSegments.length >= descendantSegments.length) return false
+  return ancestorSegments.every((segment, index) => segment === descendantSegments[index])
+}
+
+export function computeParents(entries) {
+  const parents = new Array(entries.length).fill(-1)
+  const stack = []
+  for (let i = 0; i < entries.length; i++) {
+    const xpath = entries[i].xpath
+    if (!xpath) continue
+    while (stack.length > 0 && !isAncestorXPath(entries[stack[stack.length - 1]].xpath, xpath)) {
+      stack.pop()
+    }
+    parents[i] = stack.length > 0 ? stack[stack.length - 1] : -1
+    stack.push(i)
+  }
+  return parents
+}
+
+export function computeDepths(entries) {
+  const parents = computeParents(entries)
+  return parents.map((parent, i) => {
+    if (!entries[i].xpath) return 0
+    let depth = 0
+    let current = parent
+    while (current !== -1) {
+      depth++
+      current = parents[current]
+    }
+    return depth
+  })
+}
+
+export function formatTree(entries, depths, parents) {
+  return entries.map((entry, i) => {
+    const pad = '  '.repeat(depths[i] || 0)
+    if (entry.error) {
+      return `${pad}  ${entry.index}. [Unable to get element info: ${entry.error}]`
+    }
+    const parentPos = parents ? parents[i] : -1
+    const nesting = parentPos !== undefined && parentPos !== -1 ? ` (inside ${entries[parentPos].index}.)` : ''
+    return `${pad}  ${entry.index}.${nesting} > ${entry.xpath}\n${pad}     ${entry.html}`
+  })
+}
+
 class MultipleElementsFound extends Error {
   constructor(locator, webElements) {
     const locatorStr = (typeof locator === 'object' && !(locator instanceof Locator))
@@ -17,7 +72,7 @@ class MultipleElementsFound extends Error {
     if (this._detailsFetched) return
 
     try {
-      const items = []
+      const entries = []
       const maxToShow = Math.min(this.count, 10)
 
       for (let i = 0; i < maxToShow; i++) {
@@ -25,12 +80,14 @@ class MultipleElementsFound extends Error {
         try {
           const xpath = await webEl.toAbsoluteXPath()
           const html = await webEl.toSimplifiedHTML()
-          items.push(`  ${i + 1}. > ${xpath}\n     ${html}`)
+          entries.push({ index: i + 1, xpath, html })
         } catch (err) {
-          items.push(`  ${i + 1}. [Unable to get element info: ${err.message}]`)
+          entries.push({ index: i + 1, error: err.message })
         }
       }
 
+      const items = formatTree(entries, computeDepths(entries), computeParents(entries))
+
       if (this.count > 10) {
         items.push(`  ... and ${this.count - 10} more`)
       }

package/lib/helper/extras/PlaywrightLocator.js

@@ -1,10 +1,10 @@
-async function findByPlaywrightLocator(matcher, locator) {
+function findByPlaywrightLocator(matcher, locator) {
   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 matcher.locator(pwValue)
 }
 
 export { findByPlaywrightLocator }

package/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}]`,
     ]),
 
   /**

package/lib/mocha/asyncWrapper.js

@@ -4,7 +4,7 @@ import recorder from '../recorder.js'
 import assertThrown from '../assert/throws.js'
 import { ucfirst, isAsyncFunction } from '../utils.js'
 import { getInjectedArguments } from './inject.js'
-import { fireHook } from './hooks.js'
+import { fireHook, BeforeSuiteHook, AfterSuiteHook } from './hooks.js'
 
 const injectHook = function (inject, suite) {
   try {
@@ -232,6 +232,10 @@ export function suiteSetup(suite) {
 
     // Set up error handler for suite setup
     recorder.errHandler(err => {
+      // A helper's `_beforeSuite()` runs through this hook, not through the
+      // `injected()` wrapper, so nothing here used to emit `hook.failed` and
+      // reporters listening for it never saw the failure. (#5660)
+      event.emit(event.hook.failed, new BeforeSuiteHook(suite, err))
       doneFn(err)
     })
 
@@ -254,6 +258,8 @@ export function suiteTeardown(suite) {
 
     // Set up error handler for suite teardown
     recorder.errHandler(err => {
+      // Same for a helper's `_afterSuite()`. (#5660)
+      event.emit(event.hook.failed, new AfterSuiteHook(suite, err))
       doneFn(err)
     })
 

package/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/lib/store.js

@@ -93,6 +93,12 @@ const store = {
   /** @type {CodeceptJS.Suite | null} */
   currentSuite: null,
 
+  /**
+   * Locators match only visible elements, resolved per step
+   * @type {boolean}
+   */
+  visibleLocator: false,
+
   /** @type {Map<string, string> | null} */
   tsFileMapping: null,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.2.0-beta.1",
+  "version": "4.2.0-beta.2",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
@@ -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",

package/typings/promiseBasedTypes.d.ts

@@ -3607,6 +3607,7 @@ declare namespace CodeceptJS {
      * @property [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
      * @property [bypassCSP] - bypass Content Security Policy or CSP
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+     * @property [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.
      * @property [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).
      * @property [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).
      * @property [storageState] - Playwright storage state (path to JSON file or object)
@@ -3651,6 +3652,7 @@ declare namespace CodeceptJS {
         ignoreHTTPSErrors?: boolean;
         bypassCSP?: boolean;
         highlightElement?: boolean;
+        visibleLocator?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
         storageState?: string | any;

package/typings/types.d.ts

@@ -3641,6 +3641,7 @@ declare namespace CodeceptJS {
      * @property [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
      * @property [bypassCSP] - bypass Content Security Policy or CSP
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+     * @property [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.
      * @property [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).
      * @property [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).
      * @property [storageState] - Playwright storage state (path to JSON file or object)
@@ -3685,6 +3686,7 @@ declare namespace CodeceptJS {
         ignoreHTTPSErrors?: boolean;
         bypassCSP?: boolean;
         highlightElement?: boolean;
+        visibleLocator?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
         storageState?: string | any;
@@ -11054,12 +11056,14 @@ declare namespace CodeceptJS {
      * @property [exact] - Enable strict mode for this step. Throws if multiple elements match.
      * @property [strictMode] - Alias for exact.
      * @property [ignoreCase] - Perform case-insensitive text matching.
+     * @property [visibleLocator] - Match only visible elements. Overrides the Playwright helper `visibleLocator` config option for this step.
      */
     type StepOptions = {
         elementIndex?: number | 'first' | 'last';
         exact?: boolean;
         strictMode?: boolean;
         ignoreCase?: boolean;
+        visibleLocator?: boolean;
     };
     /**
      * StepConfig is a configuration object for a step.
@@ -11169,6 +11173,10 @@ declare namespace CodeceptJS {
         var currentTest: CodeceptJS.Test | null;
         var currentStep: CodeceptJS.Step | null;
         var currentSuite: CodeceptJS.Suite | null;
+        /**
+         * Locators match only visible elements, resolved per step
+         */
+        var visibleLocator: boolean;
         var tsFileMapping: Map<string, string> | null;
         /**
          * Initialize required store fields.