webdriverio

What is webdriverio?

WebdriverIO is an open-source testing utility for Node.js that allows you to control a browser or a mobile application with just a few lines of code. It is built on top of WebDriver protocol and supports both desktop browsers and mobile applications. It provides a lot of useful features to create end-to-end tests, supports synchronous and asynchronous modes, and integrates with various test frameworks like Mocha, Jasmine, and Cucumber.

What are webdriverio's main functionalities?

Browser Automation

Automate web browsers by performing actions like navigating to URLs, clicking on elements, and retrieving page information.

const { remote } = require('webdriverio');

(async () => {
  const browser = await remote({
    capabilities: { browserName: 'chrome' }
  });

  await browser.url('https://example.com');
  const title = await browser.getTitle();
  console.log('Title was: ' + title);

  await browser.deleteSession();
})();

Element Interaction

Interact with web elements such as input fields, buttons, and links by sending keystrokes, clicking, and retrieving attributes.

const { remote } = require('webdriverio');

(async () => {
  const browser = await remote({
    capabilities: { browserName: 'chrome' }
  });

  await browser.url('https://example.com/login');
  await browser.setValue('#username', 'user123');
  await browser.setValue('#password', 'pass123');
  await browser.click('#submit');

  await browser.deleteSession();
})();

Mobile Application Testing

Test mobile applications by launching them on simulators, emulators, or real devices and interacting with them just like with browser automation.

const { remote } = require('webdriverio');

(async () => {
  const browser = await remote({
    path: '/wd/hub',
    capabilities: {
      platformName: 'Android',
      'appium:deviceName': 'emulator',
      'appium:app': '/path/to/your.app'
    }
  });

  // Your mobile testing code here

  await browser.deleteSession();
})();

Integration with Test Runners

Easily integrate with test runners like Mocha, Jasmine, or Cucumber to create structured and maintainable test suites.

const { remote } = require('webdriverio');

describe('My application', () => {
  it('should work with webdriverio', async () => {
    const browser = await remote({
      capabilities: { browserName: 'chrome' }
    });

    await browser.url('https://example.com');
    expect(await browser.getTitle()).toBe('Expected Title');

    await browser.deleteSession();
  });
});

Other packages similar to webdriverio

selenium-webdriver

Selenium WebDriver is one of the most popular browser automation tools. It requires setting up a standalone server and writing more boilerplate code compared to WebdriverIO, which provides a more concise API and integrated test runner support.

puppeteer

Puppeteer is a Node library developed by the Chrome DevTools team. It provides a high-level API to control Chrome or Chromium over the DevTools Protocol. Puppeteer is typically faster and more stable for Chrome/Chromium automation because it uses the DevTools protocol, but it does not support multiple browsers out of the box like WebdriverIO does.

cypress

Cypress is a front-end testing tool built for the modern web. It is both a library for writing tests as well as a test runner. It offers a rich interactive interface for running tests but is limited to running tests within its own browser-based test runner, which can be a limitation compared to WebdriverIO's support for various browsers and mobile platforms.

nightwatch

Nightwatch.js is an automated testing framework for web applications and websites, written in Node.js and using the W3C WebDriver API. It is similar to WebdriverIO but has its own test runner and asserts library, which can make it easier to set up and start writing tests. However, it might not be as feature-rich as WebdriverIO in terms of community plugins and integrations.

README

WebdriverIO 

This library is a webdriver module for Node.js. It makes it possible to write super easy selenium tests in your favorite BDD or TDD test framework. It was originated by Camilo Tapia's initial selenium project called WebdriverJS.

Have a look at the many examples.

For news or announcements follow @webdriverio on Twitter.

How to install it

npm install webdriverio

Usage

Make sure you have a running Selenium standalone/grid/hub. Or use selenium-standalone package to run one easily.

Once you initialized your WebdriverIO instance you can chain all available protocol and action commands to execute asynchronous requests sequentially. WebdriverIO supports callback and promise based chaining. You can either pass a callback as last parameter to handle with the command results:

var webdriverio = require('webdriverio');
var options = {
    desiredCapabilities: {
        browserName: 'chrome'
    }
};
var client = webdriverio.remote(options);

client
    .init()
    .url('http://www.google.com')
    .getTitle(function(err, title) {
        console.log('Title was: ' + title);
    })
    .end();

or you can handle it like a A+ promise:

client
    .init()
    .url('http://www.google.com')
    .getTitle()
        .then(function(title) {
            console.log('Title was: ' + title);
        })
        .catch(function(error) {
            console.log('uups something went wrong', error);
        })
    .end();

Using promised based assertion libraries like chai-as-promised it makes functional testing with WebdriverIO super easy. No nested callbacks anymore! No confusion whether to use callbacks or promises!

describe('example page', function() {
    var chai = require('chai');
    var chaiAsPromised = require('chai-as-promised');

    chai.use(chaiAsPromised);
    chai.should();
    chaiAsPromised.transferPromiseness = client.transferPromiseness;

    before(function() {
        return client.init().url('http://example.com');
    });

    it('should display right title and #someElem', function() {
        return client.getTitle().should.become('Example Title')
                     .isVisible('#someElem').should.eventually.be.true;
    });

    after(function() {
        return client.end();
    });

});

If you're looking for a complete workflow example, this post explains a way to run tests using gulp, selenium-standalone, Mocha and WebdriverIO. If you want to use Cucumber for real BDD testing check out the cucumber-boilerplate project.

Options

desiredCapabilities

Type: Object

Example:

