feat(CDPBrowser): support elementIndex/strict-mode step options

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: DavertMik

lib/helper/CDPBrowser.js

@@ -9,6 +9,7 @@ import Locator from '../locator.js'
 import store from '../store.js'
 import { xpathLocator, normalizePath, resolveUrl, toCamelCase, convertCssPropertiesToCamelCase, normalizeSpacesInString } from '../utils.js'
 import ElementNotFound from './errors/ElementNotFound.js'
+import MultipleElementsFound from './errors/MultipleElementsFound.js'
 import { includes as stringIncludes } from '../assert/include.js'
 import { empty } from '../assert/empty.js'
 import { truth } from '../assert/truth.js'
@@ -260,9 +261,52 @@ class CDPBrowser extends Helper {
    */
   async _run(candidates, action, payload) {
     await this._ensureClient()
-    return this._evaluate(
-      `window.__codecept.run(${JSON.stringify(candidates)}, ${JSON.stringify(action)}, ${JSON.stringify(payload || null)}, ${JSON.stringify(this.withinCandidates)})`,
+    const selection = this._selectionDescriptor()
+    const res = await this._evaluate(
+      `window.__codecept.run(${JSON.stringify(candidates)}, ${JSON.stringify(action)}, ${JSON.stringify(payload || null)}, ${JSON.stringify(this.withinCandidates)}, ${JSON.stringify(selection)})`,
     )
+    if (res?.outOfBounds) {
+      throw new Error(`elementIndex ${res.requestedIndex} exceeds the number of elements found (${res.found}) for "${this._candidatesLabel(candidates)}"`)
+    }
+    if (res?.strictViolation) {
+      throw new MultipleElementsFound(this._candidatesLabel(candidates), new Array(res.found))
+    }
+    return res
+  }
+
+  /**
+   * Builds the `{index, strict}` element-selection descriptor from the current step's options
+   * (`store.currentStep.opts`) and `options.strict`, mirroring the semantics of
+   * `lib/helper/extras/elementSelection.js` (used by Puppeteer/WebDriver): a per-step
+   * `elementIndex` (numeric, or the `'first'`/`'last'` aliases) always takes precedence and
+   * disables strict mode for that step; otherwise `exact`/`strictMode` per-step options
+   * override `options.strict` to enable or cancel strict mode.
+   *
+   * @returns {?{index?: number, strict?: true}} `null` when neither applies.
+   * @protected
+   */
+  _selectionDescriptor() {
+    const opts = store.currentStep?.opts
+    let index = opts?.elementIndex
+    if (index === 'first') index = 1
+    else if (index === 'last') index = -1
+    if (index !== undefined && index !== null) return { index }
+    let strict = !!this.options.strict
+    if (opts?.exact === true || opts?.strictMode === true) strict = true
+    else if (opts?.exact === false || opts?.strictMode === false) strict = false
+    return strict ? { strict: true } : null
+  }
+
+  /**
+   * A short, human-readable label built from `candidates`, used in `_run`'s elementIndex/strict
+   * error messages when no locator string is otherwise available.
+   *
+   * @param {?Array<{type: 'css'|'xpath', value: string}>} candidates
+   * @returns {string}
+   * @protected
+   */
+  _candidatesLabel(candidates) {
+    return (candidates || []).map(c => c.value).join(' | ')
   }
 
   /**

lib/helper/clientscripts/cdpBrowserClient.js

@@ -166,14 +166,23 @@ export default function installCodeceptClient() {
     }).length,
   }
   window.__codecept = {
-    run(candidates, action, payload, within) {
+    run(candidates, action, payload, within, selection) {
       let root
       if (within) {
         const withinEls = find(within, document)
         if (!withinEls.length) return { found: 0, withinMissing: true }
         root = withinEls[0]
       }
-      const els = candidates === null ? [root] : find(candidates, root)
+      let els = candidates === null ? [root] : find(candidates, root)
+      if (selection && els.length > 1) {
+        if (selection.index != null) {
+          const idx = selection.index > 0 ? selection.index - 1 : els.length + selection.index
+          if (idx < 0 || idx >= els.length) return { found: els.length, outOfBounds: true, requestedIndex: selection.index }
+          els = [els[idx]]
+        } else if (selection.strict) {
+          return { found: els.length, strictViolation: true }
+        }
+      }
       if (!els.length && action !== 'count' && action !== 'visibleCount') return { found: 0 }
       return { found: els.length, result: actions[action](els, payload || {}) }
     },

test/helper/webapi.js

@@ -2613,9 +2613,6 @@ export function tests() {
   })
 
   describe('#elementIndex step option', () => {
-    beforeEach(function () {
-      if (isHelper('CDPBrowser')) this.skip() // store.currentStep.opts.elementIndex is not implemented in CDPBrowser
-    })
     afterEach(() => {
       store.currentStep = null
       I.options.strict = false