WebdriverIO

Common errors

• Error: WebdriverIO requires Node.js >=18.20.0.

  cause Your Node.js environment is running an older version that does not meet WebdriverIO's minimum requirements.
  fix Upgrade your Node.js installation to version 18.20.0 or higher. Use a Node Version Manager (like `nvm`) to easily switch and manage Node.js versions.

• TypeError: remote is not a function or is undefined

  cause Attempting to use `remote` in a CommonJS module without proper destructuring, or trying to access the global `browser` object in a standalone script without initializing it.
  fix For standalone scripts, ensure you use `import { remote } from 'webdriverio'` at the top. If working within the `@wdio/cli` test runner, the `browser` object is automatically globally available and does not need explicit import or initialization via `remote`.

• Error: Element with selector "#lst-ib" not found.

  cause The specified CSS or XPath selector did not match any element on the page, or the element was not yet present/visible when the command was executed.
  fix Verify the selector is correct and unique for the desired element. Use explicit waits (e.g., `browser.waitUntil` or `element.waitForExist`) to ensure the element is available and interactable before attempting to use it.

• ReferenceError: browser is not defined

  cause This error typically occurs when attempting to use the `browser` object in a standalone WebdriverIO script without first initializing it via `remote()`.
  fix In standalone scripts (not run by `@wdio/cli`), you must explicitly create the browser instance: `const browser = await remote({ capabilities: { browserName: 'chrome' } })`. The global `browser` object is only injected by the WebdriverIO test runner.

Warnings

• breaking Deprecated Appium protocol commands were renamed for Appium 3 compatibility, potentially breaking existing mobile tests.
  Fix: Review the WebdriverIO v9 changelog and Appium 3 migration guide. Update any deprecated Appium protocol command names in your test suite to their new equivalents.
• breaking The global `multiremotebrowser` object was renamed to `multiRemoteBrowser` to adhere to camelCase naming conventions.
  Fix: Update all instances of `multiremotebrowser` in your configuration files and test scripts to `multiRemoteBrowser`.
• gotcha WebdriverIO introduced fixes for TypeScript 7 compatibility, which might cause issues with older TypeScript versions.
  Fix: Ensure your project is using TypeScript 7 or a later compatible version to avoid potential type inference or compilation problems.
• gotcha A bug fix restored `jiti` fallback for CommonJS (CJS) named imports, implying that CJS users might have experienced import issues around this version.
  Fix: If encountering issues with named imports in CommonJS files, particularly after previous updates, verify your CJS import patterns or consider migrating to ESM for improved compatibility.
• gotcha Mobile command argument mismatches were fixed for Appium 3 compatibility, which could affect how arguments are passed to certain mobile automation commands.
  Fix: If using Appium 3, review your mobile command arguments, especially for actions like 'touch' or 'swipe', as their signatures might have changed. Consult the Appium 3 and WebdriverIO v9 documentation for updated argument structures.

Install

• npm install webdriverio npm
• yarn add webdriverio yarn
• pnpm add webdriverio pnpm

Imports

• remote
  wrong:

  const { remote } = require('webdriverio')

  correct:

  import { remote } from 'webdriverio'

  Use `remote` for initializing standalone WebDriver/Appium sessions. For test runner usage with `@wdio/cli`, the `browser` object is globally available and does not need explicit import.
• Browser

  import type { Browser } from 'webdriverio'

  Imports the TypeScript type definition for the `Browser` object, which is useful for type checking and autocompletion in standalone scripts.
• ChainablePromiseElement

  import type { ChainablePromiseElement } from 'webdriverio'

  Imports the TypeScript type for elements returned by the `$` and `$$` commands, providing type hints for element interactions and methods.

Quickstart

Demonstrates how to initialize a standalone WebdriverIO browser instance, navigate to a page, interact with elements, and retrieve the page title using Puppeteer capabilities for Chrome.

import { remote } from 'webdriverio'

const browser = await remote({
    capabilities: { browserName: 'chrome' }
})

await browser.navigateTo('https://www.google.com/ncr')

const searchInput = await browser.$('#lst-ib')
await searchInput.setValue('WebdriverIO')

const searchBtn = await browser.$('input[value="Google Search"]')
await searchBtn.click()

console.log(await browser.getTitle()) // outputs "WebdriverIO - Google Search"

await browser.deleteSession()