feat: add elementIndex step option for targeting specific elements (#5499)

* feat: add elementIndex step option for targeting specific elements

When multiple elements match a locator, users can now specify which one
to interact with using step.opts({ elementIndex }). Supports positive
(1-based), negative (-1 = last), and 'first'/'last' aliases. Silently
ignored when only one element matches. Overrides strict mode when set.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add TypeScript types for step options and codeceptjs/steps module

Add StepOptions typedef with elementIndex and ignoreCase in JSDoc.
Add declare module for 'codeceptjs/steps' for IDE autocompletion.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use absolute XPath with // prefix in MultipleElementsFound error

toAbsoluteXPath() now returns //html/... instead of /html/... to match
standard absolute XPath notation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: rename strict.md to element-selection.md

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use duck-typing for StepConfig detection instead of instanceof

instanceof fails when StepConfig is loaded from different module paths
(e.g., symlinked packages). Add __isStepConfig marker and static
isStepConfig() method for reliable detection across module boundaries.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add exact and strictMode step options for per-step strict mode

Enable strict mode on individual steps without changing helper config:
  step.opts({ exact: true })      // Playwright-compatible naming
  step.opts({ strictMode: true }) // alias

Throws MultipleElementsFound when multiple elements match, even with
strict: false in helper config.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: exact: false cancels strict mode per-step

When helper has strict: true, step.opts({ exact: false }) overrides it
for that step, allowing multiple element matches without error.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: role locators now use getByRole() when wrapped in Locator object

handleRoleLocator used isRoleLocatorObject() which rejected Locator-wrapped
role objects (checking !locator.type). This caused findClickable to fall
through to a CSS [role="button"] selector, losing text/exact filters.

Now uses new Locator(locator).isRole() to detect role locators regardless
of whether they arrive as raw objects or Locator instances, ensuring
Playwright's native getByRole() API is always used.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use Array.from() for WebDriver element collections in selectElement

WebDriver returns element collections that aren't plain arrays, so
.map() may not work correctly. Matches the pattern used in WebDriver's
own assertOnlyOneElement.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* docs: add exact/strictMode per-step options to element selection guide

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: DavertMik <davert@testomat.io>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

docs/element-selection.md

@@ -0,0 +1,125 @@
+---
+permalink: /element-selection
+title: Element Selection
+---
+
+# Element Selection
+
+When you write `I.click('a')` and there are multiple links on a page, CodeceptJS clicks the **first** one it finds. Most of the time this is exactly what you need — your locators are specific enough that there's only one match, or the first match happens to be the right one.
+
+But what happens when it's not?
+
+## Picking a Specific Element
+
+Say you have a list of items and you want to click the second one. You could write a more specific CSS selector, but sometimes the simplest approach is to tell CodeceptJS which element you want by position:
+
+```js
+import step from 'codeceptjs/steps'
+
+// click the 2nd link
+I.click('a', step.opts({ elementIndex: 2 }))
+
+// click the last link
+I.click('a', step.opts({ elementIndex: 'last' }))
+
+// fill the last matching input
+I.fillField('.email-input', 'test@example.com', step.opts({ elementIndex: -1 }))
+```
+
+The `elementIndex` option accepts:
+
+* **Positive numbers** (1-based) — `1` is first, `2` is second, `3` is third
+* **Negative numbers** — `-1` is last, `-2` is second-to-last
+* **`'first'`** and **`'last'`** as readable aliases
+
+This works with any action that targets a single element: `click`, `doubleClick`, `rightClick`, `fillField`, `appendField`, `clearField`, `checkOption`, `selectOption`, `attachFile`, and others.
+
+If only one element matches the locator, `elementIndex` is silently ignored — you always get that single element regardless of the index value. This is convenient when the number of matches depends on page state: you won't get an error if the list happens to have just one item.
+
+When multiple elements exist but the index is out of range, CodeceptJS throws a clear error:
+
+```
+elementIndex 100 exceeds the number of elements found (3) for "a"
+```
+
+You can combine `elementIndex` with other step options:
+
+```js
+I.click('a', step.opts({ elementIndex: 2 }).timeout(5).retry(3))
+```
+
+## Strict Mode
+
+If you'd rather not silently click the first of many matches, enable `strict: true` in your helper configuration. This makes CodeceptJS throw an error whenever a locator matches more than one element, forcing you to write precise locators:
+
+```js
+// codecept.conf.js
+helpers: {
+  Playwright: {
+    url: 'http://localhost',
+    browser: 'chromium',
+    strict: true,
+  }
+}
+```
+
+Now any ambiguous locator will fail immediately:
+
+```js
+I.click('a') // MultipleElementsFound: Multiple elements (3) found for "a" in strict mode
+```
+
+This is useful on projects where you want to catch accidental matches early — clicking the wrong button because of a vague locator is a common source of flaky tests.
+
+When a test fails in strict mode, the error includes a `fetchDetails()` method that lists the matched elements with their XPath and simplified HTML, so you can see exactly what was found and write a better locator:
+
+```js
+// Multiple elements (3) found for "a" in strict mode. Call fetchDetails() for full information.
+// After fetchDetails():
+// /html/body/div/a[1] <a id="first-link">First</a>
+// /html/body/div/a[2] <a id="second-link">Second</a>
+// /html/body/div/a[3] <a id="third-link">Third</a>
+// Use a more specific locator or grabWebElements() to work with multiple elements
+```
+
+Strict mode is supported in **Playwright**, **Puppeteer**, and **WebDriver** helpers.
+
+### Per-Step Strict Mode with `exact`
+
+You don't have to enable strict mode globally. Use `exact: true` to enforce it on a single step — handy when most of your tests are fine with default behavior but a particular action needs to be precise:
+
+```js
+import step from 'codeceptjs/steps'
+
+I.click('a', step.opts({ exact: true }))
+// throws MultipleElementsFound if more than one link matches
+```
+
+`strictMode: true` is an alias if you prefer a more descriptive name:
+
+```js
+I.click('a', step.opts({ strictMode: true }))
+```
+
+It works the other way too. If your helper has `strict: true` globally but you need to relax it for one step, use `exact: false`:
+
+```js
+// strict: true in config, but this step allows multiple matches
+I.click('a', step.opts({ exact: false }))
+```
+
+And when you know there are multiple matches and want a specific one, `elementIndex` also overrides the strict check — no error is thrown because you've explicitly chosen which element to use:
+
+```js
+// strict: true in config, but this works without error
+I.click('a', step.opts({ elementIndex: 2 }))
+```
+
+## Summary
+
+| Situation | Approach |
+|-----------|----------|
+| You want to catch ambiguous locators early | Enable `strict: true` in helper config |
+| You need a specific element from a known list | Use `step.opts({ elementIndex: N })` |
+| You want to iterate over all matching elements | Use [`eachElement`](/els) from the `els` module |
+| You need full control over element inspection | Use [`grabWebElements`](/WebElement) to get all matches |

lib/element/WebElement.js

@@ -352,7 +352,7 @@ class WebElement {
         parts.unshift(`${tagName}${pathIndex}`)
         current = current.parentElement
       }
-      return '/' + parts.join('/')
+      return '//' + parts.join('/')
     }
 
     switch (this.helperType) {

lib/els.js

@@ -10,7 +10,7 @@ import WebElement from './element/WebElement.js'
 
 function element(purpose, locator, fn) {
   let stepConfig
-  if (arguments[arguments.length - 1] instanceof StepConfig) {
+  if (StepConfig.isStepConfig(arguments[arguments.length - 1])) {
     stepConfig = arguments[arguments.length - 1]
   }