{"id":12659,"library":"webdriverio","title":"WebdriverIO","description":"WebdriverIO is a next-generation Node.js-based test automation framework for web browsers and mobile applications. It provides a comprehensive API built on top of the WebDriver and Appium protocols, allowing for robust end-to-end testing. The current stable version is 9.27.0, with releases occurring frequently, often multiple times a month, indicating active development and quick bug fixes. Key differentiators include its flexibility to run tests locally with WebDriver or remotely with cloud providers like Sauce Labs, built-in support for Puppeteer for browser automation, and its modular architecture allowing integration with various services and reporters. It offers a standalone API for custom scripts and a powerful test runner via `@wdio/cli` for structured test suites, supporting popular frameworks like Mocha, Jasmine, and Cucumber.","status":"active","version":"9.27.0","language":"javascript","source_language":"en","source_url":"https://github.com/webdriverio/webdriverio","tags":["javascript","webdriverio","webdriver","selenium","appium","saucelabs","sauce","labs","mocha","typescript"],"install":[{"cmd":"npm install webdriverio","lang":"bash","label":"npm"},{"cmd":"yarn add webdriverio","lang":"bash","label":"yarn"},{"cmd":"pnpm add webdriverio","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally by WebdriverIO for browser automation when running locally without a separate WebDriver server, enabling direct control over Chrome, Firefox, or Edge. It's a peer dependency.","package":"puppeteer-core","optional":true}],"imports":[{"note":"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.","wrong":"const { remote } = require('webdriverio')","symbol":"remote","correct":"import { remote } from 'webdriverio'"},{"note":"Imports the TypeScript type definition for the `Browser` object, which is useful for type checking and autocompletion in standalone scripts.","symbol":"Browser","correct":"import type { Browser } from 'webdriverio'"},{"note":"Imports the TypeScript type for elements returned by the `$` and `$$` commands, providing type hints for element interactions and methods.","symbol":"ChainablePromiseElement","correct":"import type { ChainablePromiseElement } from 'webdriverio'"}],"quickstart":{"code":"import { remote } from 'webdriverio'\n\nconst browser = await remote({\n    capabilities: { browserName: 'chrome' }\n})\n\nawait browser.navigateTo('https://www.google.com/ncr')\n\nconst searchInput = await browser.$('#lst-ib')\nawait searchInput.setValue('WebdriverIO')\n\nconst searchBtn = await browser.$('input[value=\"Google Search\"]')\nawait searchBtn.click()\n\nconsole.log(await browser.getTitle()) // outputs \"WebdriverIO - Google Search\"\n\nawait browser.deleteSession()","lang":"javascript","description":"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."},"warnings":[{"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.","message":"Deprecated Appium protocol commands were renamed for Appium 3 compatibility, potentially breaking existing mobile tests.","severity":"breaking","affected_versions":">=9.26.0"},{"fix":"Update all instances of `multiremotebrowser` in your configuration files and test scripts to `multiRemoteBrowser`.","message":"The global `multiremotebrowser` object was renamed to `multiRemoteBrowser` to adhere to camelCase naming conventions.","severity":"breaking","affected_versions":">=9.23.0"},{"fix":"Ensure your project is using TypeScript 7 or a later compatible version to avoid potential type inference or compilation problems.","message":"WebdriverIO introduced fixes for TypeScript 7 compatibility, which might cause issues with older TypeScript versions.","severity":"gotcha","affected_versions":">=9.27.0"},{"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.","message":"A bug fix restored `jiti` fallback for CommonJS (CJS) named imports, implying that CJS users might have experienced import issues around this version.","severity":"gotcha","affected_versions":">=9.23.3"},{"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.","message":"Mobile command argument mismatches were fixed for Appium 3 compatibility, which could affect how arguments are passed to certain mobile automation commands.","severity":"gotcha","affected_versions":">=9.26.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Your Node.js environment is running an older version that does not meet WebdriverIO's minimum requirements.","error":"Error: WebdriverIO requires Node.js >=18.20.0."},{"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`.","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.","error":"TypeError: remote is not a function or is undefined"},{"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.","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.","error":"Error: Element with selector \"#lst-ib\" not found."},{"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.","cause":"This error typically occurs when attempting to use the `browser` object in a standalone WebdriverIO script without first initializing it via `remote()`.","error":"ReferenceError: browser is not defined"}],"ecosystem":"npm"}