Skip to main content

WebdriverIO v5 Released

· 11 min read
Christian Bromann

We are pleased to announce that a new major version of WebdriverIO has finally been released! I never thought that it would take this long (it's been over a year), but we can finally say that the new version of WebdriverIO is ready for use (and better than ever). There has been over 800 commits, from over 34 different contributors; and I am truly grateful to everyone who participated in this collective effort. With that being said...

🎉 🎉 🎉 Time to celebrate! 🎉 🎉 🎉
​


When I began to practically rewrite this project from scratch one year ago, I knew there would be problems here and there. However, I was confident that the WebdriverIO community in the support channels would work collectively to help each other out; and I'm proud to say, I was right!

The Goal​

Looking into the history of the project, it is humbling to see how much it has been grown within just a few years. From a handful of downloads a day, to now almost 50k; as well as the knowledge that big companies are relying on this tool to ship their software on daily basis, it became obvious that the next big feature had to be sustainability. The first step was made by joining the JS.Foundation at of 2017.



The next step was to implement a technical infrastructure that would allow the project to grow. By reviewing other successful open source projects such as e.g. Jest or Babel, we adapted a monolithic project structure to simplify the process of contributing to WebdriverIO.


We wanted to start this effort completely community driven, and began to gather feedback from everyone who was using WebdriverIO on daily basis. We created a Discord Server in order to discuss architectural changes, and to organize the work of porting the packages into the new tech stack that was Lerna.

New Package Structure​

As we moved to a monolithic system we scoped all WebdriverIO packages into the @wdio NPM organization. This would make it simpler to onboard contributors to release new package versions, and better clarifies which packages are "officially" maintained by the organization or are 3rd party community packages.


If you have been using wdio-mocha-framework or wdio-spec-reporter in your project please update the packages to use the ones built for v5: @wdio/mocha-framework or @wdio/spec-reporter. Going forward the version number of all packages are now pinned to each other; meaning that you should always have the same versions for all "official" WebdriverIO packages that you use.

We Did Some Spring Cleaning​

When people proposed new commands to the API, we contributors became more and more hesitant to introduce them. There were a vast number of existing commands; and many of these requested commands provided very little difference from existing commands. This was beginning to become a maintenance nightmare.


Starting with v5 we created a "base" WebdriverIO package called webdriver. It contains the bare logic to make a HTTP request to a WebDriver endpoint; and includes all of the commands from various specifications (including the WebDriver spec as well as Appium's Mobile JSONWire protocol) defined in a simple to maintain JSON object.


As part of that effort we've renamed many of the commands in order to align them closer to the pattern that has been used in the protocol. The base WebDriver client now also returns the value property of all protocol command responses, so that we were able to get rid of a lot of redundancy (e.g. title is now called with getTitle).


Additionally, we have seen significant confusion regarding the WebdriverIO API, and the fact that it sometimes took selectors as a first argument, and sometimes not. This was causing various problems e.g. building a consistent and useful TypeScript definition for it. In the new version we got rid of selectors as command parameters, and enforced the difference between commands only accessible from the browser/client instance, and those from the element instance. In order to click on an element, you must now first fetch it, and then call the click command on that instance, e.g.

browser.click('#elem') // throws 'browser.click is not a function'

const elem = $('#elem')
elem.click() // clicks successfully on the element
// or
$('#elem').click()

elem.url('https://webdriver.io') // throws because the url command is scoped on the browser object

Website Changes​

We already had an automated system that generated the docs for our website. As part of the new architecture and tech stack we however ported this from Hexo to Docusaurus.


We are still in the process of finalizing this effort, as we want to continue providing everyone a way to easily change the version of the docs. We are also looking into providing multiple translations of the docs so that people who don't speak english can better understand and use WebdriverIO. Please reach out to us on Twitter, or directly on the issue thread if you want to help out. This is probably one of the best ways to get involved into an open source project.

How To Upgrade To v5​

There are significantly more things that we have been working on over the last year that you might like to read about. Check out the official changelog to find all of the changes that describe the new version. We will probably continue to update this over time, as we weren't able to keep a list of every detail that changed. We would also like to ask you to have a look into the new guide section and our updated docs in general.


There is unfortunately no easy upgrade tool that you can download and run to update your test suites from v4 to v5 (even though we would love to have such a thing, PRs are welcome 😉). If you run into any issues upgrading to v5 please join our support server on Discord and reach out to us.


Every project is different, so it is impossible to have one single guide for everyone. However, the following step by step description will help you get closer to where you need to be:


  • read the changelog to understand all breaking changes
  • remove all wdio-* packages from your package.json
  • remove your node_modules directory
  • install the latest version of webdriverio: $ npm install webdriverio@latest
  • install the new wdio testrunner: $ npm install @wdio/cli --save-dev
  • if you have a wdio.conf.js in your root directory, create a backup: $ cp wdio.conf.js wdio_backup.conf.js
  • rerun the configuration wizard: $ npx wdio config
  • merge custom modifications of your old wdio_backup.conf.js into your new config file. Don't merge everything at once - just begin with the basic setup using no services and just the e.g. spec reporter to run tests locally and work towards a full migration
  • take the simplest test in your suite and rename the commands according to the changelog
  • have your log directory set in your config (e.g. outputDir: __dirname) to ensure you can see everything that is going on including errors (you can later set it to a proper log directory)
  • attempt to run the the test suite you modified $ npx wdio wdio.conf.js --spec ./path/to/modified/test.js
  • repeat on your remaining test files
  • add reporters and services back into your wdio.conf.js, and see if they work as expected (Note: it is possible that services or reporters that you have used aren't ported to v5 yet, if so, please raise an issue in the repository of that community package or try to port it)


If you have issues porting your test suite, check the issues thread to see if someone has already reported the same problem; and then reach out to us on our Discord server. We may have missed porting / not yet ported a functionality that you have been using in your test. Thanks to the new project structure, we can quickly fix this and provide an update version for you!


We will release further blog articles in our new blog with tutorials on how to upgrade WebdriverIO to v5 soon. You can also checkout the excellent video series from our beloved Will Brock on the new release. An update to the WebdriverIO Learning Course is also already in work.

What Is Next​

We didn't put put all this hard work into the project to end here. Instead, we just get started. We truly believe that WebDriver is and always will be the automation standard of the industry. Therefore we are actively engaged in contributing to the standard to ensure that all commands are compliant to the protocols. We also will take your common problems and general feedback back to the W3C Working Groups in order to ensure that we can address major issues at the core of the technology.



After the release, we will be begin working on a detailed roadmap for the next year that allows you to participate in the progress and help us prioritizing features.

An Open Source Project Made With ❤️​

Before I close up this blog post, I want to address that WebdriverIO is an open source project maintained by dedicated people who love open source. Often, I get the feeling that people take this work for granted and forget that there are real humans spending their free time to provide some piece of software to everyone for free. As @left_pad stated in the official Babel7 release:

"[...] I can only describe it as dread when seeing a message from someone online wondering why something hasn't been released while another asks why this bug isn't fixed yet. I want to just rush it out and be done with it but I also have a desire to take this seriously."

Please always be reminded that when you open an issue or ask for a feature that you are basically asking someone to spend his time on something to give you exactly that for free! Open source project can only work and survive if everyone participates and helps out with something. We are all humans and bugs happen, if you find them, please let us know in a way that we can easily work with the information and quickly fix it. It's even better if everyone once in a while takes some time of his day to contribute back. We are maintaining a list of well described issues that anyone can claim and start working on.


Again, this project is not sponsored nor owned by any company. It is a collaborative effort of an inclusive community that loves to help each other out. Let's continue to stay exactly that!

Thank You​

Finally, I want to thank a few people that have helped to make this release happen; and/or for being such great people in the community. First, I want to thank all 34 contributors that participated in making this happen, as well as all the other 328 people that have been collaborating since the beginning.


I personally want to thank Kevin Lamping for making a stellar online learning course as well as so so much other great content on YouTube over the last few years. As mentioned above - also a big thank you to Will Brock for his video course on the new release.

I want to thank everyone who has been deeply involved in the support channel helping people out on daily basis. With over 3500 users it became impossible for me to answer everyone on the level I did before. Thank you Erwin Heitzman, Tu Huynh, Jim Davis, Xu Cao, Boris Osipov and Wim Selles.

Big shoutout to Daniel Chivescu and Josh Cypher who have been giving talks on WebdriverIO around the world.


And last but not least thank you Adam Bjerstedt, who has not only been helping out in the community channel; but also for helping to push out the v5 release at the end.


🙏

Welcome! How can I help?

WebdriverIO AI Copilot