WebdriverIO review: tutorial, pros and cons

WebdriverIO speaks WebDriver Classic, one HTTP request per command, and WebDriver BiDi, the newer bidirectional protocol that browser vendors are standardising over a WebSocket. Since v9 it tries to open a BiDi session by default; the wdio:enforceWebDriverClassic capability opts out. BiDi is what enables network mocking, browsing contexts as values and fast accessibility-tree lookups, so the same suite can have more features against local Chrome or Firefox than against a remote grid that lacks BiDi. Direct Chrome DevTools Protocol control remains available as an escape hatch: getPuppeteer returns a Puppeteer instance for Chromium, though not for component tests or cloud sessions.

The wdio testrunner reads wdio.conf, combines the spec list with the capabilities list, and runs each spec file for each capability in its own worker process with its own browser session, up to the maxInstances limit (10 in the generated config). Ten specs across three browsers can mean thirty processes. Parallelism is therefore per file, isolated by process and free. Services hook into the lifecycle to start Appium, a virtual display, a tunnel to a cloud provider or a visual comparison engine, and reporters receive events from every worker. That design is the source of both the ecosystem’s breadth and its configuration weight: most behaviour is a service you add rather than a default you accept.

The $ and $$ commands return lazy, chainable elements: nothing is looked up until a command on them is awaited, so a chain of $ calls ending in a click needs a single await. Before actions such as click and setValue, WebdriverIO waits for the element to be displayed and interactable, up to waitforTimeout (5,000 ms by default, 10,000 in the generated config). Matchers such as toBeDisplayed and toHaveText retry until they pass or time out. Two things do not wait: reading a value with isDisplayed or getText returns immediately, so a plain equality check on it is a snapshot, and the WebDriver implicit timeout is 0, so lookups outside these mechanisms fail fast.

Version 10 changes two long-standing habits. $ is now strict: if a selector matches more than one element it throws StrictSelectorError instead of taking the first, as Playwright locators do; strictSelectors: false in the config or { strict: false } on one query opts out. And in BiDi sessions, tabs, windows and frames are values you hold: browser.url returns the page it opened, browser.newWindow returns the new tab without switching to it, and a context’s frame method returns a frame. switchWindow and switchFrame throw in BiDi sessions. Code written for v9 that relied on ambiguous selectors or on switching will fail loudly, which is the intent.

For native mobile, WebdriverIO is the client and Appium 3 is the server. The appium service starts Appium in a child process before the run and stops it afterwards, skipping the local launch when cloud capabilities are detected. Capabilities name the platform, the Appium driver and the app, and the same runner, reporters, page object pattern and assertions apply. That shared tooling is the main argument for WebdriverIO over running Playwright for web and a separate Appium client for mobile. Version 10 refuses Appium 1 and 2, and Appium-specific capabilities such as deviceName must carry the appium: prefix.

The wizard’s layout is a good default: specs in test/specs, page objects in test/pageobjects, and named suites in wdio.conf.ts so CI can run a subset with --suite. WebdriverIO’s own page object pattern uses getters that return $ elements, which works well because elements are lazy and looked up fresh on every use, so stale references are rare. Under v10’s strict mode each getter must identify exactly one element, which is a useful discipline. Prefer the role selector, which matches the accessible role and name, or a data-testid attribute; the docs rank both well above class or tag selectors. Note that password inputs have no ARIA role, so they need a test id or label.

browser.mock intercepts requests matching a URL pattern, optionally filtered by method or headers, and respond replaces the body and status. A pattern without a protocol matches the path on any origin, and a single * matches any characters. Each mock is also a spy, so expect(mock).toBeRequested checks that the application made the call. Mocking requires a WebDriver BiDi session, which you get locally with Chrome, Edge or Firefox and on Selenium Grid 4 or later; check before relying on it with a cloud provider. Keep some journeys unmocked so the stubs cannot drift from the real contract unnoticed.

A WebdriverIO pipeline is ordinary Node.js: check out, install, run. Sharding needs no service: a matrix of jobs each passes its own --shard value, and every job runs its share of spec files. On Linux runners v10 starts a virtual display automatically when none exists, using Weston or Xvfb; for browser-only suites, run Chrome headless and set displayServerEnabled: false to skip that overhead. Set outputDir or a JUnit reporter output directory so logs and results land in a folder you can upload when a job fails, and use specFileRetries sparingly, since a retried file can hide a real intermittent bug.

Keep mobile in its own config file that extends the web one, so the shared settings, reporters and hooks stay in one place. Install the service with Appium 3 (npm install @wdio/appium-service appium@^3 --save-dev), install the platform driver once with npx appium driver install uiautomator2 for Android or xcuitest for iOS, and let the service start Appium on port 4723. Use accessibility ids for selectors in native contexts, since the role selector is not available there. Expect the first week to go on device setup rather than tests: emulators, SDK paths and signing are the slow part, and npx wdio session doctor android reports missing prerequisites in v10.

For local debugging, await browser.debug() pauses the test and opens a REPL against the live browser; raise the framework timeout first or the test runner will fail the paused test. For CI, add the devtools service in trace mode with traceGranularity set to test and tracePolicy set to retain-on-failure, upload the test-results folder, and open failures with npx show-trace. For an existing v9 suite, upgrade on a branch: move to Node.js 22.19 or later and Appium 3, run the suite once with strictSelectors left on to list every ambiguous selector, then fix them rather than switching strict mode off. The migration guide lists renamed keys such as wdio:specs and cucumberOpts.tags, several of which now throw.