codeceptjs 4.2.0-beta.1 → 4.2.0-beta.3

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/Obscura.md

@@ -28,9 +28,9 @@ process lifecycle, the same way Playwright manages its own browser process.
     never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
 *   **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
     the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
-    spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
-    free port picked automatically), waits for it to answer, connects, and kills it in
-    `_finishTest`.
+    spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+    the config, or a free port picked automatically), waits for it to answer, connects, and kills
+    it in `_finishTest`.
 *   **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
     answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
     before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -43,12 +43,13 @@ Download a release binary and put it on your `PATH` (or point `binaryPath`/`OBSC
 it directly) and the helper launches and tears it down for you automatically:
 
 ```sh
-curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.0/obscura-x86_64-linux.tar.gz | tar xz
+curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
 ```
 
-`--allow-private-network` is always passed by this helper (it's required to reach apps running
-on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
-private-network requests by default).
+`--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+`127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+default.
 
 ## Config presets
 
@@ -67,7 +68,7 @@ Set them explicitly in your own config to skip probing or to force a mode.
 ## Limitations
 
 *   `input` is always `synthetic`, even on rendering builds — see `input` above.
-*   No frames, popups, or file uploads.
+*   No frames or popups.
 *   On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
     (`seeElement`/`dontSeeElement` always throw) — only DOM presence
     (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.

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 steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. 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/command/info.js

@@ -21,9 +21,16 @@ function parsePlaywrightBrowsers(output) {
   return versions.join(', ')
 }
 
+// Bun has its own package runner and a Bun-only install has no `npx` on PATH at all, so the
+// runner has to follow the runtime that is actually executing rather than what PATH happens to hold.
+function getPackageRunner() {
+  if (process.versions.bun) return 'bunx'
+  return 'npx'
+}
+
 async function getPlaywrightBrowsers() {
   try {
-    const info = execSync('npx playwright install --dry-run').toString().trim()
+    const info = execSync(`${getPackageRunner()} playwright install --dry-run`).toString().trim()
     return parsePlaywrightBrowsers(info)
   } catch (err) {
     return 'Playwright not installed'
@@ -85,7 +92,7 @@ export default async function (path) {
   output.print('***************************************')
 }
 
-export { parsePlaywrightBrowsers, getRuntimeInfo }
+export { parsePlaywrightBrowsers, getRuntimeInfo, getPackageRunner }
 
 export const getMachineInfo = async () => {
   const info = {

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/CDPBrowser.js

@@ -1631,6 +1631,9 @@ class CDPBrowser extends Helper {
     const value = Array.isArray(option) ? option.map(String) : String(option)
     const res = await this._run(this._candidates(select, 'field'), 'select', { value }, context)
     if (!res.found) throw new ElementNotFound(select, 'Selectable field')
+    if (res.result === '__RADIOGROUP_MULTI__') {
+      throw new Error(`selectOption: a radio group holds one value, but ${value.length} options were passed: ${value.join(', ')}`)
+    }
     if (res.result === false) throw new Error(`Option "${Array.isArray(option) ? option.join(',') : option}" not found in ${new Locator(select).toString()}`)
   }
 
@@ -1810,7 +1813,6 @@ class CDPBrowser extends Helper {
    */
   async waitInUrl(urlPart, sec = null) {
     const timeout = sec || this.options.waitForTimeout
-    const expectedUrl = resolveUrl(urlPart, this.options.url)
     let lastUrl = ''
     try {
       return await this._poll(
@@ -1822,7 +1824,7 @@ class CDPBrowser extends Helper {
         'placeholder',
       )
     } catch (e) {
-      throw new Error(`expected url to include ${expectedUrl}, but found ${lastUrl}`)
+      throw new Error(`expected url to include ${urlPart}, but found ${lastUrl}`)
     }
   }
 

package/lib/helper/Obscura.js

@@ -45,9 +45,9 @@ const config = {}
  *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
  * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
  *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
- *   spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
- *   free port picked automatically), waits for it to answer, connects, and kills it in
- *   `_finishTest`.
+ *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+ *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
+ *   it in `_finishTest`.
  * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
  *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
  *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -60,12 +60,13 @@ const config = {}
  * it directly) and the helper launches and tears it down for you automatically:
  *
  * ```sh
- * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.0/obscura-x86_64-linux.tar.gz | tar xz
+ * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
  * ```
  *
- * `--allow-private-network` is always passed by this helper (it's required to reach apps running
- * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
- * private-network requests by default).
+ * `--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+ * is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+ * `127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+ * default.
  *
  * ## Config presets
  *
@@ -84,7 +85,7 @@ const config = {}
  * ## Limitations
  *
  * - `input` is always `synthetic`, even on rendering builds — see `input` above.
- * - No frames, popups, or file uploads.
+ * - No frames or popups.
  * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
  *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
  *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -179,7 +180,7 @@ class Obscura extends CDPBrowser {
       const port = this.options.port || (await this._findFreePort())
       this.options.port = port
       this.serverError = null
-      this.serverProcess = spawn(binaryPath, ['serve', '--port', String(port), '--allow-private-network'], { stdio: 'ignore' })
+      this.serverProcess = spawn(binaryPath, ['serve', '--port', String(port), '--allow-private-network', '--allow-file-access'], { stdio: 'ignore' })
       this.serverProcess.on('error', err => {
         this.serverError = err
       })

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 visibilityAgnosticSteps = ['seeElementInDOM', 'dontSeeElementInDOM', 'seeNumberOfElements', 'scrollTo']
 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 steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. 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,11 @@ class Playwright extends Helper {
     }
   }
 
+  _beforeStep(step) {
+    const reachesHidden = step.helperMethod?.startsWith('grab') || visibilityAgnosticSteps.includes(step.helperMethod)
+    store.visibleLocator = step.opts?.visibleLocator ?? (this.options.visibleLocator && !reachesHidden)
+  }
+
   async _before(test) {
     // Skip browser operations in dry-run mode (used by check command)
     if (store.dryRun) {
@@ -1518,6 +1526,7 @@ class Playwright extends Helper {
       assertElementExists(el, locator)
     }
 
+    await el.scrollIntoViewIfNeeded()
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await clickablePoint(el)
     await this.page.mouse.move(x + offsetX, y + offsetY)
@@ -4197,6 +4206,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 +4229,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 +4237,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 +4253,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 +4330,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 +4406,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
@@ -846,6 +845,9 @@ class Puppeteer extends Helper {
       }
     }
 
+    if (!(await el.isIntersectingViewport({ threshold: 1 }))) {
+      await el.evaluate(el => el.scrollIntoView({ block: 'center', inline: 'center' }))
+    }
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await getClickablePoint(el)
     await this.page.mouse.move(x + offsetX, y + offsetY)
@@ -3196,19 +3198,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 +3208,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/clientscripts/cdpBrowserClient.js

@@ -387,6 +387,17 @@ export default function installCodeceptClient(xpathNeedsPolyfill) {
         return true
       }
 
+      if (resolveRole(el) === 'radiogroup') {
+        if (values.length > 1) return '__RADIOGROUP_MULTI__'
+        const radios = Array.from(el.querySelectorAll('[role="radio"]'))
+        const [wanted] = values
+        const named = (radio, matchFn) => roleTextCandidates(radio).some(matchFn)
+        const radio = radios.find(r => named(r, t => t === wanted)) || radios.find(r => named(r, t => t.indexOf(wanted) !== -1))
+        if (!radio) return false
+        radio.click()
+        return true
+      }
+
       // ARIA combobox/listbox widgets: click the trigger (if any) to reveal the
       // listbox, then click each matching [role="option"].
       let container = el

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.3",
   "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

@@ -3429,9 +3429,9 @@ declare namespace CodeceptJS {
      *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
      * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
      *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
-     *   spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
-     *   free port picked automatically), waits for it to answer, connects, and kills it in
-     *   `_finishTest`.
+     *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+     *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
+     *   it in `_finishTest`.
      * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
      *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
      *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -3444,12 +3444,13 @@ declare namespace CodeceptJS {
      * it directly) and the helper launches and tears it down for you automatically:
      *
      * ```sh
-     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.0/obscura-x86_64-linux.tar.gz | tar xz
+     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
      * ```
      *
-     * `--allow-private-network` is always passed by this helper (it's required to reach apps running
-     * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
-     * private-network requests by default).
+     * `--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+     * is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+     * `127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+     * default.
      *
      * ## Config presets
      *
@@ -3468,7 +3469,7 @@ declare namespace CodeceptJS {
      * ## Limitations
      *
      * - `input` is always `synthetic`, even on rendering builds — see `input` above.
-     * - No frames, popups, or file uploads.
+     * - No frames or popups.
      * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
      *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
      *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -3607,6 +3608,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 steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. 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 +3653,7 @@ declare namespace CodeceptJS {
         ignoreHTTPSErrors?: boolean;
         bypassCSP?: boolean;
         highlightElement?: boolean;
+        visibleLocator?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
         storageState?: string | any;

package/typings/types.d.ts

@@ -3462,9 +3462,9 @@ declare namespace CodeceptJS {
      *   never spawns or kills anything, no matter what `binaryPath`/`port` are set to.
      * - **SELF-LAUNCH** — `endpoint` is unset and a binary can be resolved, in order: `binaryPath` in
      *   the config, then the `OBSCURA_PATH` environment variable, then `obscura` on `PATH`. The helper
-     *   spawns `obscura serve --port <port> --allow-private-network` (`port` from the config, or a
-     *   free port picked automatically), waits for it to answer, connects, and kills it in
-     *   `_finishTest`.
+     *   spawns `obscura serve --port <port> --allow-private-network --allow-file-access` (`port` from
+     *   the config, or a free port picked automatically), waits for it to answer, connects, and kills
+     *   it in `_finishTest`.
      * - **COURTESY-ATTACH** — `endpoint` is unset and no binary can be resolved, but something already
      *   answers `http://127.0.0.1:9222/json/version` (e.g. `obscura serve` started by hand, or by CI
      *   before this process ever ran). The helper attaches to it and never kills it — it isn't the
