# WebdriverIO v10 documentation: Upgrade > 1 pages. Index of all sections: https://webdriver.io/llms.txt --- Source: https://webdriver.io/docs/v10-migration.md # From v9 to v10 This guide collects the breaking changes of WebdriverIO `v10` and what you have to do about them. Unlike previous majors, most of these changes cannot be applied by the WebdriverIO [codemod](https://github.com/webdriverio/codemod), because they depend on what your tests actually mean. The [legacy command signatures](#legacy-command-signatures) below are mechanical replacements. Each other section describes how to find the affected places in your suite. ## Migrate with a coding agent[​](#migrate-with-a-coding-agent "Direct link to Migrate with a coding agent") Give your agent the v10 migration skill and ask it to migrate the suite to WebdriverIO v10, following this page. The skill is the procedure: what to search for, which codemod to run, and when to stop. This page is the source of truth for each break. Install it from the project you are upgrading. The [skills CLI](https://skills.sh) reads [`.agents/skills/wdio-v10-migration/SKILL.md`](https://github.com/webdriverio/webdriverio/blob/main/.agents/skills/wdio-v10-migration/SKILL.md) from this repository and writes it into the skill directory of the agents you pick: ``` npx skills add webdriverio/webdriverio --skill wdio-v10-migration ``` `--skill wdio-v10-migration` installs this skill. Skills for working on the WebdriverIO repository are marked internal and are not offered. The CLI asks which agents to install for and writes the skill into each agent's project directory. You can also attach that file to the chat. Strict selectors and bare capability `specs` / `exclude` lists only show up when the suite runs. The skill cannot decide those from the source alone. ## Node.js[​](#nodejs "Direct link to Node.js") WebdriverIO v10 requires Node.js 22.23.4, 24.22.1 or 26.12.1, or a later release of these lines. These are the first releases with the [updated CA store](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases) for the eMudhra intermediate CA compromise. Node.js 18 and 20 are no longer supported, and Node.js 23 and 25 are not supported. CI covers Node.js 22, 24, and 26. ## Component tests[​](#component-tests "Direct link to Component tests") The browser runner still runs in Chrome 90, Edge 90, Firefox 90 and Safari 14.1 or newer. See [Browser support](/docs/component-testing.md#browser-support). Code passed to `browser.execute` stays at ES2021, so it can run in older browsers under test. That floor did not change. ## Mocha[​](#mocha "Direct link to Mocha") `@wdio/mocha-framework` and `@wdio/browser-runner` depend on [Mocha 12](https://mochajs.org/blog/mocha-12-stable/). Mocha 12 needs Node.js `^20.19.0 || >=22.12.0`, which is covered by the v10 floor of Node.js 22.23.4. ``` - mochaOpts: { compilers: ['ts:ts-node/register'] } + mochaOpts: { require: ['ts-node/register'] } ``` `mochaOpts.compilers` is gone. Mocha removed the long-deprecated `--compilers` flag, so leftover compiler mappings are ignored. Load transpilers or other setup files with `mochaOpts.require`. WebdriverIO follows the Mocha timeout: `this.timeout()` in a test or hook, and `mochaOpts.timeout: 0`, which turns the timeout off. In v9, WebdriverIO ignored `this.timeout()` in a test, and from 9.22 `mochaOpts.timeout: 0` failed every test ("Timeout after -3ms"). The `retry` argument of WebdriverIO does not run a test again after a timeout. See [Mocha timeouts and the WebdriverIO hooks](/docs/timeouts.md#mocha-timeouts-and-the-webdriverio-hooks), also for `mochaOpts.parallelMode`. New in v10: [parallel tests in a spec file](/docs/parallel-tests.md) with `mochaOpts.parallelMode` or `cucumberOpts.parallelMode`. `failHookAffectedTests` defaults to `true`. A failing `before` or `beforeEach` hook fails the tests that hook skipped. Set `mochaOpts.failHookAffectedTests` to `false` to report only the hook. A hook title has the description or the name of the hook function, as in Mocha: `"before each" hook: login for "my test"` for `beforeEach('login', fn)` or `beforeEach(function login () {})`, or no name for an anonymous hook: `"before each" hook for "my test"`. In v9 it had `wrappedHook`, the name of the WebdriverIO wrapper. You see this title in the error of a test that a failed hook skipped, and in the names of root-level hooks, for example in Allure. Use `expect-webdriverio` 8, see [expect-webdriverio 8](#expect-webdriverio-8). Mocha can load that package twice in one process; it shares assertion state across those copies ([expect-webdriverio#2221](https://github.com/webdriverio/expect-webdriverio/pull/2221)). Mocha 12 changes that can leak through `mochaOpts`: * `grep` accepts modern RegExp flags. * `ui` is still `bdd`, `tdd`, `qunit`, or `exports`. Custom interfaces should keep the `*-bdd`, `*-tdd`, or `*-qunit` suffix. * `parallel` is still unsupported. WDIO owns spec parallelism; Mocha's worker pool will error if you enable it. Mocha 12 is ESM-first (`"type": "module"`). Programmatic `require('mocha')` still works on Node 22 via `require(esm)`. The WDIO Mocha CLI (`wdio run … --mochaOpts.*`) is unchanged; Mocha's own CLI now uses `util.parseArgs` instead of yargs. ## Cucumber[​](#cucumber "Direct link to Cucumber") `@wdio/cucumber-framework` depends on [`@cucumber/cucumber` 13](https://github.com/cucumber/cucumber-js/blob/main/UPGRADING.md#1300). Cucumber 13 requires Node.js 22, 24, or 26 or later. It does not run on Node.js 20, 23, or 25. The framework package declares the v10 range, which also excludes Node.js 23 and 25. ``` - cucumberOpts: { tagExpression: '@smoke' } + cucumberOpts: { tags: '@smoke' } ``` `tagExpression` is not aliased. Setting it throws, so a leftover filter cannot silently run every scenario. Cucumber 13 no longer exports `Cli`. Programmatic runs go through `runCucumber` from `@cucumber/cucumber/api`, which is what the adapter already uses. Other Cucumber 13 breaks (ambiguous formatter paths, parallel workers, `BeforeAll` / `AfterAll`) are described in [Cucumber's upgrade guide](https://github.com/cucumber/cucumber-js/blob/main/UPGRADING.md#1300). ### `strict` and profiles[​](#strict-and-profiles "Direct link to strict-and-profiles") `cucumberOpts.strict` defaults to `true`, as in Cucumber: a pending step fails the run, and the reporters still show the step as pending. Set `strict: false` to keep the v9 behavior. Values in a Cucumber profile or configuration file are used: the file in `cucumberOpts.file`, or, without it, Cucumber's default file in the working folder (`cucumber.js`, `.cjs`, `.mjs`, `.json`, `.yaml` or `.yml`). A value in `cucumberOpts` wins over the profile; before, the WebdriverIO defaults (for example `retry: 0`) also won, so a profile could only set a few options. The `require` and `import` lists of the profile are loaded too, together with the ones in `cucumberOpts`. The `paths`, `requireModule` and `loader` of the profile are not used, and the worker logs a warning: use `specs` and `cucumberOpts.requireModule` (WebdriverIO has its own TypeScript loader). A folder in the `require` or `import` of the profile is not loaded either, with a warning: use a glob such as `features/support/**/*.js`. Remove a Cucumber configuration file that you do not use, or set `cucumberOpts.file: false`. ### `BeforeAll` and `AfterAll` hooks[​](#beforeall-and-afterall-hooks "Direct link to beforeall-and-afterall-hooks") A Cucumber `BeforeAll` / `AfterAll` is now reported as a hook of the feature, passed or failed (before, a failed one was in no report). The browser commands and console logs of its body belong to the hook: those of an `AfterAll` were on the last step of the last scenario before. Allure shows each one as a fixture of the feature (set `disableMochaHooks: true` to hide the passed ones), and `@wdio/json-reporter` lists it in the `hooks` of the feature. WebdriverIO's own `beforeFeature` / `afterFeature` hooks are not reported. ### Feature uid[​](#feature-uid "Direct link to Feature uid") The uid of a Cucumber feature is the path of the feature file from `rootDir`, not the file name: `features/admin/login.feature:1:1` instead of `login.feature:1:1`. Two feature files with the same name in other folders no longer share a uid. The `parent` and `fullTitle` of a scenario use this uid. `%`, `:` and `#` in the path are encoded as `%25`, `%3A` and `%23`, so `uid.split(':')[1]` is still the line and a `#` only starts a part number. In grouped specs with a random order, a feature that starts again has the suite uid `#2`. With `scenarioLevelReporter: true`, the Allure `historyId` comes from `fullTitle`, so the Allure history of each scenario starts again with this change. It also starts again when `rootDir` or the path of the feature file changes. To keep one history for config files in different folders, set the same `rootDir` in each of them. ## Jasmine[​](#jasmine "Direct link to Jasmine") `@wdio/jasmine-framework` depends on [Jasmine 6](https://jasmine.github.io/upgrade-guides/6.0). Jasmine 6 is tested on Node.js 20, 22, and 24. The v10 floor of Node.js 22.23.4 already covers that range. `jasmineNodeOpts` was removed. Configure Jasmine with `jasmineOpts`. Setting `jasmineNodeOpts` throws: ``` The option "jasmineNodeOpts" was removed in WebdriverIO v10. Use "jasmineOpts" instead. ``` ``` - jasmineNodeOpts: { defaultTimeoutInterval: 60000 } + jasmineOpts: { defaultTimeoutInterval: 60000 } ``` `jasmineOpts.failFast` is no longer read. Use `jasmineOpts.stopOnSpecFailure`. A leftover `failFast` does not stop the suite. Cucumber's `failFast` is a different option and still works. ``` - jasmineOpts: { failFast: true } + jasmineOpts: { stopOnSpecFailure: true } ``` `jasmineOpts.stopSpecOnExpectationFailure` was removed. Use `jasmineOpts.oneFailurePerSpec`. Setting the old key throws: ``` The option "jasmineOpts.stopSpecOnExpectationFailure" was removed in WebdriverIO v10. Use "jasmineOpts.oneFailurePerSpec" instead. ``` ``` - jasmineOpts: { stopSpecOnExpectationFailure: true } + jasmineOpts: { oneFailurePerSpec: true } ``` Jasmine's sync matchers are synchronous again. In v9, the global `expect` was Jasmine's `expectAsync`, so `expect(1).toBe(1)` returned a promise. In v10, Jasmine's built-in matchers and the matchers you add with `jasmine.addMatchers` return `undefined`. WebdriverIO matchers, Jasmine's async matchers and `jasmine.addAsyncMatchers` matchers still return a promise, so continue to `await` them. You do not need to change `await expect($('#logo')).toBeDisplayed()` to `expectAsync()`: the global `expect` sends WebdriverIO matchers to `expectAsync` for you. `await expect(1).toBe(1)` continues to work. A failed sync assertion without `await` now fails the spec. In v9, it was a rejected promise: if nothing awaited it, the spec could pass, with only an unhandled rejection in the log. After the upgrade, look at the specs that start to fail. They had a hidden failure in v9, and the fix is in the test or in the application, not in the `expect` call: ``` it('saves the form', async () => { const onSave = jasmine.createSpy('onSave') await submitForm(onSave) // v9: passed even when `onSave` was not called // v10: fails when `onSave` was not called expect(onSave).toHaveBeenCalled() }) ``` The result of a sync matcher is now `undefined`, so `.then()` or `.catch()` on it throws a `TypeError`: ``` - expect(total).toBe(3).then(() => log('ok')) + expect(total).toBe(3) + log('ok') ``` Other effects of this change: * `oneFailurePerSpec` now stops the spec at its first failed assertion: at once for a sync matcher, and when the promise settles for an awaited async matcher. * Jasmine's spy matchers work without `await`. In v9, `toHaveBeenCalled`, `toHaveSpyInteractions` and `toHaveNoOtherSpyInteractions` failed with "Does not take arguments", and an uncalled spy passed without `await`. * `jasmine.addMatchers` is no longer replaced, so Jasmine does not show its "Monkey patching detected" warning anymore. `toHaveSize` has two meanings. On a WebdriverIO value, it is the WebdriverIO matcher and checks the size of the element: an element, an element array (including the result of `$$().filter()`), an `Element[]`, a multi-remote element, a browser, a browsing context, a mock, the `some()` wrapper, or a promise such as a chainable `$()`. On any other value, it is Jasmine's matcher and checks the length. In v9, Jasmine's matcher always ran. ``` expect([1, 2]).toHaveSize(2) // Jasmine, sync await expect($('#logo')).toHaveSize({ width: 32, height: 32 }) // WebdriverIO, async ``` The types follow the same rules. `@wdio/jasmine-framework` now types the global `expect` with Jasmine's matchers, plus the WebdriverIO matchers and the Jasmine async matchers, which return a promise. Remove `expect-webdriverio/jasmine-wdio-expect-async` from `types` in your `tsconfig.json`, because it types every matcher as async. Add `jasmine` if it is not there: tsconfig.json ``` { "compilerOptions": { - "types": ["node", "@wdio/globals/types", "expect-webdriverio/jasmine-wdio-expect-async", "@wdio/jasmine-framework"] + "types": ["node", "jasmine", "@wdio/globals/types", "@wdio/jasmine-framework"] } } ``` `expect.oneOf()` and `expect.multiRemote()` now also work in Jasmine specs. Before, they were not on the Jasmine `expect` at runtime. ## expect-webdriverio 8[​](#expect-webdriverio-8 "Direct link to expect-webdriverio 8") `@wdio/globals`, `@wdio/runner` and `@wdio/browser-runner` require `expect-webdriverio` 8 as a peer dependency. In v9, it was `expect-webdriverio` 5, 6 or 7. If your `package.json` lists `expect-webdriverio`, update it to version 8 in the same change as the `@wdio/*` packages. `expect-webdriverio` 8 has its own breaking changes. Its [v7 to v8 migration guide](https://github.com/webdriverio/expect-webdriverio/blob/main/docs/Migrations.md#migration-guide-v7-to-v8) lists each change and its replacement. From `expect-webdriverio` 5 or 6, also read its [v5 to v6 migration guide](https://github.com/webdriverio/expect-webdriverio/blob/main/docs/Migrations.md#migration-guide-v5-to-v6): version 8 removes the APIs that 5.6.9 to 6.0.0 deprecated. Version 7 has no migration guide. It adds multi-remote support, and `toMatchSnapshot()` and `toMatchInlineSnapshot()` on `$$()` now store the `outerHTML` of each element: update those snapshots. These changes are the most likely to affect a test suite: * `toHaveText` on `$$()` compares the elements index by index. An expected array in another order than the page fails. Use the page order, `expect.oneOf()` or `expect.arrayContaining()`. * An array of expected values on a single element fails `toHaveText`, `toHaveHTML`, `toHaveComputedLabel`, `toHaveComputedRole` and `toHaveElementClass`. Use `expect.oneOf()`. For `toHaveElementClass`, an array meant "has any of these classes": use `expect.oneOf()`, or one assertion for each class when the element must have all of them. * A list matcher (`expect.arrayContaining()`, `expect.arrayOf()`) on a single element, or with `some()`, throws an error. On `$$()`, it compares the values of all the elements at once. * A missing attribute or property never matches, also not a matcher that accepts no value, such as `expect.not.stringContaining()`. * `URL`, `Set`, `Map` and binary values are compared by their content. An assertion that passed by mistake can now fail. * The helper types are not global anymore. A file that uses `Test`, `TestResult`, `Scenario` or `WdioCustomMatchers` without an import fails with `Cannot find name`: use `Frameworks.Test`, `Frameworks.TestResult` and `Frameworks.Scenario` from `@wdio/types`, and `ExpectWebdriverIO.Matchers`. * `setFeatureFlags()` and the `featureFlags` option were removed. * These deprecated APIs were removed: `setOptions` (use `setDefaultOptions`), `getConfig` (use `getDefaultOptions`), `matchers` (use `wdioCustomMatchers`), `toHaveAttr` (use `toHaveAttribute`), `toHaveClass` (use `toHaveElementClass`), `toBeRequestedWithResponse()` (use `toBeRequestedWith({ response })`), and `expect-webdriverio/types` (use `expect-webdriverio/expect-global`). * The `beforeAssertion` and `afterAssertion` hooks get the name of the alias that the test called, for `toBeExisting`, `toBePresent`, `toHaveLink`, `toHaveValue` and `toBeRequested`. In v9, they got the name of the matcher behind the alias, for example `toExist` for `toBeExisting`. * On a multi-remote browser, give the result of `$$()` to `expect`. A plain array such as `[...elements]` or `Array.from(elements)` is not recognized as elements, and the assertion fails. On a multi-remote browser, one assertion checks every instance, and `expect.multiRemote()` gives one expected value per instance. See [Multiremote assertions](/docs/multiremote.md#assertions). ## Driver packages[​](#driver-packages "Direct link to Driver packages") WebdriverIO v10 starts Firefox, Edge and Safari with `geckodriver` 8, `edgedriver` 8 and `safaridriver` 3. In v9, it used `geckodriver` and `edgedriver` 6 or 7, and `safaridriver` 1 or 2. WebdriverIO installs them, so you do not list them yourself. If your `package.json` lists one of them, update it in the same change as the `@wdio/*` packages. `geckodriver` and `edgedriver` take `@wdio/logger` as a peer dependency, so they log through the logger of your WebdriverIO install. In v9, `geckodriver` and `edgedriver` brought their own copy of `@wdio/logger`, and that second copy emptied the log file in `outputDir`. Run `npm ls @wdio/logger`: every copy should be version 10. A plugin or service that still depends on version 9 has the same effect. The [driver upgrade notes](https://github.com/webdriverio/driver#upgrading-to-geckodriver-8-edgedriver-8-and-safaridriver-3) list every change. These changes can affect a WebdriverIO project: * The driver downloads use `HTTPS_PROXY` and `HTTP_PROXY`. In v9, the `geckodriver` and `edgedriver` downloads ignored them. If a proxy is set in your environment but the driver CDN must be reached directly, add its host to `NO_PROXY`. * `geckodriver` no longer reads `GECKODRIVER_FILEPATH`. Use `GECKODRIVER_PATH`. * `wdio:edgedriverOptions` and `wdio:safaridriverOptions` accept `spawnOpts`, as `wdio:chromedriverOptions` does. ## Browser downloads[​](#browser-downloads "Direct link to Browser downloads") In v9, WebdriverIO extracted the Chrome, Chromium and Chromedriver zip files itself. In v10 it uses the system `unzip` command on Linux and macOS (`tar.exe` or PowerShell on Windows). Slim Docker images, such as `node:24-slim`, do not have it: install it, see [Docker](/docs/docker.md#images-where-webdriverio-downloads-the-browser). In v9, the Chrome, Chromium, Firefox and Chromedriver downloads used `HTTPS_PROXY` and `HTTP_PROXY`. In v10 they use them only when `proxy-agent` is installed in your project, or when Node.js runs with `NODE_USE_ENV_PROXY=1`. WebdriverIO logs a warning when a proxy variable is set but the download would ignore it. See [Proxy For Browser And Driver Downloads](/docs/proxy.md#proxy-for-browser-and-driver-downloads). ## Chrome profile on Windows[​](#chrome-profile-on-windows "Direct link to Chrome profile on Windows") In v9, a testrunner worker on Windows gave Chrome the profile folder `wdio-chrome--