browserName: 'chrome',  // options: firefox, chrome, opera, safari
version: '27.0',        // browser version
platform: 'XP',         // OS platform
tags: ['tag1','tag2'],  // specify some tags (e.g. if you use Sauce Labs)
name: 'my test'         // set name for test (e.g. if you use Sauce Labs)

See the Selenium documentation for a list of the available capabilities.

logLevel

Level of logging verbosity.

Type: String

Default: silent

Options: verbose | silent | command | data | result

logOutput

Pipe WebdriverIO logs into a file. You can define either a directory and WebdriverIO generates a filename for the log file or you can pass in writeable stream and everything gets redirected to that (last one doesn't work yet with the wdio runner).

Type: String|writeable stream

Defaults: null

baseUrl

Shorten url command calls by setting a base url. If your url parameter starts with / the base url gets prepended.

Type: String

Default: null

coloredLogs

Type: Boolean

Default: true

Enables colors for log output

errorScreenshotDir

Saves a screenshot to a given path if a command fails

Type: String|null

Default: null

waitforTimeout

Default timeout for all waitForXXX commands.

Type: Number

Default: 500

Selector API

The JsonWireProtocol provides several strategies to query an element. WebdriverIO simplifies these to make it more familiar with the common existing selector libraries like Sizzle. The following selector types are supported:

• CSS query selector
  e.g. client.click('h2.subheading a', function(err,res) {...}) etc.
• link text
  To get an anchor element with a specific text in it (f.i. <a href="http://webdriver.io">WebdriverIO</a>) query the text starting with an equal (=) sign. In this example use =WebdriverIO
• partial link text
  To find a anchor element whose visible text partially matches your search value, query it by using *= in front of the query string (e.g. *=driver)
• tag name
  To query an element with a specific tag name use <tag> or <tag />
• name attribute
  For quering elements with a specific name attribute you can eather use a normal CSS3 selector or the provided name strategy from the JsonWireProtocol by passing something like [name="some-name"] as selector parameter
• xPath
  It is also possible to query elements via a specific xPath. The selector has to have a format like for example //BODY/DIV[6]/DIV[1]/SPAN[1]

In near future WebdriverIO will cover more selector features like form selector (e.g. :password,:file etc) or positional selectors like :first or :nth.

List of current commands methods

To see the full list of available commands check out the WebdriverIO API.

Eventhandling

WebdriverIO inherits several function from the NodeJS EventEmitter object. Additionally it provides an experimental way to register events on browser side (like click, focus, keypress etc.).

Eventhandling

The following functions are supported: on,once,emit,removeListener,removeAllListeners. They behave exactly as described in the official NodeJS docs. There are some predefined events (error,init,end, command) which cover important WebdriverIO events.

Example:

client.on('error', function(e) {
    // will be executed everytime an error occured
    // e.g. when element couldn't be found
    console.log(e.body.value.class);   // -> "org.openqa.selenium.NoSuchElementException"
    console.log(e.body.value.message); // -> "no such element ..."
})

All commands are chainable, so you can use them while chaining your commands

var cnt;

client
    .init()
    .once('countme', function(e) {
        console.log(e.elements.length, 'elements were found');
    })
    .elements('.myElem', function(err,res) {
        cnt = res.value;
    })
    .emit('countme', cnt)
    .end();

Note: make sure you check out the Browserevent side project that enables event-handling on client side (Yes, in the browser!! ;-).

Adding custom commands

If you want to extend the client with your own set of commands there is a method called addCommand available from the client object:

var client = require("webdriverio").remote();

// example: create a command the returns the current url and title as one result
// last parameter has to be a callback function that needs to be called
// when the command has finished (otherwise the queue stops)
client.addCommand("getUrlAndTitle", function(customVar, cb) {
    this.url(function(err,urlResult) {
        this.getTitle(function(err,titleResult) {
            var specialResult = {url: urlResult.value, title: titleResult};
            cb(err,specialResult);
            console.log(customVar); // "a custom variable"
        })
    });
});

client
    .init()
    .url('http://www.github.com')
    .getUrlAndTitle('a custom variable', function(err,result){
        assert.equal(null, err)
        assert.strictEqual(result.url,'https://github.com/');
        assert.strictEqual(result.title,'GitHub · Build software better, together.');
    })
    .end();

Run multiple browser at the same time

This feature isn't quite ready for release yet but it is already merged into master so you can already play arround with it. Checkout the example here.

Selenium cloud providers

WebdriverIO supports

• Sauce Labs
• BrowserStack
• TestingBot

See the corresponding examples.

How to run tests

1. Download the latest Selenium standalone server and run it via

   $ java -jar selenium-server-standalone-2.41.0.jar
   

2. Make sure you have all the dependencies installed

   $ npm install
   

   also all Bower packages required by our testpage

   $ cd test/site/www && bower install && cd ../../..
   

3. Start a local server that delivers our test page to the browser. We recommend to use http-server

   $ cd /root/dir/of/webdriverio
   $ http-server -p 8080
   

4. Depending on your feature/fix/patch make sure it gets covered by a test. To ensure that you can run one of the following commands:

   # if your patch is browser specific
   # (e.g. upload files)
   npm run-script test-desktop
   
   # if your patch is mobile specific
   # (e.g. flick or swipe tests)
   npm run-script test-mobile
   
   # if your patch is functional and hasn't something to do with Selenium
   # (e.g. library specific fixes like changes within EventHandler.js)
   npm run-script test-functional
   

   While developing you can run tests on specific specs by passing another environment variable _SPEC, e.g.

   $ _SPEC=test/spec/YOURSPEC.js npm run-script test-desktop
   

NPM Maintainers

The npm module for this library is maintained by:

• Camilo Tapia
• Dan Jenkins
• Christian Bromann
• Vincent Voyer