@@ -3477,12 +3477,13 @@ declare namespace CodeceptJS {
      * it directly) and the helper launches and tears it down for you automatically:
      *
      * ```sh
-     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.0/obscura-x86_64-linux.tar.gz | tar xz
+     * curl -sL https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.2/obscura-x86_64-linux.tar.gz | tar xz
      * ```
      *
-     * `--allow-private-network` is always passed by this helper (it's required to reach apps running
-     * on `localhost`/private IPs, e.g. a dev server on `127.0.0.1:8000` — Obscura blocks
-     * private-network requests by default).
+     * `--allow-private-network` and `--allow-file-access` are always passed by this helper: the first
+     * is required to reach apps running on `localhost`/private IPs, e.g. a dev server on
+     * `127.0.0.1:8000`, the second to let `attachFile` upload local files. Obscura blocks both by
+     * default.
      *
      * ## Config presets
      *
@@ -3501,7 +3502,7 @@ declare namespace CodeceptJS {
      * ## Limitations
      *
      * - `input` is always `synthetic`, even on rendering builds — see `input` above.
-     * - No frames, popups, or file uploads.
+     * - No frames or popups.
      * - On `-no-render` builds and v0.1.x: no screenshots, no visibility assertions
      *   (`seeElement`/`dontSeeElement` always throw) — only DOM presence
      *   (`seeElementInDOM`/`dontSeeElementInDOM`) is meaningful without a layout engine.
@@ -3641,6 +3642,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 steps that must reach hidden elements: `grab*` methods, `scrollTo`, `seeElementInDOM`, `dontSeeElementInDOM` and `seeNumberOfElements`. 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 +3687,7 @@ declare namespace CodeceptJS {
         ignoreHTTPSErrors?: boolean;
         bypassCSP?: boolean;
         highlightElement?: boolean;
+        visibleLocator?: boolean;
         recordHar?: any;
         testIdAttribute?: string;
         storageState?: string | any;
@@ -11054,12 +11057,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 +11174,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.