Should I upgrade to WebdriverIO v9 now?

Plan whether to upgrade or freeze WebdriverIO after v9 changed runtime requirements and test API behavior in ways that can break CI pipelines.

Freeze on WebdriverIO v8 for now, unless you can raise the Node floor and absorb v9 API refactors in the same migration window.

Blockers

Who this is for

Candidates

Upgrade to WebdriverIO v9 and raise the Node floor first

As of 2026-03-27, WebdriverIO v9 is the stable release on the official versions page. The v9 release notes state that v9 no longer supports Node.js v16 and below, and the project recommends Node.js v20. The same release introduced blocker-level API and behavior changes: element metadata access now goes through `getElement` or `getElements`, `XXXContaining` matchers were removed in favor of asymmetric matchers, `isDisplayedViewport` was removed in favor of `isDisplayed({ withinViewport: true })`, and the old JSON Wire Protocol commands and `devtools` packages were removed or replaced. It also switched TypeScript runtime compilation from `ts-node` to `tsx`, which can affect test bootstrapping in CI.

When to choose

Use this when you can upgrade CI images and local dev to a supported Node release before touching test code. The decisive factor is whether you can absorb both the runtime floor change and the test-suite refactors in one migration window.

Tradeoffs

You move back onto the current stable line and avoid staying on an unsupported major, but the upgrade is not just a package bump because it can break helpers, custom matchers, and legacy browser-driver integrations.

Cautions

Expect silent behavior changes as well as compile-time breaks. v9 now automatically suppresses dialogs unless you register a listener, and it automatically waits for elements to become interactable on direct actions like `click` and `setValue`, so timing-sensitive tests can behave differently even after they compile.

Sources

Freeze on WebdriverIO v8 temporarily and isolate the upgrade work

WebdriverIO v8 is listed on the official versions page as LTS only until August 2025. As of 2026-03-27, this has already occurred, so freezing on v8 means intentionally staying on an older major that is no longer in its stated LTS window. This can still be the lower-risk short-term choice if your CI or self-hosted runners are pinned to Node 16 or if your suite depends on removed v9 APIs such as direct element metadata access, `XXXContaining` matchers, `isDisplayedViewport`, JSON Wire Protocol commands, or `@wdio/devtools-service`. The differentiator is operational stability today versus taking on an unsupported dependency posture.

When to choose

Use this when CI continuity matters more than framework currency and you cannot yet lift Node or refactor the suite safely. The decisive factor is whether the immediate outage risk from a forced v9 migration is higher than the governance risk of running past v8's published support window.

Tradeoffs

You avoid near-term pipeline breakage and can stage the migration behind a dedicated branch or runner-image project, but you remain on an older major whose official LTS window has already ended.

Cautions

Do not treat a freeze as a steady-state plan. Because the official versions page shows v8 LTS ended in August 2025, the safer interpretation as of 2026-03-27 is 'short-term containment only' while you schedule a Node upgrade and a codemod-style pass over WDIO-specific APIs.

Sources

Facts updated: 2026-03-27
Published: 2026-04-03

Related questions

Try with your AI agent

$ npm install -g pocketlantern
$ pocketlantern init
# Restart Claude Code, Cursor, or your MCP client, then ask:
# "Should I upgrade to WebdriverIO v9 now?"
Missing something? Request coverage