codeceptjs 4.0.0-rc.1 → 4.0.0-rc.10

package/lib/helper/WebDriver.js

@@ -1,5 +1,6 @@
 let webdriverio
 
+import fs from 'fs'
 import assert from 'assert'
 import path from 'path'
 import crypto from 'crypto'
@@ -13,17 +14,33 @@ import output from '../output.js'
 const { debug } = output
 import { empty } from '../assert/empty.js'
 import { truth } from '../assert/truth.js'
-import { xpathLocator, fileExists, decodeUrl, chunkArray, convertCssPropertiesToCamelCase, screenshotOutputFolder, getNormalizedKeyAttributeValue, modifierKeys } from '../utils.js'
+import {
+  xpathLocator,
+  fileExists,
+  decodeUrl,
+  chunkArray,
+  convertCssPropertiesToCamelCase,
+  screenshotOutputFolder,
+  getNormalizedKeyAttributeValue,
+  modifierKeys,
+  normalizePath,
+  resolveUrl,
+  getMimeType,
+  base64EncodeFile,
+} 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'
@@ -489,6 +506,7 @@ class WebDriver extends Helper {
       keepBrowserState: false,
       deprecationWarnings: false,
       highlightElement: false,
+      strict: false,
     }
 
     // override defaults with config
@@ -1076,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))
   }
@@ -1095,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 => {
@@ -1123,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()
   }
@@ -1143,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()
 
