codeceptjs 4.0.0-rc.7 → 4.0.0-rc.9

package/docs/webapi/moveCursorTo.mustache

@@ -1,12 +1,16 @@
 Moves cursor to element matched by locator.
 Extra shift can be set with offsetX and offsetY options.
 
+An optional `context` (as a second parameter) can be specified to narrow the search to an element within a parent.
+When the second argument is a non-number (string or locator object), it is treated as context.
+
 ```js
 I.moveCursorTo('.tooltip');
 I.moveCursorTo('#submit', 5,5);
+I.moveCursorTo('#submit', '.container');
 ```
 
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-@param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
+@param {number|CodeceptJS.LocatorOrString} [offsetX=0] (optional, `0` by default) X-axis offset or context locator.
 @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
 @returns {void} automatically synchronized promise through #recorder

package/lib/element/WebElement.js

@@ -1,4 +1,5 @@
 import assert from 'assert'
+import { simplifyHtmlElement } from '../html.js'
 
 /**
  * Unified WebElement class that wraps native element instances from different helpers
@@ -306,6 +307,57 @@ class WebElement {
    * @returns {string} Normalized CSS selector
    * @private
    */
+  async toAbsoluteXPath() {
+    const xpathFn = (el) => {
+      const parts = []
+      let current = el
+      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
+      }
+      return '//' + parts.join('/')
+    }
+
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.evaluate(xpathFn)
+      case 'puppeteer':
+        return this.element.evaluate(xpathFn)
+      case 'webdriver':
+        return this.helper.browser.execute(xpathFn, this.element)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  async toOuterHTML() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.evaluate(el => el.outerHTML)
+      case 'puppeteer':
+        return this.element.evaluate(el => el.outerHTML)
+      case 'webdriver':
+        return this.helper.browser.execute(el => el.outerHTML, this.element)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  async toSimplifiedHTML(maxLength = 300) {
+    const outerHTML = await this.toOuterHTML()
+    return simplifyHtmlElement(outerHTML, maxLength)
+  }
+
   _normalizeLocator(locator) {
     if (typeof locator === 'string') {
       return locator

package/lib/helper/Playwright.js

@@ -36,7 +36,9 @@ import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefu
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
 import { findReact, findVue, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
+import { dropFile } from './scripts/dropFile.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
 
 let playwright
 let perfTiming
@@ -1494,8 +1496,23 @@ class Playwright extends Helper {
    *
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const el = await this._locateElement(locator)
-    assertElementExists(el, locator)
+    let context = null
+    if (typeof offsetX !== 'number') {
+      context = offsetX
+      offsetX = 0
+    }
+
+    let el
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      el = await findElements.call(this, contextEls[0], locator)
+      assertElementExists(el, locator)
+      el = el[0]
+    } else {
+      el = await this._locateElement(locator)
+      assertElementExists(el, locator)
+    }
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await clickablePoint(el)
@@ -1763,8 +1780,7 @@ class Playwright extends Helper {
     if (elements.length === 0) {
       throw new ElementNotFound(locator, 'Element', 'was not found')
     }
-    if (this.options.strict) assertOnlyOneElement(elements, locator)
-    return elements[0]
+    return selectElement(elements, locator, this)
   }
 
   /**
@@ -1779,8 +1795,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]
+    return selectElement(els, locator, this)
   }
 
   /**
@@ -2266,8 +2281,7 @@ class Playwright extends Helper {
   async fillField(field, value, context = null) {
     const els = await findFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    if (this.options.strict) assertOnlyOneElement(els, field)
-    const el = els[0]
+    const el = selectElement(els, field, this)
 
     await el.clear()
     if (store.debugMode) this.debugSection('Focused', await elToString(el, 1))
@@ -2285,9 +2299,8 @@ class Playwright extends Helper {
   async clearField(locator, context = null) {
     const els = await findFields.call(this, locator, context)
     assertElementExists(els, locator, 'Field to clear')
-    if (this.options.strict) assertOnlyOneElement(els, locator)
 
-    const el = els[0]
+    const el = selectElement(els, locator, this)
 
     await highlightActiveElement.call(this, el)
 
@@ -2302,10 +2315,10 @@ class Playwright extends Helper {
   async appendField(field, value, context = null) {
     const els = await findFields.call(this, field, context)
     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 })
+    const el = selectElement(els, field, this)
+    await highlightActiveElement.call(this, el)
+    await el.press('End')
+    await el.type(value.toString(), { delay: this.options.pressKeyDelay })
     return this._waitForAction()
   }
 
@@ -2337,30 +2350,24 @@ class Playwright extends Helper {
     }
     const els = await findFields.call(this, locator, context)
     if (els.length) {
-      const tag = await els[0].evaluate(el => el.tagName)
-      const type = await els[0].evaluate(el => el.type)
+      const el = selectElement(els, locator, this)
+      const tag = await el.evaluate(el => el.tagName)
+      const type = await el.evaluate(el => el.type)
       if (tag === 'INPUT' && type === 'file') {
-        await els[0].setInputFiles(file)
+        await el.setInputFiles(file)
         return this._waitForAction()
       }
     }
 
     const targetEls = els.length ? els : await this._locate(locator)
     assertElementExists(targetEls, locator, 'Element')
-    const base64Content = base64EncodeFile(file)
-    const fileName = path.basename(file)
-    const mimeType = getMimeType(fileName)
-    await targetEls[0].evaluate((el, { base64Content, fileName, mimeType }) => {
-      const binaryStr = atob(base64Content)
-      const bytes = new Uint8Array(binaryStr.length)
-      for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i)
-      const fileObj = new File([bytes], fileName, { type: mimeType })
-      const dataTransfer = new DataTransfer()
-      dataTransfer.items.add(fileObj)
-      el.dispatchEvent(new DragEvent('dragenter', { dataTransfer, bubbles: true }))
-      el.dispatchEvent(new DragEvent('dragover', { dataTransfer, bubbles: true }))
-      el.dispatchEvent(new DragEvent('drop', { dataTransfer, bubbles: true }))
-    }, { base64Content, fileName, mimeType })
+    const el = selectElement(targetEls, locator, this)
+    const fileData = {
+      base64Content: base64EncodeFile(file),
+      fileName: path.basename(file),
+      mimeType: getMimeType(path.basename(file)),
+    }
+    await el.evaluate(dropFile, fileData)
     return this._waitForAction()
   }
 
@@ -2383,23 +2390,23 @@ class Playwright extends Helper {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
       const els = contextEl ? await findElements.call(this, contextEl, matchedLocator) : await this._locate(matchedLocator)
       assertElementExists(els, select, 'Selectable element')
-      return proceedSelect.call(this, pageContext, els[0], option)
+      return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
     }
 
     // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
     const comboboxSearchCtx = contextEl || pageContext
     let els = await findByRole(comboboxSearchCtx, { role: 'combobox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, pageContext, els[0], option)
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try listbox
     els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, pageContext, els[0], option)
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try native select
     els = await findFields.call(this, select, context)
     assertElementExists(els, select, 'Selectable element')
-    return proceedSelect.call(this, pageContext, els[0], option)
+    return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
   }
 
   /**
@@ -4274,16 +4281,21 @@ async function proceedClick(locator, context = null, options = {}) {
     assertElementExists(els, locator, 'Clickable element')
   }
 
-  await highlightActiveElement.call(this, els[0])
-  if (store.debugMode) this.debugSection('Clicked', await elToString(els[0], 1))
+  const elementIndex = store.currentStep?.opts?.elementIndex
+  let element
+  if (elementIndex != null) {
+    element = selectElement(els, locator, this)
+  } else {
+    if (this.options.strict) assertOnlyOneElement(els, locator, this)
+    element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
+  }
+
+  await highlightActiveElement.call(this, element)
+  if (store.debugMode) this.debugSection('Clicked', await elToString(element, 1))
 
-  /*
-    using the force true options itself but instead dispatching a click
-  */
   if (options.force) {
-    await els[0].dispatchEvent('click')
+    await element.dispatchEvent('click')
   } else {
-    const element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
     await element.click(options)
   }
   const promises = []
@@ -4300,7 +4312,6 @@ async function findClickable(matcher, locator) {
 
   if (!matchedLocator.isFuzzy()) {
     const els = await findElements.call(this, matcher, matchedLocator)
-    if (this.options.strict) assertOnlyOneElement(els, locator)
     return els
   }
 
@@ -4309,42 +4320,27 @@ async function findClickable(matcher, locator) {
 
   try {
     els = await matcher.getByRole('button', { name: matchedLocator.value }).all()
-    if (els.length) {
-      if (this.options.strict) assertOnlyOneElement(els, locator)
-      return els
-    }
+    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) {
-      if (this.options.strict) assertOnlyOneElement(els, locator)
-      return els
-    }
+    if (els.length) return els
   } catch (err) {
     // getByRole not supported or failed
   }
 
   els = await findElements.call(this, matcher, Locator.clickable.narrow(literal))
-  if (els.length) {
-    if (this.options.strict) assertOnlyOneElement(els, locator)
-    return els
-  }
+  if (els.length) return els
 
   els = await findElements.call(this, matcher, Locator.clickable.wide(literal))
-  if (els.length) {
-    if (this.options.strict) assertOnlyOneElement(els, locator)
-    return els
-  }
+  if (els.length) return els
 
   try {
     els = await findElements.call(this, matcher, Locator.clickable.self(literal))
-    if (els.length) {
-      if (this.options.strict) assertOnlyOneElement(els, locator)
-      return els
-    }
+    if (els.length) return els
   } catch (err) {
     // Do nothing
   }
@@ -4619,9 +4615,10 @@ function assertElementExists(res, locator, prefix, suffix) {
   }
 }
 
-function assertOnlyOneElement(elements, locator) {
+function assertOnlyOneElement(elements, locator, helper) {
   if (elements.length > 1) {
-    throw new MultipleElementsFound(locator, elements)
+    const webElements = elements.map(el => new WebElement(el, helper))
+    throw new MultipleElementsFound(locator, webElements)
   }
 }
 

package/lib/helper/Puppeteer.js

@@ -33,14 +33,17 @@ 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'
 import { highlightElement } from './scripts/highlightElement.js'
 import { blurElement } from './scripts/blurElement.js'
+import { dropFile } from './scripts/dropFile.js'
 import { dontSeeElementError, seeElementError, dontSeeElementInDOMError, seeElementInDOMError } from './errors/ElementAssertion.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } from './network/actions.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
 
 let puppeteer
 
@@ -270,6 +273,7 @@ class Puppeteer extends Helper {
       show: false,
       defaultPopupAction: 'accept',
       highlightElement: false,
+      strict: false,
     }
 
     return Object.assign(defaults, config)
@@ -818,9 +822,26 @@ class Puppeteer extends Helper {
    * {{ react }}
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const el = await this._locateElement(locator)
-    if (!el) {
-      throw new ElementNotFound(locator, 'Element to move cursor to')
+    let context = null
+    if (typeof offsetX !== 'number') {
+      context = offsetX
+      offsetX = 0
+    }
+
+    let el
+    if (context) {
+      const contextEls = await findElements.call(this, this.page, context)
+      assertElementExists(contextEls, context, 'Context element')
+      const els = await findElements.call(this, contextEls[0], locator)
+      if (!els || els.length === 0) {
+        throw new ElementNotFound(locator, 'Element to move cursor to')
+      }
+      el = els[0]
+    } else {
+      el = await this._locateElement(locator)
+      if (!el) {
+        throw new ElementNotFound(locator, 'Element to move cursor to')
+      }
     }
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
@@ -988,6 +1009,14 @@ class Puppeteer extends Helper {
    */
   async _locateElement(locator) {
     const context = await this.context
+    const elementIndex = store.currentStep?.opts?.elementIndex
+    if (this.options.strict || elementIndex) {
+      const elements = await findElements.call(this, context, locator)
+      if (elements.length === 0) {
+        throw new ElementNotFound(locator, 'Element', 'was not found')
+      }
+      return selectElement(elements, locator, this)
+    }
     return findElement.call(this, context, locator)
   }
 
@@ -1005,7 +1034,7 @@ class Puppeteer extends Helper {
     if (!els || els.length === 0) {
       throw new ElementNotFound(locator, 'Checkbox or radio')
     }
-    return els[0]
+    return selectElement(els, locator, this)
   }
 
   /**
@@ -1564,7 +1593,7 @@ class Puppeteer extends Helper {
   async fillField(field, value, context = null) {
     const els = await findVisibleFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    const el = els[0]
+    const el = selectElement(els, field, this)
     const tag = await el.getProperty('tagName').then(el => el.jsonValue())
     const editable = await el.getProperty('contenteditable').then(el => el.jsonValue())
     if (tag === 'INPUT' || tag === 'TEXTAREA') {
@@ -1594,9 +1623,10 @@ class Puppeteer extends Helper {
   async appendField(field, value, context = null) {
     const els = await findVisibleFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    highlightActiveElement.call(this, els[0], await this._getContext())
-    await els[0].press('End')
-    await els[0].type(value.toString(), { delay: this.options.pressKeyDelay })
+    const el = selectElement(els, field, this)
+    highlightActiveElement.call(this, el, await this._getContext())
+    await el.press('End')
+    await el.type(value.toString(), { delay: this.options.pressKeyDelay })
     return this._waitForAction()
   }
 
@@ -1629,30 +1659,24 @@ class Puppeteer extends Helper {
     }
     const els = await findFields.call(this, locator, context)
     if (els.length) {
-      const tag = await els[0].evaluate(el => el.tagName)
-      const type = await els[0].evaluate(el => el.type)
+      const el = selectElement(els, locator, this)
+      const tag = await el.evaluate(el => el.tagName)
+      const type = await el.evaluate(el => el.type)
       if (tag === 'INPUT' && type === 'file') {
-        await els[0].uploadFile(file)
+        await el.uploadFile(file)
         return this._waitForAction()
       }
     }
 
     const targetEls = els.length ? els : await this._locate(locator)
     assertElementExists(targetEls, locator, 'Element')
-    const base64Content = base64EncodeFile(file)
-    const fileName = path.basename(file)
-    const mimeType = getMimeType(fileName)
-    await targetEls[0].evaluate((el, { base64Content, fileName, mimeType }) => {
-      const binaryStr = atob(base64Content)
-      const bytes = new Uint8Array(binaryStr.length)
-      for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i)
-      const fileObj = new File([bytes], fileName, { type: mimeType })
-      const dataTransfer = new DataTransfer()
-      dataTransfer.items.add(fileObj)
-      el.dispatchEvent(new DragEvent('dragenter', { dataTransfer, bubbles: true }))
-      el.dispatchEvent(new DragEvent('dragover', { dataTransfer, bubbles: true }))
-      el.dispatchEvent(new DragEvent('drop', { dataTransfer, bubbles: true }))
-    }, { base64Content, fileName, mimeType })
+    const el = selectElement(targetEls, locator, this)
+    const fileData = {
+      base64Content: base64EncodeFile(file),
+      fileName: path.basename(file),
+      mimeType: getMimeType(path.basename(file)),
+    }
+    await el.evaluate(dropFile, fileData)
     return this._waitForAction()
   }
 
@@ -1675,23 +1699,23 @@ class Puppeteer extends Helper {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
       const els = contextEl ? await findElements.call(this, contextEl, select) : await this._locate(select)
       assertElementExists(els, select, 'Selectable element')
-      return proceedSelect.call(this, pageContext, els[0], option)
+      return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
     }
 
     // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
     const comboboxSearchCtx = contextEl || pageContext
     let els = await findByRole(comboboxSearchCtx, { role: 'combobox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, pageContext, els[0], option)
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try listbox
     els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value })
-    if (els?.length) return proceedSelect.call(this, pageContext, els[0], option)
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
     // Fuzzy: try native select
     const visibleEls = await findVisibleFields.call(this, select, context)
     assertElementExists(visibleEls, select, 'Selectable field')
-    return proceedSelect.call(this, pageContext, visibleEls[0], option)
+    return proceedSelect.call(this, pageContext, selectElement(visibleEls, select, this), option)
   }
 
   /**
@@ -3098,10 +3122,11 @@ async function proceedClick(locator, context = null, options = {}) {
   } else {
     assertElementExists(els, locator, 'Clickable element')
   }
+  const el = selectElement(els, locator, this)
 
-  highlightActiveElement.call(this, els[0], await this._getContext())
+  highlightActiveElement.call(this, el, await this._getContext())
 
-  await els[0].click(options)
+  await el.click(options)
   const promises = []
   if (options.waitForNavigation) {
     promises.push(this.waitForNavigation())
@@ -3425,6 +3450,13 @@ function assertElementExists(res, locator, prefix, suffix) {
   }
 }
 
+function assertOnlyOneElement(elements, locator, helper) {
+  if (elements.length > 1) {
+    const webElements = elements.map(el => new WebElement(el, helper))
+    throw new MultipleElementsFound(locator, webElements)
+  }
+}
+
 function $XPath(element, selector) {
   const found = document.evaluate(selector, element || document.body, null, 5, null)
   const res = []

package/lib/helper/WebDriver.js

@@ -30,14 +30,17 @@ import {
 } from '../utils.js'
 import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import ElementNotFound from './errors/ElementNotFound.js'
+import MultipleElementsFound from './errors/MultipleElementsFound.js'
 import ConnectionRefused from './errors/ConnectionRefused.js'
 import Locator from '../locator.js'
 import { highlightElement } from './scripts/highlightElement.js'
 import { focusElement } from './scripts/focusElement.js'
 import { blurElement } from './scripts/blurElement.js'
 import { dontSeeElementError, seeElementError, seeElementInDOMError, dontSeeElementInDOMError } from './errors/ElementAssertion.js'
+import { dropFile } from './scripts/dropFile.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } from './network/actions.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
 
 const SHADOW = 'shadow'
 const webRoot = 'body'
@@ -503,6 +506,7 @@ class WebDriver extends Helper {
       keepBrowserState: false,
       deprecationWarnings: false,
       highlightElement: false,
+      strict: false,
     }
 
     // override defaults with config
@@ -1090,7 +1094,7 @@ class WebDriver extends Helper {
     } else {
       assertElementExists(res, locator, 'Clickable element')
     }
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, locator, this)
     highlightActiveElement.call(this, elem)
     return this.browser[clickMethod](getElementId(elem))
   }
@@ -1109,7 +1113,7 @@ class WebDriver extends Helper {
     } else {
       assertElementExists(res, locator, 'Clickable element')
     }
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, locator, this)
     highlightActiveElement.call(this, elem)
 
     return this.executeScript(el => {
@@ -1137,7 +1141,7 @@ class WebDriver extends Helper {
       assertElementExists(res, locator, 'Clickable element')
     }
 
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, locator, this)
     highlightActiveElement.call(this, elem)
     return elem.doubleClick()
   }
@@ -1157,7 +1161,7 @@ class WebDriver extends Helper {
       assertElementExists(res, locator, 'Clickable element')
     }
 
-    const el = usingFirstElement(res)
+    const el = selectElement(res, locator, this)
 
     await el.moveTo()
 
@@ -1272,7 +1276,7 @@ class WebDriver extends Helper {
   async fillField(field, value, context = null) {
     const res = await findFields.call(this, field, context)
     assertElementExists(res, field, 'Field')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     highlightActiveElement.call(this, elem)
     try {
       await elem.clearValue()
@@ -1295,7 +1299,7 @@ class WebDriver extends Helper {
   async appendField(field, value, context = null) {
     const res = await findFields.call(this, field, context)
     assertElementExists(res, field, 'Field')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     highlightActiveElement.call(this, elem)
     return elem.addValue(value.toString())
   }
@@ -1307,7 +1311,7 @@ class WebDriver extends Helper {
   async clearField(field, context = null) {
     const res = await findFields.call(this, field, context)
     assertElementExists(res, field, 'Field')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     highlightActiveElement.call(this, elem)
     return elem.clearValue(getElementId(elem))
   }
@@ -1324,22 +1328,22 @@ class WebDriver extends Helper {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
       const els = await locateFn(select)
       assertElementExists(els, select, 'Selectable element')
-      return proceedSelectOption.call(this, usingFirstElement(els), option)
+      return proceedSelectOption.call(this, selectElement(els, select, this), option)
     }
 
     // Fuzzy: try combobox
     this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
     let els = await this._locateByRole({ role: 'combobox', text: matchedLocator.value })
-    if (els?.length) return proceedSelectOption.call(this, usingFirstElement(els), option)
+    if (els?.length) return proceedSelectOption.call(this, selectElement(els, select, this), option)
 
     // Fuzzy: try listbox
     els = await this._locateByRole({ role: 'listbox', text: matchedLocator.value })
-    if (els?.length) return proceedSelectOption.call(this, usingFirstElement(els), option)
+    if (els?.length) return proceedSelectOption.call(this, selectElement(els, select, this), option)
 
     // Fuzzy: try native select
     const res = await findFields.call(this, select, context)
     assertElementExists(res, select, 'Selectable field')
-    return proceedSelectOption.call(this, usingFirstElement(res), option)
+    return proceedSelectOption.call(this, selectElement(res, select, this), option)
   }
 
   /**
@@ -1357,7 +1361,7 @@ class WebDriver extends Helper {
     this.debug(`Uploading ${file}`)
 
     if (res.length) {
-      const el = usingFirstElement(res)
+      const el = selectElement(res, locator, this)
       const tag = await this.browser.execute(function (elem) { return elem.tagName }, el)
       const type = await this.browser.execute(function (elem) { return elem.type }, el)
       if (tag === 'INPUT' && type === 'file') {
@@ -1375,21 +1379,13 @@ class WebDriver extends Helper {
 
     const targetRes = res.length ? res : await this._locate(locator)
     assertElementExists(targetRes, locator, 'Element')
-    const targetEl = usingFirstElement(targetRes)
-    const base64Content = base64EncodeFile(file)
-    const fileName = path.basename(file)
-    const mimeType = getMimeType(fileName)
-    return this.browser.execute(function (el, data) {
-      var binaryStr = atob(data.base64Content)
-      var bytes = new Uint8Array(binaryStr.length)
-      for (var i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i)
-      var fileObj = new File([bytes], data.fileName, { type: data.mimeType })
-      var dataTransfer = new DataTransfer()
-      dataTransfer.items.add(fileObj)
-      el.dispatchEvent(new DragEvent('dragenter', { dataTransfer: dataTransfer, bubbles: true }))
-      el.dispatchEvent(new DragEvent('dragover', { dataTransfer: dataTransfer, bubbles: true }))
-      el.dispatchEvent(new DragEvent('drop', { dataTransfer: dataTransfer, bubbles: true }))
-    }, targetEl, { base64Content, fileName, mimeType })
+    const targetEl = selectElement(targetRes, locator, this)
+    const fileData = {
+      base64Content: base64EncodeFile(file),
+      fileName: path.basename(file),
+      mimeType: getMimeType(path.basename(file)),
+    }
+    return this.browser.execute(dropFile, targetEl, fileData)
   }
 
   /**
@@ -1403,7 +1399,7 @@ class WebDriver extends Helper {
     const res = await findCheckable.call(this, field, locateFn)
 
     assertElementExists(res, field, 'Checkable')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     const elementId = getElementId(elem)
     highlightActiveElement.call(this, elem)
 
@@ -1424,7 +1420,7 @@ class WebDriver extends Helper {
     const res = await findCheckable.call(this, field, locateFn)
 
     assertElementExists(res, field, 'Checkable')
-    const elem = usingFirstElement(res)
+    const elem = selectElement(res, field, this)
     const elementId = getElementId(elem)
     highlightActiveElement.call(this, elem)
 
@@ -1974,8 +1970,22 @@ class WebDriver extends Helper {
    * {{> moveCursorTo }}
    */
   async moveCursorTo(locator, xOffset, yOffset) {
-    const res = await this._locate(withStrictLocator(locator), true)
-    assertElementExists(res, locator)
+    let context = null
+    if (typeof xOffset !== 'number' && xOffset !== undefined) {
+      context = xOffset
+      xOffset = undefined
+    }
+
+    let res
+    if (context) {
+      const contextRes = await this._locate(withStrictLocator(context), true)
+      assertElementExists(contextRes, context, 'Context element')
+      res = await contextRes[0].$$(withStrictLocator(locator))
+      assertElementExists(res, locator)
+    } else {
+      res = await this._locate(withStrictLocator(locator), true)
+      assertElementExists(res, locator)
+    }
     const elem = usingFirstElement(res)
     try {
       await elem.moveTo({ xOffset, yOffset })
@@ -3285,10 +3295,30 @@ function assertElementExists(res, locator, prefix, suffix) {
 }
 
 function usingFirstElement(els) {
+  const rawIndex = store.currentStep?.opts?.elementIndex
+  if (rawIndex != null && els.length > 1) {
+    let elementIndex = rawIndex
+    if (elementIndex === 'first') elementIndex = 1
+    if (elementIndex === 'last') elementIndex = -1
+    if (Number.isInteger(elementIndex) && elementIndex !== 0) {
+      const idx = elementIndex > 0 ? elementIndex - 1 : els.length + elementIndex
+      if (idx >= 0 && idx < els.length) {
+        debug(`[Elements] Using element #${rawIndex} out of ${els.length}`)
+        return els[idx]
+      }
+    }
+  }
   if (els.length > 1) debug(`[Elements] Using first element out of ${els.length}`)
   return els[0]
 }
 
+function assertOnlyOneElement(elements, locator, helper) {
+  if (elements.length > 1) {
+    const webElements = Array.from(elements).map(el => new WebElement(el, helper))
+    throw new MultipleElementsFound(locator, webElements)
+  }
+}
+
 function getElementId(el) {
   // W3C WebDriver web element identifier
   // https://w3c.github.io/webdriver/#dfn-web-element-identifier

package/lib/helper/errors/MultipleElementsFound.js

@@ -1,40 +1,45 @@
 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.`)
+  constructor(locator, webElements) {
+    const locatorStr = (typeof locator === 'object' && !(locator instanceof Locator))
+      ? new Locator(locator).toString()
+      : String(locator)
+    super(`Multiple elements (${webElements.length}) found for "${locatorStr}" in strict mode. Call fetchDetails() for full information.`)
     this.name = 'MultipleElementsFound'
     this.locator = locator
-    this.elements = elements
-    this.count = elements.length
+    this.webElements = webElements
+    this.count = webElements.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 items = []
+      const maxToShow = Math.min(this.count, 10)
+
+      for (let i = 0; i < maxToShow; i++) {
+        const webEl = this.webElements[i]
+        try {
+          const xpath = await webEl.toAbsoluteXPath()
+          const html = await webEl.toSimplifiedHTML()
+          items.push(`  ${i + 1}. > ${xpath}\n     ${html}`)
+        } catch (err) {
+          items.push(`  ${i + 1}. [Unable to get element info: ${err.message}]`)
+        }
       }
 
-      const locatorObj = new Locator(this.locator)
-      const elementList = await this._generateElementList(this.elements, this.count)
+      if (this.count > 10) {
+        items.push(`  ... and ${this.count - 10} more`)
+      }
 
-      this.message = `Multiple elements (${this.count}) found for "${locatorObj.toString()}" in strict mode.\n` +
-        elementList +
+      const locatorStr = (typeof this.locator === 'object' && !(this.locator instanceof Locator))
+        ? new Locator(this.locator).toString()
+        : String(this.locator)
+      this.message = `Multiple elements (${this.count}) found for "${locatorStr}" in strict mode.\n` +
+        items.join('\n') +
         `\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}`
@@ -42,94 +47,6 @@ class MultipleElementsFound extends Error {
 
     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/helper/extras/elementSelection.js

@@ -0,0 +1,51 @@
+import store from '../../store.js'
+import output from '../../output.js'
+import WebElement from '../../element/WebElement.js'
+import MultipleElementsFound from '../errors/MultipleElementsFound.js'
+
+function resolveElementIndex(value) {
+  if (value === 'first') return 1
+  if (value === 'last') return -1
+  return value
+}
+
+function selectElement(els, locator, helper) {
+  const rawIndex = store.currentStep?.opts?.elementIndex
+  const elementIndex = resolveElementIndex(rawIndex)
+
+  if (elementIndex != null) {
+    if (els.length === 1) return els[0]
+
+    if (!Number.isInteger(elementIndex) || elementIndex === 0) {
+      throw new Error(`elementIndex must be a non-zero integer or 'first'/'last', got: ${rawIndex}`)
+    }
+
+    let idx
+    if (elementIndex > 0) {
+      idx = elementIndex - 1
+      if (idx >= els.length) {
+        throw new Error(`elementIndex ${elementIndex} exceeds the number of elements found (${els.length}) for "${locator}"`)
+      }
+    } else {
+      idx = els.length + elementIndex
+      if (idx < 0) {
+        throw new Error(`elementIndex ${elementIndex} exceeds the number of elements found (${els.length}) for "${locator}"`)
+      }
+    }
+
+    output.debug(`[Elements] Using element #${elementIndex} out of ${els.length}`)
+    return els[idx]
+  }
+
+  if (helper.options.strict) {
+    if (els.length > 1) {
+      const webElements = els.map(el => new WebElement(el, helper))
+      throw new MultipleElementsFound(locator, webElements)
+    }
+  }
+
+  if (els.length > 1) output.debug(`[Elements] Using first element out of ${els.length}`)
+  return els[0]
+}
+
+export { selectElement }

package/lib/helper/scripts/dropFile.js

@@ -0,0 +1,11 @@
+export const dropFile = (el, { base64Content, fileName, mimeType }) => {
+  const binaryStr = atob(base64Content)
+  const bytes = new Uint8Array(binaryStr.length)
+  for (let i = 0; i < binaryStr.length; i++) bytes[i] = binaryStr.charCodeAt(i)
+  const fileObj = new File([bytes], fileName, { type: mimeType })
+  const dataTransfer = new DataTransfer()
+  dataTransfer.items.add(fileObj)
+  el.dispatchEvent(new DragEvent('dragenter', { dataTransfer, bubbles: true }))
+  el.dispatchEvent(new DragEvent('dragover', { dataTransfer, bubbles: true }))
+  el.dispatchEvent(new DragEvent('drop', { dataTransfer, bubbles: true }))
+}

package/lib/html.js

@@ -245,4 +245,17 @@ function splitByChunks(text, chunkSize) {
   return chunks.map(chunk => chunk.trim())
 }
 
-export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml }
+function simplifyHtmlElement(html, maxLength = 300) {
+  try {
+    html = removeNonInteractiveElements(html)
+    html = html.replace(/<html>(?:<head>.*?<\/head>)?<body>(.*)<\/body><\/html>/s, '$1').trim()
+  } catch (e) {
+    // keep raw html if minification fails
+  }
+  if (html.length > maxLength) {
+    html = html.slice(0, maxLength) + '...'
+  }
+  return html
+}
+
+export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml, simplifyHtmlElement }

package/lib/mocha/cli.js

@@ -202,6 +202,16 @@ class Cli extends Base {
 
     // failures
     if (stats.failures) {
+      for (const test of this.failures) {
+        if (test.err && typeof test.err.fetchDetails === 'function') {
+          try {
+            await test.err.fetchDetails()
+          } catch (e) {
+            // ignore fetch errors
+          }
+        }
+      }
+
       // append step traces
       this.failures = this.failures.map(test => {
         // we will change the stack trace, so we need to clone the test

package/lib/step/config.js

@@ -1,10 +1,16 @@
+/**
+ * @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} [ignoreCase] - Perform case-insensitive text matching.
+ */
+
 /**
  * StepConfig is a configuration object for a step.
  * It is used to create a new step that is a combination of other steps.
  */
 class StepConfig {
   constructor(opts = {}) {
-    /** @member {{ opts: Record<string, any>, timeout: number|undefined, retry: number|undefined }} */
+    /** @member {{ opts: StepOptions, timeout: number|undefined, retry: number|undefined }} */
     this.config = {
       opts,
       timeout: undefined,
@@ -14,7 +20,7 @@ class StepConfig {
 
   /**
    * Set the options for the step.
-   * @param {object} opts - The options for the step.
+   * @param {StepOptions} opts - The options for the step.
    * @returns {StepConfig} - The step configuration object.
    */
   opts(opts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.0-rc.7",
+  "version": "4.0.0-rc.9",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [

package/typings/index.d.ts

@@ -745,3 +745,22 @@ declare module 'codeceptjs/effects' {
   export const retryTo: RetryTo
   export const hopeThat: HopeThat
 }
+
+declare module 'codeceptjs/steps' {
+  const step: {
+    opts(opts: CodeceptJS.StepOptions): CodeceptJS.StepConfig;
+    timeout(timeout: number): CodeceptJS.StepConfig;
+    retry(retry: number): CodeceptJS.StepConfig;
+    stepOpts(opts: CodeceptJS.StepOptions): CodeceptJS.StepConfig;
+    stepTimeout(timeout: number): CodeceptJS.StepConfig;
+    stepRetry(retry: number): CodeceptJS.StepConfig;
+    section(name: string): any;
+    endSection(): any;
+    Section(name: string): any;
+    EndSection(): any;
+    Given(): any;
+    When(): any;
+    Then(): any;
+  }
+  export default step
+}