From v6 to v7

This tutorial is for people who are still using v6 of WebdriverIO and want to migrate to v7. As mentioned in our release blog post the changes are mostly under the hood and upgrading should be a straight forward process.


If you are using WebdriverIO v5 or below, please upgrade to v6 first. Please checkout our v6 migration guide.

While we would love to have a fully automated process for this the reality looks different. Everyone has a different setup. Every step should be seen as guidance and less like a step by step instruction. If you have issues with the migration, don't hesitate to contact us.


Similar to other migrations we can use the WebdriverIO codemod. For this tutorial we use a boilerplate project submitted by a community member and fully migrate it from v6 to v7.

To install the codemod, run:

npm install jscodeshift @wdio/codemod


Upgrade WebdriverIO Dependencies#

Given that all WebdriverIO versions are tight to each other it is the best to always upgrade to a specific tag, e.g. latest. To do so we copy all WebdriverIO related dependencies out of our package.json and re-install them via:

npm i --save-dev @wdio/allure-reporter@7 @wdio/cli@7 @wdio/cucumber-framework@7 @wdio/local-runner@7 @wdio/spec-reporter@7 @wdio/sync@7 wdio-chromedriver-service@7 wdio-timeline-reporter@7 webdriverio@7

Usually WebdriverIO dependencies are part of the dev dependencies, depending on your project this can vary though. After this your package.json and package-lock.json should be updated. Note: these are the dependencies used by the example project, yours may differ.


Transform Config File#

A good first step is to start with the config file. In WebdriverIO v7 we don't require to manually register any of the compilers anymore. In fact they need to be removed. This can be done with the codemod full automatically:

npx jscodeshift -t ./node_modules/@wdio/codemod/v7 ./wdio.conf.js

The codemod doesn't yet support TypeScript projects. See @webdriverio/codemod#10. We are working to implement support for it soon. If you are using TypeScript please get involved!


Update Step Definitions#

If you are using Jasmine or Mocha, you are done here. The last step is to update the Cucumber.js imports from cucumber to @cucumber/cucumber. This can also be done via the codemod automatically:

npx jscodeshift -t ./node_modules/@wdio/codemod/v7 ./src/e2e/*

That's it! No more changes necessary 🎉



We hope this tutorial guides you a little bit through the migration process to WebdriverIO v7. The community continues to improve the codemod while testing it with various teams in various organisations. Don't hesitate to raise an issue if you have feedback or start a discussion if you struggle during the migration process.