added strict mode to PW

Author: DavertMik

lib/helper/Playwright.js

@@ -27,6 +27,7 @@ import {
 } from '../utils.js'
 import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import ElementNotFound from './errors/ElementNotFound.js'
+import MultipleElementsFound from './errors/MultipleElementsFound.js'
 import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefused.js'
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
@@ -107,6 +108,9 @@ const pathSeparator = path.sep
  *   those cookies are used instead and the configured `storageState` is ignored (no merge).
  *   May include session cookies, auth tokens, localStorage and (if captured with
  *   `grabStorageState({ indexedDB: true })`) IndexedDB data; treat as sensitive and do not commit.
+ * @prop {boolean} [strict=false] - throw error when multiple elements match a single-element locator.
+ *   When enabled, methods like `click`, `fillField`, `selectOption`, etc. will throw a
+ *   `MultipleElementsFound` error if more than one element matches the locator.
  */
 const config = {}
 
@@ -417,6 +421,7 @@ class Playwright extends Helper {
       highlightElement: false,
       storageState: undefined,
       onResponse: null,
+      strict: false, // Throw error when multiple elements match single-element locator
     }
 
     process.env.testIdAttribute = 'data-testid'
@@ -1912,7 +1917,12 @@ class Playwright extends Helper {
    */
   async _locateElement(locator) {
     const context = await this._getContext()
-    return findElement(context, locator)
+    const elements = await findElements.call(this, context, locator)
+    if (elements.length === 0) {
+      throw new ElementNotFound(locator, 'Element', 'was not found')
+    }
+    if (this.options.strict) assertOnlyOneElement(elements, locator)
+    return elements[0]
   }
 
   /**
@@ -1927,6 +1937,7 @@ class Playwright extends Helper {
     const context = providedContext || (await this._getContext())
     const els = await findCheckable.call(this, locator, context)
     assertElementExists(els[0], locator, 'Checkbox or radio')
+    if (this.options.strict) assertOnlyOneElement(els, locator)
     return els[0]
   }
 
@@ -2399,6 +2410,7 @@ class Playwright extends Helper {
   async fillField(field, value) {
     const els = await findFields.call(this, field)
     assertElementExists(els, field, 'Field')
+    if (this.options.strict) assertOnlyOneElement(els, field)
     const el = els[0]
 
     await el.clear()
@@ -2431,6 +2443,7 @@ class Playwright extends Helper {
   async clearField(locator, options = {}) {
     const els = await findFields.call(this, locator)
     assertElementExists(els, locator, 'Field to clear')
+    if (this.options.strict) assertOnlyOneElement(els, locator)
 
     const el = els[0]
 
@@ -2447,6 +2460,7 @@ class Playwright extends Helper {
   async appendField(field, value) {
     const els = await findFields.call(this, field)
     assertElementExists(els, field, 'Field')
+    if (this.options.strict) assertOnlyOneElement(els, field)
     await highlightActiveElement.call(this, els[0])
     await els[0].press('End')
     await els[0].type(value.toString(), { delay: this.options.pressKeyDelay })
@@ -4444,20 +4458,6 @@ async function findCustomElements(matcher, locator) {
   return locators
 }
 
-async function findElement(matcher, locator) {
-  const matchedLocator = Locator.from(locator)
-  const roleElements = await findByRole(matcher, matchedLocator)
-  if (roleElements && roleElements.length > 0) return roleElements[0]
-
-  const isReactLocator = matchedLocator.type === 'react'
-  const isVueLocator = matchedLocator.type === 'vue'
-
-  if (isReactLocator) return findReact(matcher, matchedLocator)
-  if (isVueLocator) return findVue(matcher, matchedLocator)
-
-  return matcher.locator(buildLocatorString(matchedLocator)).first()
-}
-
 async function getVisibleElements(elements) {
   const visibleElements = []
   for (const element of elements) {
@@ -4511,20 +4511,33 @@ async function findClickable(matcher, locator) {
   if (locator.vue) return findVue(matcher, locator)
 
   locator = new Locator(locator)
-  if (!locator.isFuzzy()) return findElements.call(this, matcher, locator)
+  if (!locator.isFuzzy()) {
+    const els = await findElements.call(this, matcher, locator)
+    if (this.options.strict) assertOnlyOneElement(els, locator)
+    return els
+  }
 
   let els
   const literal = xpathLocator.literal(locator.value)
 
   els = await findElements.call(this, matcher, Locator.clickable.narrow(literal))
-  if (els.length) return els
+  if (els.length) {
+    if (this.options.strict) assertOnlyOneElement(els, locator)
+    return els
+  }
 
   els = await findElements.call(this, matcher, Locator.clickable.wide(literal))
-  if (els.length) return els
+  if (els.length) {
+    if (this.options.strict) assertOnlyOneElement(els, locator)
+    return els
+  }
 
   try {
     els = await findElements.call(this, matcher, Locator.clickable.self(literal))
-    if (els.length) return els
+    if (els.length) {
+      if (this.options.strict) assertOnlyOneElement(els, locator)
+      return els
+    }
   } catch (err) {
     // Do nothing
   }
@@ -4782,6 +4795,12 @@ function assertElementExists(res, locator, prefix, suffix) {
   }
 }
 
+function assertOnlyOneElement(elements, locator) {
+  if (elements.length > 1) {
+    throw new MultipleElementsFound(locator, elements)
+  }
+}
+
 function $XPath(element, selector) {
   const found = document.evaluate(selector, element || document.body, null, 5, null)
   const res = []
@@ -5018,7 +5037,7 @@ async function saveTraceForContext(context, name) {
 }
 
 async function highlightActiveElement(element) {
-  if ((this.options.highlightElement || store.onPause) && store.debugMode) {
+  if (this.options.highlightElement || store.onPause || store.debugMode) {
     await element.evaluate(el => {
       const prevStyle = el.style.boxShadow
       el.style.boxShadow = '0px 0px 4px 3px rgba(147, 51, 234, 0.8)' // Bright purple that works on both dark/light modes

lib/helper/errors/MultipleElementsFound.js

@@ -0,0 +1,135 @@
+import Locator from '../../locator.js'
+
+/**
+ * Error thrown when strict mode is enabled and multiple elements are found
+ * for a single-element locator operation (click, fillField, etc.)
+ */
+class MultipleElementsFound extends Error {
+  /**
+   * @param {Locator|string|object} locator - The locator used
+   * @param {Array<HTMLElement>} elements - Array of Playwright element handles found
+   */
+  constructor(locator, elements) {
+    super(`Multiple elements (${elements.length}) found for "${locator}". Call fetchDetails() for full information.`)
+    this.name = 'MultipleElementsFound'
+    this.locator = locator
+    this.elements = elements
+    this.count = elements.length
+    this._detailsFetched = false
+  }
+
+  /**
+   * Fetch detailed information about the found elements asynchronously
+   * This updates the error message with XPath and element previews
+   */
+  async fetchDetails() {
+    if (this._detailsFetched) return
+
+    try {
+      if (typeof this.locator === 'object' && !(this.locator instanceof Locator)) {
+        this.locator = JSON.stringify(this.locator)
+      }
+
+      const locatorObj = new Locator(this.locator)
+      const elementList = await this._generateElementList(this.elements, this.count)
+
+      this.message = `Multiple elements (${this.count}) found for "${locatorObj.toString()}" in strict mode.\n` +
+        elementList +
+        `\nUse a more specific locator or use grabWebElements() to handle multiple elements.`
+    } catch (err) {
+      this.message = `Multiple elements (${this.count}) found. Failed to fetch details: ${err.message}`
+    }
+
+    this._detailsFetched = true
+  }
+
+  /**
+   * Generate a formatted list of found elements with their XPath and preview
+   * @param {Array<HTMLElement>} elements
+   * @param {number} count
+   * @returns {Promise<string>}
+   */
+  async _generateElementList(elements, count) {
+    const items = []
+    const maxToShow = Math.min(count, 10)
+
+    for (let i = 0; i < maxToShow; i++) {
+      const el = elements[i]
+      try {
+        const info = await this._getElementInfo(el)
+        items.push(`  ${i + 1}. ${info.xpath} (${info.preview})`)
+      } catch (err) {
+        // Element might be detached or inaccessible
+        items.push(`  ${i + 1}. [Unable to get element info: ${err.message}]`)
+      }
+    }
+
+    if (count > 10) {
+      items.push(`  ... and ${count - 10} more`)
+    }
+
+    return items.join('\n')
+  }
+
+  /**
+   * Get XPath and preview for an element by running JavaScript in browser context
+   * @param {HTMLElement} element
+   * @returns {Promise<{xpath: string, preview: string}>}
+   */
+  async _getElementInfo(element) {
+    return element.evaluate((el) => {
+      // Generate a unique XPath for this element
+      const getUniqueXPath = (element) => {
+        if (element.id) {
+          return `//*[@id="${element.id}"]`
+        }
+
+        const parts = []
+        let current = element
+
+        while (current && current.nodeType === Node.ELEMENT_NODE) {
+          let index = 0
+          let sibling = current.previousSibling
+
+          while (sibling) {
+            if (sibling.nodeType === Node.ELEMENT_NODE && sibling.tagName === current.tagName) {
+              index++
+            }
+            sibling = sibling.previousSibling
+          }
+
+          const tagName = current.tagName.toLowerCase()
+          const pathIndex = index > 0 ? `[${index + 1}]` : ''
+          parts.unshift(`${tagName}${pathIndex}`)
+
+          current = current.parentElement
+
+          // Stop at body to keep XPath reasonable
+          if (current && current.tagName === 'BODY') {
+            parts.unshift('body')
+            break
+          }
+        }
+
+        return '/' + parts.join('/')
+      }
+
+      // Get a preview of the element (tag, classes, id)
+      const getPreview = (element) => {
+        const tag = element.tagName.toLowerCase()
+        const id = element.id ? `#${element.id}` : ''
+        const classes = element.className
+          ? '.' + element.className.split(' ').filter(c => c).join('.')
+          : ''
+        return `${tag}${id}${classes || ''}`
+      }
+
+      return {
+        xpath: getUniqueXPath(el),
+        preview: getPreview(el),
+      }
+    })
+  }
+}
+
+export default MultipleElementsFound

test/data/app/view/form/strict_mode.php

@@ -0,0 +1,48 @@
+<html>
+<body>
+<h1>Strict Mode Test Page</h1>
+
+<h2>Multiple Buttons (Same Class)</h2>
+<button class="duplicate-btn">Button 1</button>
+<button class="duplicate-btn">Button 2</button>
+<button class="duplicate-btn">Button 3</button>
+
+<h2>Single Button</h2>
+<button class="single-btn">Single Button</button>
+
+<h2>Multiple Inputs (Same Name)</h2>
+<form>
+    <input type="text" name="duplicate-field" placeholder="Field 1" />
+    <input type="text" name="duplicate-field" placeholder="Field 2" />
+    <input type="text" name="duplicate-field" placeholder="Field 3" />
+</form>
+
+<h2>Single Input</h2>
+<form>
+    <input type="text" name="single-field" placeholder="Single Field" />
+</form>
+
+<h2>Multiple Checkboxes (Same Name)</h2>
+<form>
+    <label><input type="checkbox" name="terms" value="1" /> Option 1</label><br>
+    <label><input type="checkbox" name="terms" value="2" /> Option 2</label><br>
+    <label><input type="checkbox" name="terms" value="3" /> Option 3</label>
+</form>
+
+<h2>Single Checkbox</h2>
+<form>
+    <label><input type="checkbox" name="agree" value="yes" /> I Agree</label>
+</form>
+
+<h2>Multiple Divs (Same Class)</h2>
+<div class="test-div">Div 1</div>
+<div class="test-div">Div 2</div>
+<div class="test-div">Div 3</div>
+
+<h2>Buttons with IDs for fetchDetails test</h2>
+<button id="details-btn-0" class="details-test-btn">Details Button 0</button>
+<button id="details-btn-1" class="details-test-btn">Details Button 1</button>
+<button id="details-btn-2" class="details-test-btn">Details Button 2</button>
+
+</body>
+</html>