Join Chat.svg)

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

See the corresponding examples.

How to run tests

Download the latest Selenium standalone server and run it via
```
$ java -jar selenium-server-standalone-2.41.0.jar
```
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 ../../..
```
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
```

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:

icaaq/webdriverio

WebdriverIO ![Gitter](https://badges.gitter.im/Join Chat.svg)

How to install it

Usage

Options

desiredCapabilities

logLevel

logOutput

baseUrl

coloredLogs

errorScreenshotDir

waitforTimeout

Selector API

List of current commands methods

Eventhandling

Eventhandling

Adding custom commands

Run multiple browser at the same time

Selenium cloud providers

How to run tests

NPM Maintainers