WebdriverIO for newbies

WebdriverIO is a tool used to create automated browser tests. The following tutorial is aimed at people who have very little or no experience in writing automated tests. The aim of the tutorial is to:

1. Create a very basic framework from scratch that will run locally on your machine.

2. Write an automated test to spin up a web browser and check the web page title.

Pre-requisites:

• Node.js (https://nodejs.org/en/)
  Follow the instructions for install. To check installation is successful, run
  node -v in the terminal, you should see the Node version installed.
• NPM ( https://www.npmjs.com/)
  This will be installed with node. To check, run npm -v in the terminal, you should see the NPM version installed. If not installed, follow the instructions for install from the link above.
• A text editor for Javascript
  For example, Atom (https://atom.io/).
• Java (https://www.java.com/en/download/).
  Installed and added to your path (this is a requirement for Webdriverio).

Creating a skeleton project

1. Create a directory.

Create a directory where you want to store your project. For example, Desktop > Development > webdriver-io-tutorial.

2. Initiate a new NPM package.

Open your terminal, tab into the folder you have just created and type:

npm init

‘Npm init’ will set up a new NPM package. On initialising, you will be prompted to enter a package name, version, description, entry point, test command, git repo, keywords, author, licence. You can fill this in as you like or just hit ‘enter’ for each to get started. You will be asked — ‘Is this OK?’ Type ‘Yes’. Your terminal should look something like this:

To check this has worked successfully, look in the folder you have just created and you will see a package.json — this file lists the packages that your project depends on. At the moment, it will only contain the information you provided on initialisation.

3. Install webdriverio.

In the terminal (making sure you’re still in the project root), install webdriverio to your dev dependencies by typing:

npm install webdriverio --save-dev

To check this installation has been successful, open your package.json file and check that webdriverio now appears under ‘devDependancies’. You will also notice a node_modules folder has appeared. This is where all your dependencies packages are stored.

4. Create a wdio config.

Now that you have installed webdriverio, create a wdio.config.js file. This file will specify the location of the tests, frameworks you want to use, reporters, browsers and general config of the project. Conveniently, we can create this file pretty easily by running the following command in the terminal (again making sure you’re in the project root).

./node_modules/.bin/wdio config

The terminal will prompt some questions about how you want to set up your config file. This example will use the following configuration, but amend as you need (note that selenium-standalone is added as a required service, this will mean there is no need to start up a separate selenium server before running tests):

To check the config has successfully been created, a file called wdio.conf.js should now appear in the project root. Open this file to check or amend any of the information you provided in the terminal.

6. Create a directory for the tests

This example will use mocha as a framework for structuring tests. At a very high level, mocha is a javascript test framework for node.js, which supports asynchronous testing, the use of many assertion libraries, a high level of browser support and test coverage reports. If you followed the instructions above to create your config file, then mocha should already be installed and available to use in your project.

In the project root, create a folder which matches the spec pattern you specified in the config. If you followed the example above, you will want to create a folder called ‘test’ and within that, a folder called ‘specs’. You can create this manually or by running the following command in the terminal from the project root:

mkdir -p ./test/specs

7. Create a test.spec.js file

Within the test/specs folder, create a file for your first test. For example test.spec.js.In this file, let’s add a simple test to verify the title of the ASOS homepage. You can copy and paste the code below as an example.

describe('ASOS homepage', () => {
    it('should display the correct homepage title', () => {
        browser.url('http://asos.com');
        const title = browser.getTitle();
        assert.equal(title, 'ASOS | Online Shopping for the Latest Clothes & Fashion');
    });
});

A description of what the code is doing:

• browser.url('http://asos.com') browser.url() navigates to a url, in this case http://asos.com.
• const title = browser.getTitle() browser.getTitle() gets the title of the current page in the browser and returns a string, in this case it will get the title of ASOS.com. The ‘const title =’ before, saves the string variable as ‘title’, which we will be able to refer to later.
• assert.equal(title, ‘ASOS | Online Shopping for the Latest Clothes & Fashion’) Is using an assertion to say, make sure the variable we have just saved (title), is equal to ASOS | Online Shopping for the Latest Clothes & Fashion

8. Install chai for webdriverio

Before trying to run anything, you will need to install chai, which will be used to handle assertions. In the terminal run the following commands:

npm install chai --save-dev

and

npm install chai-webdriverio --save-dev

To check that everything is installed as expected, open your package.json and check that it looks something like this:

{
  "name": "webdriver-io-tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "chai": "^4.2.0",
    "chai-webdriverio": "^0.4.3",
    "wdio-mocha-framework": "^0.6.4",
    "wdio-selenium-standalone-service": "0.0.11",
    "webdriverio": "^4.14.0"
  }
}

9. Add a ‘before test’ step

Now, add chai to your wdio.conf.js file and set it as a global requirement for all tests. To do this, in the wdio.conf.js file, add the following piece of code to the end of the file and save:

beforeTest: () => {
      const chai = require('chai');
      const chaiWebdriver = require('chai-webdriverio').default;
      chai.use(chaiWebdriver(browser));
      global.assert = chai.assert;
    },

The ‘beforeTest’ snippet will run the containing code before every test, regardless where the file is saved in the spec folder. In this case, it will set a global assert so you won’t need to import it into every test file. You can also use chai’s ‘expect’ or ‘should’ options.

10. Run the test!

From the terminal, run the following command:

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

You should see a web browser spin up and navigate to ASOS. In the terminal you should see the following:

The green dot indicates that the test has passed! If you want to check the test is really working, then change the expected title in your test.spec.js file to something incorrect and run the test again. You should see an error in the terminal which will look something like this:

Tip: You may also want to consider adding this command as a script in your package.json, so instead of running ./node_modules/.bin/wdio wdio.conf.js you can just run npm run test to run the tests. To do this — amend the ‘script’ section in your package.json to the following:

"scripts": {
    "test": "./node_modules/.bin/wdio wdio.conf.js"
  },

Done!

Now you have a very basic framework to start building automated tests. I would recommend reading through the webdriverIO API documentation to see the available browser commands and a more detailed explanation of what they are doing(http://webdriver.io/api.html). It is also worth reading through the developer guide for more options around using page objects, compatible frameworks, various plugins and test runners etc.

Written by Lizzie Hiles
QA engineer @ ASOS
https://www.linkedin.com/in/lizzie-hiles-88b898123/