Setting Up WebdriverIO For Automated Website Testing

I’ve been writing about Selenium IDE for years , telling anyone that would listen how it helps automate user experience testing.    Recently , with the demise of Selenium IDE along with the engine updates to Firefox, I started talking about migrating to Selenium Webdriver.    Think of Selenium Webdriver as the “professional version” of Selenium IDE.    It is far more powerful but is a pain to setup and does require minimal JavaScript coding skills.

By installing a few node modules on my laptop I now can write fully UX tests in JavaScript using simple language without the need to work with external services.   Install node, install a handful of NodeJS modules, run the WebdriverIO config and you are ready to write some simple tests.

First things first -let’s get setup.

Getting setup

I have found the best documentation for Selenium Webdriver is available on WebdriverIO including how to layer Mocha and Chai on top.    To get things working for the test I present here you need a stack of components.    Mocha and Chai are extra “icing” that is not necessarily required for automated testing but it makes the code nicer to read.

I advise not using Selenium on its own without WebdriverIO and Mocha as a minimum.   I started there and quickly realized that I was writing configuration sharing and testing management libraries that someone else must have already written — they had, it is called WebdriverIO.   I then realized someone probably wrote better test reporting and other tools to make the code less “code-like” which is why Mocha and Chai were added.

Skip all the drama and install the entire stack.   Selenium Standalone Server, WebdriverIO, Mocha, and Chai.   It can all be done from the Node Package Manager (npm) — WebdriverIO has some good documentation on getting this setup.

Personally I use phpStorm to write my code and after creating my TestThis project in a new directory let phpStorm’s built-in NPM tool install the libraries for me.   I’ve written an article about that already.

In the end you have something that I picture in my mind like the following stack:

WebdriverIO Test Stack Components
WebdriverIO Test Stack Components

Selenium Standalone Server – talks to the browser through driver classes.   I found Chrome works best, maybe because NodeJS uses the same V8 engine included in Chrome.   Safari Remote Automation was cool but after a nasty input processing bug I skipped it in favor of Chrome.

Selenium Webdriver – the JavaScript interface that talks to the Standalone Server.

WebdriverIO – reads configuration files and adds some “syntax sugar” to make writing Selenium Webdriver tests easier.

Mocha – adds more “syntax sugar” , this one for reporting and things like “make sure this is here” language elements.

Chai – yup, even more sugar, this one lets you write things that are more human-friendly like the_input_box.should.exist


Setup your configuration file

This will tell the test environment things like what browser to use and what URL to run the tests on.

Then use a configuration file like this — WebdriverIO has a configuration building tool.

configuring webdriverio
configuring webdriverio

You can later modify the configuration file to something like this that I use in more advanced tests:

exports.config = {
    baseUrl: '',
    specs: [
    maxInstances: 10,
    capabilities: [{
        maxInstances: 2,
        browserName: 'chrome'
    sync: true,

    // Level of logging verbosity: silent | verbose | command | data | result | error
    logLevel: 'error',

    // Enables colors for log output.
    coloredLogs: true,

    // Warns when a deprecated command is used
    deprecationWarnings: true,

    // If you only want to run your tests until a specific amount of tests have failed use
    // bail (default is 0 - don't bail, run all tests).
    bail: 0,

    // Saves a screenshot to a given path if a command fails.
    screenshotPath: './errorShots/',
    waitforTimeout: 10000,
    connectionRetryTimeout: 90000,
    connectionRetryCount: 3,

    services: ['selenium-standalone'],
    framework: 'mocha',
    mochaOpts: {
        ui: 'bdd',
        timeout: 40000

    reporters: ['spec'],
    reporterOptions: {
        outputDir: './reports/'
    before: function() {
        var chai = require('chai');
        global.expect = chai.expect;
        global.should = chai.should();

            width: 1200,
            height: 800

    // creds
    credentials: {
        superman : {
            username: process.env.SA_USER,
            password: process.env.SA_PASS

    // organization
    suites: {
        main: [


You can read all about this on the WebdriverIO site.   The highlights:

  • This will open up Chrome when my tests are run.
  • Any browser commands will run against the URL.
  • Added  a “suites” organization section so I can run groups of tests by adding –suite main (for example) to run a subset of tests.
  • Added a credentials section so I can use browser.options.credentials.<key>.<key> within my tests for login processing.
  • Set the credentials to pickup the process environment variables I set earlier.
  • Configured to set the chai elements for every test (think of it as a per-JavaScript file included header).
  • Configured to use the BDD test formats and a per-script timeout of 40 seconds for Mocha.

Summary of the process

Install NodeJS.

Create a directory where you will put your tests and run npm in there.   It will create a node_modules sub-directory.

Using Node Package Manager (npm) install:

  • selenium-standalone
  • webdriverio (make it easier to write Selenium tests)

Create another subdirectory, I call it test for consistency, and cd into that directory.

Run wdio config to create the config.js file that your tests will reference when running.

Edit the config file and add the Chai and Mocha options to the auto-created config file.

Here is a video of the process from setting up the standard WebdriverIO configuration in npm through running a simple “open the site” test.

[videopress eXJG3JjK]

Create some tests

Now that everything it setup it is time to write some test scripts.

Let’s look into that next.

One thought on “Setting Up WebdriverIO For Automated Website Testing

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.