Tester, I introduce to you WebdriverIO

New Year, New Framework

In the last couple of years, we have seen a boom of Node.js browser automation libraries using the Webdriver protocol. WebdriverIO is one of those libraries which has seen its popularity growing progressively. You can visualize this through the npm trends graph (you can learn more about npm trends in this post) showing the number of downloads up to two years ago.

The popularity of this library is due to some of its excellent characteristics which make it compatible with most test frameworks. It also makes it reasonably easy to jump on the ‘automation wagon’ for the newbies out there.

Quickly!! Set it up!

Let’s see how you could set up, to begin exploring the many features of WebdriverIO.

First off, prepare your framework root directory by creating a folder and go to it. Then you can initialise your Node.js framework by running the command:

You will need to enter some data for package name, version and description, or just leave them as defaults. Confirm your entries by entering yes when prompted.

Now we can go ahead and install WebdriverIO. This will install WebdriverIO as well as its dependencies and include WebdriverIO as a dependency of the framework.

npm install webdriverio

Once done, we can launch the WebdriverIO configuration helper:

./node_modules/.bin/wdio config

This will show multiple options, so let’s start with the easiest ones. Press Enter on On my local machine for the first question. The second one allows you to choose a test runner from different frameworks. The listed ones are all quite used, with a lot of similarities in their way of usage. However, a quick search on npm trends shows mocha as the most downloaded. We can discuss this on a different topic, so for now, let’s go with mocha. The next question asks you if you want the configuration tool to install the chosen framework automatically, so let’s type Y. We can now select the location of our tests, let’s go with the default one by just pressing Enter. Now we are presented with a list of reporters to display the outcome of our tests. As you can see, we are provided with a vast number of reporters which can either just output result in the terminal, as well as sending results to known CI and test case management tools such as TeamCity and TestRail.

Half way there…

WebdriverIO also gives us the choice of using multiple reporters and therefore outputting our results to different locations. For our basic example, we can go with the spec reporter by going down with the Down Arrow button and pressing Space to choose the reporter. Enter to confirm your choice. Press Enter for the next question so that this reporter is automatically installed. For the next option, we can install services which are necessary, such as ChromeDriver to run the tests using the Chrome browser and selenium-standalone to interpret our commands through the Selenium API. So let’s click the Space button on selenium-standalone and confirm using Enter. Press Enter to confirm automatic installation. For the level of verbosity, we can go with the error so as to help us when having issues. When our tests fail, the framework generates a screenshot showing the browser at the point of failure. Let’s go with the choice of default location suggested by the helper by pressing Enter. Lastly, we can keep the base URL pointing to localhost by again pressing Enter.

Done! Let’s start automating

Wait wait, let’s check that all the required packages are installed, shall we? First off, let’s get the packages currently required within the package.json file by running:

npm install

Then, we can make sure that mocha, our test runner, is also installed by running:

./node_modules/mocha/bin/mocha

This will output that no test files found. That’s okay, it means that mocha is all set within our project. Next, we need to check that selenium-standalone is available and use it to install the required ChromeDriver. Let’s do that by running:

./node_modules/selenium-standalone/bin/selenium-standalone install

If everything is fine, this will install Selenium standalone, ChromeDriver and GeckoDriver.

Once completing our checks and required installations, we can proceed with writing our first test. Next thing to do is open the project in your preferred IDE, so for this example, I will use the free text editor, Atom.

Let’s do a simple scenario where we need to verify that the Webdriver.IO navigational links are working as they should.

First, we need to create a spec file which will contain our test scenario. Create the folder structure and a file called navigationLinksTest.js under ./test/specs folder. We will create four simple tests which check that each navigational link takes the user to the expected URL. We will have three steps in each test:

Setup — Opening the browser to a given URL (the Given step in Gherkin syntax)

Action — Clicking the link that needs to test (the When step in Gherkin syntax)

Assert — Assert that the actual URL the test landed on is the expected one (the Then step in Gherkin syntax)

Talking about assertions, mocha does not come with an assertion library out of the box, so what we will do is require the assert library within the spec file. So, have a look at the code below:

var assert = require('assert');

describe('WebdriverIO Navigation Links', function() {
    it('should go to Developer Guide page when choosing Developer Guide link', function () {
        browser.url('http://webdriver.io');
        browser.click('=Developer Guide');
        assert.equal(browser.getUrl(), 'http://webdriver.io/guide.html');
    });

    it('should go to API page when choosing API link', function () {
        browser.url('http://webdriver.io');
        browser.click('=API');
        assert.equal(browser.getUrl(), 'http://webdriver.io/api.html');
    });

    it('should go to Contribute page when choosing Contribute link', function () {
        browser.url('http://webdriver.io');
        browser.click('=Contribute');
        assert.equal(browser.getUrl(), 'http://webdriver.io/contribute.html');
    });

    it('should go to Home page when choosing Home link', function () {
        browser.url('http://webdriver.io/api.html');
        browser.click('=Home');
        assert.equal(browser.getUrl(), 'http://webdriver.io/');
    });

});

By default, the WebdriverIO configuration file sets Firefox as the browser, so you need to change this to Chrome by setting this line inside wdio.conf.js to:

browserName: 'Chrome'

That’s it! Now save the file and run tests by running:

./node_modules/.bin/wdio wdio.conf.js

Voila! Your first WebdriverIO tests!

…and they lived happily ever after

This simple example of using WebdriverIO for your functional tests is far from being perfect. First of all, it follows no design pattern (we will probably discuss this in future posts), and secondly, it has no complexity involved, of which you will undoubtedly face once you need to prepare more challenging test scenarios. It is fair to say that no test framework provides an entirely stress-free experience of creating automated tests, this is no fairy tale story here. Things will get challenging, tricky, but the answer is out there. When you face a hurdle, consult with WebdriverIO’s official page as well as the usual StackOverflow. Practice, plan your tests, learn from your mistakes, learn from other testers’ mistakes, and you will succeed in making the best use out of this great tool!

Want to share your thought about WebdriverIO? Leave us a comment below!

P.S. If you want to have a look at the code, you can do so by going to https://github.com/testautonation/Webdriverio-intro

Originally published at https://testautonation.com in 01/2018.