@@ -1255,10 +1273,10 @@ class WebDriver extends Helper {
    * {{ custom }}
    *
    */
-  async fillField(field, value) {
-    const res = await findFields.call(this, field)
+  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()
@@ -1278,10 +1296,10 @@ class WebDriver extends Helper {
    * {{> appendField }}
    * {{ react }}
    */
-  async appendField(field, value) {
-    const res = await findFields.call(this, field)
+  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())
   }
@@ -1290,10 +1308,10 @@ class WebDriver extends Helper {
    * {{> clearField }}
    *
    */
-  async clearField(field) {
-    const res = await findFields.call(this, field)
+  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))
   }
@@ -1301,30 +1319,31 @@ class WebDriver extends Helper {
   /**
    * {{> selectOption }}
    */
-  async selectOption(select, option) {
+  async selectOption(select, option, context = null) {
+    const locateFn = prepareLocateFn.call(this, context)
     const matchedLocator = new Locator(select)
 
     // Strict locator
     if (!matchedLocator.isFuzzy()) {
       this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
-      const els = await this._locate(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)
+    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)
   }
 
   /**
@@ -1332,28 +1351,41 @@ class WebDriver extends Helper {
    *
    * {{> attachFile }}
    */
-  async attachFile(locator, pathToFile) {
+  async attachFile(locator, pathToFile, context = null) {
     let file = path.join(global.codecept_dir, pathToFile)
     if (!fileExists(file)) {
       throw new Error(`File at ${file} can not be found on local system`)
     }
 
-    const res = await findFields.call(this, locator)
+    const res = await findFields.call(this, locator, context)
     this.debug(`Uploading ${file}`)
-    assertElementExists(res, locator, 'File field')
-    const el = usingFirstElement(res)
 
-    // Remote Upload (when running Selenium Server)
-    if (this.options.remoteFileUpload) {
-      try {
-        this.debugSection('File', 'Uploading file to remote server')
-        file = await this.browser.uploadFile(file)
-      } catch (err) {
-        throw new Error(`File can't be transferred to remote server. Set \`remoteFileUpload: false\` in config to upload file locally.\n${err.message}`)
+    if (res.length) {
+      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') {
+        if (this.options.remoteFileUpload) {
+          try {
+            this.debugSection('File', 'Uploading file to remote server')
+            file = await this.browser.uploadFile(file)
+          } catch (err) {
+            throw new Error(`File can't be transferred to remote server. Set \`remoteFileUpload: false\` in config to upload file locally.\n${err.message}`)
+          }
+        }
+        return el.addValue(file)
       }
     }
 
-    return el.addValue(file)
+    const targetRes = res.length ? res : await this._locate(locator)
+    assertElementExists(targetRes, locator, 'Element')
+    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)
   }
 
   /**
@@ -1367,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)
 
@@ -1388,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)
 
@@ -1586,18 +1618,18 @@ class WebDriver extends Helper {
    * {{> seeInField }}
    *
    */
-  async seeInField(field, value) {
+  async seeInField(field, value, context = null) {
     const _value = typeof value === 'boolean' ? value : value.toString()
-    return proceedSeeField.call(this, 'assert', field, _value)
+    return proceedSeeField.call(this, 'assert', field, _value, context)
   }
 
   /**
    * {{> dontSeeInField }}
    *
    */
-  async dontSeeInField(field, value) {
+  async dontSeeInField(field, value, context = null) {
     const _value = typeof value === 'boolean' ? value : value.toString()
-    return proceedSeeField.call(this, 'negate', field, _value)
+    return proceedSeeField.call(this, 'negate', field, _value, context)
   }
 
   /**
@@ -1621,8 +1653,9 @@ class WebDriver extends Helper {
    * {{ react }}
    *
    */
-  async seeElement(locator) {
-    const res = await this._locate(locator, true)
+  async seeElement(locator, context = null) {
+    const locateFn = prepareLocateFn.call(this, context)
+    const res = context ? await locateFn(locator) : await this._locate(locator, true)
     assertElementExists(res, locator)
     const selected = await forEachAsync(res, async el => el.isDisplayed())
     try {
@@ -1636,8 +1669,9 @@ class WebDriver extends Helper {
    * {{> dontSeeElement }}
    * {{ react }}
    */
-  async dontSeeElement(locator) {
-    const res = await this._locate(locator, false)
+  async dontSeeElement(locator, context = null) {
+    const locateFn = prepareLocateFn.call(this, context)
+    const res = context ? await locateFn(locator) : await this._locate(locator, false)
     if (!res || res.length === 0) {
       return truth(`elements of ${new Locator(locator)}`, 'to be seen').negate(false)
     }
@@ -1844,6 +1878,26 @@ class WebDriver extends Helper {
     return urlEquals(this.options.url).negate(url, decodeUrl(res))
   }
 
+  /**
+   * {{> seeCurrentPathEquals }}
+   */
+  async seeCurrentPathEquals(path) {
+    const currentUrl = await this.browser.getUrl()
+    const baseUrl = this.options.url || 'http://localhost'
+    const actualPath = new URL(currentUrl, baseUrl).pathname
+    return equals('url path').assert(normalizePath(path), normalizePath(actualPath))
+  }
+
+  /**
+   * {{> dontSeeCurrentPathEquals }}
+   */
+  async dontSeeCurrentPathEquals(path) {
+    const currentUrl = await this.browser.getUrl()
+    const baseUrl = this.options.url || 'http://localhost'
+    const actualPath = new URL(currentUrl, baseUrl).pathname
+    return equals('url path').negate(normalizePath(path), normalizePath(actualPath))
+  }
+
   /**
    * Wraps [execute](http://webdriver.io/api/protocol/execute.html) command.
    *
@@ -1916,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 })
@@ -2467,6 +2535,7 @@ class WebDriver extends Helper {
   async waitInUrl(urlPart, sec = null) {
     const client = this.browser
     const aSec = sec || this.options.waitForTimeoutInSeconds
+    const expectedUrl = resolveUrl(urlPart, this.options.url)
     let currUrl = ''
 
     return client
@@ -2474,7 +2543,7 @@ class WebDriver extends Helper {
         function () {
           return this.getUrl().then(res => {
             currUrl = decodeUrl(res)
-            return currUrl.indexOf(urlPart) > -1
+            return currUrl.indexOf(expectedUrl) > -1
           })
         },
         { timeout: aSec * 1000 },
@@ -2482,7 +2551,7 @@ class WebDriver extends Helper {
       .catch(e => {
         e = wrapError(e)
         if (e.message.indexOf('timeout')) {
-          throw new Error(`expected url to include ${urlPart}, but found ${currUrl}`)
+          throw new Error(`expected url to include ${expectedUrl}, but found ${currUrl}`)
         }
         throw e
       })
@@ -2493,22 +2562,47 @@ class WebDriver extends Helper {
    */
   async waitUrlEquals(urlPart, sec = null) {
     const aSec = sec || this.options.waitForTimeoutInSeconds
-    const baseUrl = this.options.url
-    if (urlPart.indexOf('http') < 0) {
-      urlPart = baseUrl + urlPart
-    }
+    const expectedUrl = resolveUrl(urlPart, this.options.url)
     let currUrl = ''
     return this.browser
       .waitUntil(function () {
         return this.getUrl().then(res => {
           currUrl = decodeUrl(res)
-          return currUrl === urlPart
+          return currUrl === expectedUrl
         })
       }, aSec * 1000)
       .catch(e => {
         e = wrapError(e)
         if (e.message.indexOf('timeout')) {
-          throw new Error(`expected url to be ${urlPart}, but found ${currUrl}`)
+          throw new Error(`expected url to be ${expectedUrl}, but found ${currUrl}`)
+        }
+        throw e
+      })
+  }
+
+  /**
+   * {{> waitCurrentPathEquals }}
+   */
+  async waitCurrentPathEquals(path, sec = null) {
+    const aSec = sec || this.options.waitForTimeoutInSeconds
+    const normalizedPath = normalizePath(path)
+    const baseUrl = this.options.url || 'http://localhost'
+    let actualPath = ''
+
+    return this.browser
+      .waitUntil(
+        async () => {
+          const currUrl = await this.browser.getUrl()
+          const url = new URL(currUrl, baseUrl)
+          actualPath = url.pathname
+          return normalizePath(actualPath) === normalizedPath
+        },
+        { timeout: aSec * 1000 },
+      )
+      .catch(e => {
+        e = wrapError(e)
+        if (e.message.indexOf('timeout')) {
+          throw new Error(`expected path to be ${normalizedPath}, but found ${normalizePath(actualPath)}`)
         }
         throw e
       })
@@ -2990,32 +3084,33 @@ async function findClickable(locator, locateFn) {
   return await locateFn(locator.value) // by css or xpath
 }
 
-async function findFields(locator) {
+async function findFields(locator, context = null) {
+  const locateFn = prepareLocateFn.call(this, context)
   locator = new Locator(locator)
 
   if (this._isCustomLocator(locator)) {
-    return this._locate(locator)
+    return locateFn(locator)
   }
 
-  if (locator.isAccessibilityId() && !this.isWeb) return this._locate(locator, true)
-  if (locator.isRole()) return this._locate(locator, true)
-  if (!locator.isFuzzy()) return this._locate(locator, true)
+  if (locator.isAccessibilityId() && !this.isWeb) return locateFn(locator)
+  if (locator.isRole()) return locateFn(locator)
+  if (!locator.isFuzzy()) return locateFn(locator)
 
   const literal = xpathLocator.literal(locator.value)
-  let els = await this._locate(Locator.field.labelEquals(literal))
+  let els = await locateFn(Locator.field.labelEquals(literal))
   if (els.length) return els
 
-  els = await this._locate(Locator.field.labelContains(literal))
+  els = await locateFn(Locator.field.labelContains(literal))
   if (els.length) return els
 
-  els = await this._locate(Locator.field.byName(literal))
+  els = await locateFn(Locator.field.byName(literal))
   if (els.length) return els
 
-  return await this._locate(locator.value) // by css or xpath
+  return await locateFn(locator.value) // by css or xpath
 }
 
-async function proceedSeeField(assertType, field, value) {
-  const res = await findFields.call(this, field)
+async function proceedSeeField(assertType, field, value, context) {
+  const res = await findFields.call(this, field, context)
   assertElementExists(res, field, 'Field')
   const elem = usingFirstElement(res)
   const elemId = getElementId(elem)
@@ -3200,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