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>

Author: DavertMik

lib/helper/Playwright.js

@@ -4281,12 +4281,12 @@ async function proceedClick(locator, context = null, options = {}) {
     assertElementExists(els, locator, 'Clickable element')
   }
 
-  const elementIndex = store.currentStep?.opts?.elementIndex
+  const opts = store.currentStep?.opts
   let element
-  if (elementIndex != null) {
+  if (opts?.elementIndex != null) {
     element = selectElement(els, locator, this)
   } else {
-    if (this.options.strict) assertOnlyOneElement(els, locator, this)
+    if (this.options.strict || opts?.exact === true || opts?.strictMode === true) assertOnlyOneElement(els, locator, this)
     element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
   }
 

lib/helper/extras/elementSelection.js

@@ -9,8 +9,14 @@ function resolveElementIndex(value) {
   return value
 }
 
+function isStrictStep(opts, helper) {
+  if (opts?.exact === true || opts?.strictMode === true) return true
+  return helper.options.strict
+}
+
 function selectElement(els, locator, helper) {
-  const rawIndex = store.currentStep?.opts?.elementIndex
+  const opts = store.currentStep?.opts
+  const rawIndex = opts?.elementIndex
   const elementIndex = resolveElementIndex(rawIndex)
 
   if (elementIndex != null) {
@@ -37,7 +43,7 @@ function selectElement(els, locator, helper) {
     return els[idx]
   }
 
-  if (helper.options.strict) {
+  if (isStrictStep(opts, helper)) {
     if (els.length > 1) {
       const webElements = els.map(el => new WebElement(el, helper))
       throw new MultipleElementsFound(locator, webElements)

lib/step/config.js

@@ -1,6 +1,8 @@
 /**
  * @typedef {Object} StepOptions
  * @property {number|'first'|'last'} [elementIndex] - Select a specific element when multiple match. 1-based positive index, negative from end, or 'first'/'last'.
+ * @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.
  */
 

test/helper/webapi.js

@@ -2388,5 +2388,37 @@ export function tests() {
       expect(err).to.exist
       expect(err.message).to.include('elementIndex')
     })
+
+    it('should enable strict mode per-step with exact: true', async () => {
+      await I.amOnPage('/info')
+      store.currentStep = { opts: { exact: true } }
+      let err
+      try {
+        await I.click('#grab-multiple a')
+      } catch (e) {
+        err = e
+      }
+      expect(err).to.exist
+      expect(err.constructor.name).to.equal('MultipleElementsFound')
+    })
+
+    it('should enable strict mode per-step with strictMode: true', async () => {
+      await I.amOnPage('/info')
+      store.currentStep = { opts: { strictMode: true } }
+      let err
+      try {
+        await I.click('#grab-multiple a')
+      } catch (e) {
+        err = e
+      }
+      expect(err).to.exist
+      expect(err.constructor.name).to.equal('MultipleElementsFound')
+    })
+
+    it('should not throw with exact: true when single element found', async () => {
+      await I.amOnPage('/info')
+      store.currentStep = { opts: { exact: true } }
+      await I.click('#first-link')
+    })
   })
 }