codeceptjs 4.0.2-beta.9 → 4.0.2

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'
@@ -9,21 +10,39 @@ import promiseRetry from 'promise-retry'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import store from '../store.js'
+import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
 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'
+import { fillRichEditor } from './extras/richTextEditor.js'
 
 const SHADOW = 'shadow'
 const webRoot = 'body'
@@ -78,11 +97,7 @@ const config = {}
  * WebDriver helper which wraps [webdriverio](http://webdriver.io/) library to
  * manipulate browser using Selenium WebDriver or PhantomJS.
  *
- * WebDriver requires Selenium Server and ChromeDriver/GeckoDriver to be installed. Those tools can be easily installed via NPM. Please check [Testing with WebDriver](https://codecept.io/webdriver/#testing-with-webdriver) for more details.
- *
- * With the release of WebdriverIO version v8.14.0, and onwards, all driver management hassles are now a thing of the past 🙌. Read more [here](https://webdriver.io/blog/2023/07/31/driver-management/).
- * One of the significant advantages of this update is that you can now get rid of any driver services you previously had to manage, such as
- * `wdio-chromedriver-service`, `wdio-geckodriver-service`, `wdio-edgedriver-service`, `wdio-safaridriver-service`, and even `@wdio/selenium-standalone-service`.
+ * No Selenium Server, ChromeDriver, or GeckoDriver to install or start. Since WebdriverIO 9, driver management is fully automatic — WebdriverIO downloads and starts the matching driver for you. Read more [here](https://webdriver.io/blog/2023/07/31/driver-management/). Please check [Testing with WebDriver](https://codecept.io/webdriver/#testing-with-webdriver) for more details.
  *
  * For those who require custom driver options, fear not; WebDriver Helper allows you to pass in driver options through custom WebDriver configuration.
  * If you have a custom grid, use a cloud service, or prefer to run your own driver, there's no need to worry since WebDriver Helper will only start a driver when there are no other connection information settings like hostname or port specified.
@@ -489,6 +504,7 @@ class WebDriver extends Helper {
       keepBrowserState: false,
       deprecationWarnings: false,
       highlightElement: false,
+      strict: false,
     }
 
     // override defaults with config
@@ -888,13 +904,6 @@ class WebDriver extends Helper {
       return els
     }
 
-    // special locator type for React
-    if (locator.react) {
-      const els = await this.browser.react$$(locator.react, locator.props || undefined, locator.state || undefined)
-      this.debugSection('Elements', `Found ${els.length} react components`)
-      return els
-    }
-
     // special locator type for ARIA roles
     if (locator.role) {
       return this._locateByRole(locator)
@@ -1064,7 +1073,6 @@ class WebDriver extends Helper {
   /**
    * {{> click }}
    *
-   * {{ react }}
    */
   async click(locator, context = null) {
     const clickMethod = this.browser.isMobile && this.browser.capabilities.platformName !== 'android' ? 'touchClick' : 'elementClick'
@@ -1076,7 +1084,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))
   }
@@ -1084,7 +1092,6 @@ class WebDriver extends Helper {
   /**
    * {{> forceClick }}
    *
-   * {{ react }}
    */
   async forceClick(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1095,7 +1102,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 => {
@@ -1111,7 +1118,6 @@ class WebDriver extends Helper {
   /**
    * {{> doubleClick }}
    *
-   * {{ react }}
    */
   async doubleClick(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1123,7 +1129,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()
   }
@@ -1131,7 +1137,6 @@ class WebDriver extends Helper {
   /**
    * {{> rightClick }}
    *
-   * {{ react }}
    */
   async rightClick(locator, context) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1143,7 +1148,7 @@ class WebDriver extends Helper {
       assertElementExists(res, locator, 'Clickable element')
     }
 
-    const el = usingFirstElement(res)
+    const el = selectElement(res, locator, this)
 
     await el.moveTo()
 
@@ -1226,7 +1231,6 @@ class WebDriver extends Helper {
   /**
    * {{> forceRightClick }}
    *
-   * {{ react }}
    */
   async forceRightClick(locator, context = null) {
     const locateFn = prepareLocateFn.call(this, context)
@@ -1251,15 +1255,19 @@ class WebDriver extends Helper {
 
   /**
    * {{> fillField }}
-   * {{ react }}
    * {{ 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)
+
+    if (await fillRichEditor(this, elem, value)) {
+      return
+    }
+
     try {
       await elem.clearValue()
     } catch (err) {
@@ -1276,12 +1284,11 @@ 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 +1297,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,34 +1308,31 @@ class WebDriver extends Helper {
   /**
    * {{> selectOption }}
    */
-  async selectOption(select, option) {
-    const res = await findFields.call(this, select)
-    assertElementExists(res, select, 'Selectable field')
-    const elem = usingFirstElement(res)
-    highlightActiveElement.call(this, elem)
+  async selectOption(select, option, context = null) {
+    const locateFn = prepareLocateFn.call(this, context)
+    const matchedLocator = new Locator(select)
 
-    if (!Array.isArray(option)) {
-      option = [option]
+    // Strict locator
+    if (!matchedLocator.isFuzzy()) {
+      this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
+      const els = await locateFn(select)
+      assertElementExists(els, select, 'Selectable element')
+      return proceedSelectOption.call(this, selectElement(els, select, this), option)
     }
 
-    // select options by visible text
-    let els = await forEachAsync(option, async opt => this.browser.findElementsFromElement(getElementId(elem), 'xpath', Locator.select.byVisibleText(xpathLocator.literal(opt))))
+    // 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, selectElement(els, select, this), option)
 
-    const clickOptionFn = async el => {
-      if (el[0]) el = el[0]
-      const elementId = getElementId(el)
-      if (elementId) return this.browser.elementClick(elementId)
-    }
+    // Fuzzy: try listbox
+    els = await this._locateByRole({ role: 'listbox', text: matchedLocator.value })
+    if (els?.length) return proceedSelectOption.call(this, selectElement(els, select, this), option)
 
-    if (Array.isArray(els) && els.length) {
-      return forEachAsync(els, clickOptionFn)
-    }
-    // select options by value
-    els = await forEachAsync(option, async opt => this.browser.findElementsFromElement(getElementId(elem), 'xpath', Locator.select.byValue(xpathLocator.literal(opt))))
-    if (els.length === 0) {
-      throw new ElementNotFound(select, `Option "${option}" in`, 'was not found neither by a visible text nor by a value')
-    }
-    return forEachAsync(els, clickOptionFn)
+    // Fuzzy: try native select
+    const res = await findFields.call(this, select, context)
+    assertElementExists(res, select, 'Selectable field')
+    return proceedSelectOption.call(this, selectElement(res, select, this), option)
   }
 
   /**
@@ -1336,28 +1340,41 @@ class WebDriver extends Helper {
    *
    * {{> attachFile }}
    */
-  async attachFile(locator, pathToFile) {
-    let file = path.join(global.codecept_dir, pathToFile)
+  async attachFile(locator, pathToFile, context = null) {
+    let file = path.join(store.codeceptDir, 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)
   }
 
   /**
@@ -1371,7 +1388,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)
 
@@ -1392,7 +1409,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)
 
@@ -1564,7 +1581,6 @@ class WebDriver extends Helper {
   /**
    * {{> see }}
    *
-   * {{ react }}
    */
   async see(text, context = null) {
     return proceedSee.call(this, 'assert', text, context)
@@ -1580,7 +1596,6 @@ class WebDriver extends Helper {
   /**
    * {{> dontSee }}
    *
-   * {{ react }}
    */
   async dontSee(text, context = null) {
     return proceedSee.call(this, 'negate', text, context)
@@ -1590,18 +1605,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)
   }
 
   /**
@@ -1622,11 +1637,11 @@ class WebDriver extends Helper {
 
   /**
    * {{> seeElement }}
-   * {{ 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 {
@@ -1638,10 +1653,10 @@ 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)
     }
@@ -1722,7 +1737,6 @@ class WebDriver extends Helper {
 
   /**
    * {{> seeNumberOfElements }}
-   * {{ react }}
    */
   async seeNumberOfElements(locator, num) {
     const res = await this._locate(locator)
@@ -1731,7 +1745,6 @@ class WebDriver extends Helper {
 
   /**
    * {{> seeNumberOfVisibleElements }}
-   * {{ react }}
    */
   async seeNumberOfVisibleElements(locator, num) {
     const res = await this.grabNumberOfVisibleElements(locator)
@@ -1848,6 +1861,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.
    *
@@ -1920,8 +1953,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 })
@@ -2173,6 +2220,7 @@ class WebDriver extends Helper {
    * {{> pressKeyWithKeyNormalization }}
    */
   async pressKey(key) {
+    await checkFocusBeforePressKey(this, key)
     const modifiers = []
     if (Array.isArray(key)) {
       for (let k of key) {
@@ -2219,6 +2267,8 @@ class WebDriver extends Helper {
    * {{> type }}
    */
   async type(keys, delay = null) {
+    await checkFocusBeforeType(this)
+
     if (!Array.isArray(keys)) {
       keys = keys.toString()
       keys = keys.split('')
@@ -2471,6 +2521,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
@@ -2478,7 +2529,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 },
@@ -2486,7 +2537,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
       })
@@ -2497,22 +2548,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
       })
@@ -2994,32 +3070,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)
@@ -3128,7 +3205,23 @@ async function getElementTextAttributes(element) {
   const ariaLabel = await this.browser.getElementAttribute(elementId, 'aria-label').catch(() => '')
   const placeholder = await this.browser.getElementAttribute(elementId, 'placeholder').catch(() => '')
   const innerText = await this.browser.getElementText(elementId).catch(() => '')
-  return [ariaLabel, placeholder, innerText]
+
+  // Handle aria-labelledby
+  const labelledBy = await this.browser.getElementAttribute(elementId, 'aria-labelledby').catch(() => '')
+  let labelText = ''
+  if (labelledBy) {
+    try {
+      const labelId = labelledBy.split(' ')[0]
+      const labelEls = await this.browser.$$(`#${labelId}`)
+      if (labelEls?.length) {
+        labelText = await this.browser.getElementText(getElementId(labelEls[0])).catch(() => '')
+      }
+    } catch (e) {
+      // Ignore errors when resolving aria-labelledby
+    }
+  }
+
+  return [ariaLabel, placeholder, innerText, labelText]
 }
 
 async function isElementChecked(browser, elementId) {
@@ -3188,10 +3281,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
@@ -3353,7 +3466,7 @@ function isModifierKey(key) {
 }
 
 function highlightActiveElement(element) {
-  if (this.options.highlightElement && global.debugMode) {
+  if (this.options.highlightElement && store.debugMode) {
     highlightElement(element, this.browser)
   }
 }
@@ -3364,9 +3477,6 @@ function prepareLocateFn(context) {
     l = new Locator(l, 'css')
     return this._locate(context, true).then(async res => {
       assertElementExists(res, context, 'Context element')
-      if (l.react) {
-        return res[0].react$$(l.react, l.props || undefined)
-      }
       return res[0].$$(l.simplify())
     })
   }
@@ -3376,4 +3486,107 @@ function logEvents(event) {
   browserLogs.push(event.text) // add log message to the array
 }
 
+async function proceedSelectOption(elem, option) {
+  const elementId = getElementId(elem)
+  const role = await this.browser.getElementAttribute(elementId, 'role').catch(() => null)
+  const options = Array.isArray(option) ? option : [option]
+
+  if (role === 'combobox') {
+    this.debugSection('SelectOption', 'Expanding combobox')
+    highlightActiveElement.call(this, elem)
+    const ariaOwns = await this.browser.getElementAttribute(elementId, 'aria-owns').catch(() => null)
+    const ariaControls = await this.browser.getElementAttribute(elementId, 'aria-controls').catch(() => null)
+    const ariaLabelledBy = await this.browser.getElementAttribute(elementId, 'aria-labelledby').catch(() => null)
+    await this.browser.elementClick(elementId)
+
+    const listboxId = ariaOwns || ariaControls
+    let listbox = null
+    if (listboxId) {
+      const listboxEls = await this.browser.$$(`#${listboxId}`)
+      if (listboxEls?.length) listbox = listboxEls[0]
+    }
+    if (!listbox && ariaLabelledBy) {
+      // Find listbox with the same aria-labelledby
+      const listboxEls = await this.browser.$$(`[role="listbox"][aria-labelledby="${ariaLabelledBy}"]`)
+      if (listboxEls?.length) listbox = listboxEls[0]
+    }
+    if (!listbox) {
+      // Fallback: find any listbox with the same label
+      const allListboxes = await this.browser.$$(`[role="listbox"]`)
+      for (const lb of allListboxes) {
+        const lbLabelledBy = await this.browser.getElementAttribute(getElementId(lb), 'aria-labelledby').catch(() => '')
+        if (lbLabelledBy === ariaLabelledBy) {
+          listbox = lb
+          break
+        }
+      }
+    }
+
+    if (listbox) {
+      const listboxElementId = getElementId(listbox)
+      for (const opt of options) {
+        const optEls = await this.browser.findElementsFromElement(listboxElementId, 'xpath', `.//*[@role="option"]`)
+        if (optEls?.length) {
+          for (const optEl of optEls) {
+            const optElId = getElementId(optEl)
+            const text = await this.browser.getElementText(optElId).catch(() => '')
+            if (text && text.includes(opt)) {
+              this.debugSection('SelectOption', `Clicking: "${opt}"`)
+              highlightActiveElement.call(this, optEl)
+              await this.browser.elementClick(optElId)
+              break
+            }
+          }
+        }
+      }
+    }
+    return
+  }
+
+  if (role === 'listbox') {
+    for (const opt of options) {
+      const optEls = await this.browser.findElementsFromElement(elementId, 'xpath', `.//*[@role="option"]`)
+      if (optEls?.length) {
+        for (const optEl of optEls) {
+          const optElId = getElementId(optEl)
+          const text = await this.browser.getElementText(optElId).catch(() => '')
+          if (text && text.includes(opt)) {
+            this.debugSection('SelectOption', `Clicking: "${opt}"`)
+            highlightActiveElement.call(this, optEl)
+            await this.browser.elementClick(optElId)
+            break
+          }
+        }
+      }
+    }
+    return
+  }
+
+  // Native <select> element
+  highlightActiveElement.call(this, elem)
+
+  if (!Array.isArray(option)) {
+    option = [option]
+  }
+
+  const clickOptionFn = async el => {
+    if (el[0]) el = el[0]
+    const elId = getElementId(el)
+    if (elId) return this.browser.elementClick(elId)
+  }
+
+  // select options by visible text
+  let els = await forEachAsync(option, async opt => this.browser.findElementsFromElement(elementId, 'xpath', Locator.select.byVisibleText(xpathLocator.literal(opt))))
+
+  if (Array.isArray(els) && els.length) {
+    return forEachAsync(els, clickOptionFn)
+  }
+  // select options by value
+  els = await forEachAsync(option, async opt => this.browser.findElementsFromElement(elementId, 'xpath', Locator.select.byValue(xpathLocator.literal(opt))))
+  if (els.length === 0) {
+    throw new ElementNotFound(elem, `Option "${option}" in`, 'was not found neither by a visible text nor by a value')
+  }
+  return forEachAsync(els, clickOptionFn)
+}
+
 export { WebDriver as default }