codeceptjs 4.0.1-beta.22 → 4.0.1-beta.25

package/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 })
@@ -2492,7 +2506,6 @@ class Playwright extends Helper {
     const context = await this.context
     const matchedLocator = new Locator(select)
 
-    // Strict locator
     if (!matchedLocator.isFuzzy()) {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
       const els = await this._locate(matchedLocator)
@@ -2500,16 +2513,15 @@ class Playwright extends Helper {
       return proceedSelect.call(this, context, els[0], option)
     }
 
-    // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
-    let els = await findByRole(context, { role: 'combobox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, context, els[0], option)
+    const literal = xpathLocator.literal(matchedLocator.value)
+
+    let els = await this._locate({ xpath: Locator.select.narrow(literal) })
+    if (els.length) return proceedSelect.call(this, context, els[0], option)
 
-    // Fuzzy: try listbox
-    els = await findByRole(context, { role: 'listbox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, context, els[0], option)
+    els = await this._locate({ xpath: Locator.select.wide(literal) })
+    if (els.length) return proceedSelect.call(this, context, els[0], option)
 
-    // Fuzzy: try native select
     els = await findFields.call(this, select)
     assertElementExists(els, select, 'Selectable element')
     return proceedSelect.call(this, context, els[0], option)
@@ -2559,6 +2571,10 @@ class Playwright extends Helper {
    *
    */
   async see(text, context = null) {
+    // If only one argument passed and it's an object without custom toString(), treat as locator
+    if (!context && text && typeof text === 'object' && !Array.isArray(text) && text.toString === Object.prototype.toString) {
+      return this.seeElement(text)
+    }
     return proceedSee.call(this, 'assert', text, context)
   }
 
@@ -4442,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) {
@@ -4505,47 +4507,42 @@ async function proceedClick(locator, context = null, options = {}) {
 }
 
 async function findClickable(matcher, locator) {
-  // Convert to Locator first to handle JSON strings properly
-  const matchedLocator = new Locator(locator)
+  if (locator.react) return findReact(matcher, locator)
+  if (locator.vue) return findVue(matcher, locator)
 
-  // Handle role locators from Locator
-  if (matchedLocator.isRole()) {
-    return findByRole(matcher, matchedLocator)
+  locator = new Locator(locator)
+  if (!locator.isFuzzy()) {
+    const els = await findElements.call(this, matcher, locator)
+    if (this.options.strict) assertOnlyOneElement(els, locator)
+    return els
   }
 
-  if (!matchedLocator.isFuzzy()) return findElements.call(this, matcher, matchedLocator)
-
   let els
-  const literal = xpathLocator.literal(matchedLocator.value)
-
-  try {
-    els = await 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()
-    if (els.length) return els
-  } catch (err) {
-    // getByRole not supported or failed
-  }
+  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
   }
 
-  return findElements.call(this, matcher, matchedLocator.value) // by css or xpath
+  return findElements.call(this, matcher, locator.value) // by css or xpath
 }
 
 async function proceedSee(assertType, text, context, strict = false) {
@@ -4648,7 +4645,7 @@ async function proceedSelect(context, el, option) {
   const role = await el.getAttribute('role')
   const options = Array.isArray(option) ? option : [option]
 
-  if (role === 'combobox') {
+  if (role === 'combobox' || role === 'button') {
     this.debugSection('SelectOption', 'Expanding combobox')
     await highlightActiveElement.call(this, el)
     const [ariaOwns, ariaControls] = await Promise.all([el.getAttribute('aria-owns'), el.getAttribute('aria-controls')])
@@ -4798,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 = []
@@ -5034,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

package/lib/helper/Puppeteer.js

@@ -1690,6 +1690,10 @@ class Puppeteer extends Helper {
    * {{ react }}
    */
   async see(text, context = null) {
+    // If only one argument passed and it's an object without custom toString(), treat as locator
+    if (!context && text && typeof text === 'object' && !Array.isArray(text) && text.toString === Object.prototype.toString) {
+      return this.seeElement(text)
+    }
     return proceedSee.call(this, 'assert', text, context)
   }
 

package/lib/helper/WebDriver.js

@@ -1563,6 +1563,10 @@ class WebDriver extends Helper {
    * {{ react }}
    */
   async see(text, context = null) {
+    // If only one argument passed and it's an object without custom toString(), treat as locator
+    if (!context && text && typeof text === 'object' && !Array.isArray(text) && text.toString === Object.prototype.toString) {
+      return this.seeElement(text)
+    }
     return proceedSee.call(this, 'assert', text, context)
   }
 
@@ -2399,6 +2403,10 @@ class WebDriver extends Helper {
     })
   }
 
+  async _waitForAction() {
+    return this.wait(0.1)
+  }
+
   /**
    * {{> waitForEnabled }}
    */
@@ -3030,7 +3038,10 @@ async function proceedSelect(el, option) {
     const listboxId = ariaOwns || ariaControls
     let listboxEls = listboxId ? await this.browser.$$(`#${listboxId}`) : []
     if (!listboxEls.length) {
-      listboxEls = await this.browser.$$('[role="listbox"]')
+      listboxEls = await this.browser.findElementsFromElement(elementId, 'xpath', 'following-sibling::*[@role="listbox"]')
+    }
+    if (!listboxEls.length) {
+      listboxEls = await this.browser.findElementsFromElement(elementId, 'xpath', 'ancestor::*[@role="listbox"]')
     }
     if (!listboxEls.length) throw new Error('Cannot find listbox for combobox')
     const listbox = listboxEls[0]

package/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

package/lib/locator.js

@@ -6,6 +6,9 @@ const require = createRequire(import.meta.url)
 let cssToXPath
 
 const locatorTypes = ['css', 'by', 'xpath', 'id', 'name', 'fuzzy', 'frame', 'shadow', 'role']
+
+// Roles that can be used as shorthand locators: { button: 'text' } -> { role: 'button', text: 'text' }
+const shorthandRoles = ['button', 'link', 'textbox', 'checkbox', 'radio', 'combobox', 'listbox', 'heading', 'listitem', 'menuitem', 'tab', 'option', 'searchbox', 'alert', 'dialog']
 /** @class */
 class Locator {
   /**
@@ -114,6 +117,16 @@ class Locator {
     this.locator = locator
     const keys = Object.keys(locator)
     const [type] = keys
+
+    // Transform shorthand role locators: { button: 'text' } -> { role: 'button', text: 'text' }
+    if (keys.length === 1 && shorthandRoles.includes(type)) {
+      this.locator = { role: type, text: locator[type] }
+      this.type = 'role'
+      this.value = this.locator
+      Locator.filters.forEach(f => f(this.locator, this))
+      return
+    }
+
     this.type = type
     this.value = keys.length > 1 ? locator : locator[type]
     Locator.filters.forEach(f => f(locator, this))
@@ -500,7 +513,7 @@ Locator.clickable = {
       `.//*[@aria-label = ${literal}]`,
       `.//*[@title = ${literal}]`,
       `.//*[@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id ]`,
-      `.//*[@role='link' | @role='tab' | @role='menuitem' | @role='menuitemcheckbox' | @role='menuitemradio' | @role='option' | @role='radio' | @role='checkbox' | @role='switch' | @role='treeitem' | @role='gridcell' | @role='columnheader' | @role='rowheader' | @role='scrollbar' | @role='slider' | @role='spinbutton'][normalize-space(.)='${literal}']`,
+      `.//*[@role='button' or @role='link' or @role='tab' or @role='menuitem' or @role='menuitemcheckbox' or @role='menuitemradio' or @role='option' or @role='radio' or @role='checkbox' or @role='switch' or @role='treeitem' or @role='gridcell' or @role='columnheader' or @role='rowheader' or @role='scrollbar' or @role='slider' or @role='spinbutton'][normalize-space(.)=${literal}]`,
     ]),
 
   /**
@@ -570,6 +583,35 @@ Locator.checkable = {
 }
 
 Locator.select = {
+  /**
+   * Narrow strategy for finding select elements.
+   * Tries exact role match first (combobox/listbox by name), then select by name.
+   * @param {string} literal
+   * @returns {string}
+   */
+  narrow: literal =>
+    xpathLocator.combine([
+      `.//*[@role = 'combobox'][normalize-space(@name) = ${literal}]`,
+      `.//*[@role = 'listbox'][normalize-space(@name) = ${literal}]`,
+      `.//select[@name = ${literal}]`,
+    ]),
+
+  /**
+   * Wide strategy for finding select elements.
+   * Includes select, button, combobox, listbox with various accessibility attributes.
+   * @param {string} literal
+   * @returns {string}
+   */
+  wide: literal =>
+    xpathLocator.combine([
+      `.//select[((./@name = ${literal}) or ./@id = //label[@for][normalize-space(string(.)) = ${literal}]/@for or ./@placeholder = ${literal})]`,
+      `.//*[@role='button' or @role='combobox' or @role='listbox'][normalize-space(string(.)) = ${literal}]`,
+      `.//*[@role='button' or @role='combobox' or @role='listbox'][@aria-label = ${literal}]`,
+      `.//*[@role='button' or @role='combobox' or @role='listbox'][@title = ${literal}]`,
+      `.//*[@role='button' or @role='combobox' or @role='listbox'][@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id ]`,
+      `.//label[normalize-space(string(.)) = ${literal}]//*[self::button or @role='button' or @role='combobox' or @role='listbox']`,
+    ]),
+
   /**
    * @param {string} opt
    * @returns {string}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.1-beta.22",
+  "version": "4.0.1-beta.25",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [