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 inital 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.

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

webdriverio
    .remote(options)
    .init()
    .url('http://www.google.com')
    .title(function(err, res) {
        console.log('Title was: ' + res.value);
    })
    .end();

See the full list of options you can pass to .remote(options).

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

Type: String

Default: silent

Options: verbose | silent | command | data | result

screenshotPath

Saves a screenshot to a given path if Selenium driver crashes

Type: String|null

Default: null

singleton

Type: Boolean

Default: false

Set to true if you always want to reuse the same remote

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.

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();

Local testing

If you want to help us in developing WebdriverIO, you can easily add mocha tests and run them locally:

npm install -g selenium-standalone http-server phantomjs

# start a local Selenium instances
start-selenium

# serves the test directory holding the test files
http-server

# runs tests !
npm test

Selenium cloud providers

WebdriverIO supports

• Sauce Labs
• BrowserStack
• TestingBot

See the corresponding examples.

List of current commands methods

These are the current implemented command methods. All methods take from 0 to a couple of parameters. Also all methods accept a callback so that we can assert values or have more logic when the callback is called. WebdriverIO has all JSONWire protocol commands implemented and even a whole bunch of undocumented Appium commands of the Selenium.

• addValue(String selector, String|String[] value, Function callback)
  adds a value to an object found by a selector. You can also use unicode characters like Left arrow or Back space. You'll find all supported characters here. To do that, the value has to correspond to a key from the table.
• call(callback)
  call given function in async order of current command queue
• chooseFile(String selector, String localFilePath, Function callback)
  Given a selector corresponding to an <input type=file>, will upload the local file to the browser machine and fill the form accordingly. It does not submit the form for you.
• clearElement(String selector, Function callback)
  clear an element of text
• click(String selector, Function callback)
  Clicks on an element based on a selector.
• close([String tab ID to focus on,] Function callback)
  Close the current window (optional: and switch focus to opended tab)
• deleteCookie(String name, Function callback)
  Delete a cookie for current page.
• doubleClick(String selector, Function callback)
  Clicks on an element based on a selector
• drag(String selector, Number startX, Number startY, Number endX, Number endY, Number touchCount, Number duration, Function callback)
  Perform a drag on the screen or an element (works only on Appium)
• dragAndDrop(String sourceCssSelector, String destinationCssSelector, Function callback)
  Drags an item to a destination
• dragDown(String selector, Number touchCount, Number duration, Function callback)
  Perform a drag down on an element (works only on Appium)
• dragLeft(String selector, Number touchCount, Number duration, Function callback)
  Perform a drag left on an element (works only on Appium)
• dragRight(String selector, Number touchCount, Number duration, Function callback)
  Perform a drag right on an element (works only on Appium)
• dragUp(String selector, Number touchCount, Number duration, Function callback)
  Perform a drag up on an element (works only on Appium)
• emit(String eventName, [arg1], [arg2], [...])
  Execute each event listeners in order with the supplied arguments.
• end(Function callback)
  Ends a sessions (closes the browser)
• endAll(Function callback)
  Ends all sessions (closes the browser)
• execute(String or Function script, Array arguments, Function callback)
  Inject a snippet of JavaScript into the page for execution in the context of the currently selected frame. If script is a Function, arguments is required.
• flick(String selector, Number startX, Number startY, Number endX, Number endY, Number touchCount, Function callback)
  Perform a flick on the screen or an element (works only on Appium)
• getAttribute(String selector, String attribute name, Function callback)
  Get an attribute from an dom obj based on the selector and attribute name
• getCookie(String name, Function callback)
  Get cookie for the current page. If no cookie name is specified the command will return all cookies.
• getCssProperty(String selector, String css property name, Function callback)
  Gets a css property from a dom object selected with a selector
• getCurrentTabId(Function callback)
  Retrieve the current window handle.
• getElementSize(String selector, Function callback)
  Gets the width and height for an object based on the selector
• getLocation(String selector, Function callback)
  Gets the x and y coordinate for an object based on the selector
• getLocationInView(String selector, Function callback)
  Gets the x and y coordinate for an object based on the selector in the view
• getOrientation(Function callback)
  Get the current browser orientation.
• getSource(Function callback)
  Gets source code of the page
• getTabIds(Function callback)
  Retrieve the list of all window handles available to the session.
• getTagName(String selector, Function callback)
  Gets the tag name of a dom obj found by the selector
• getText(String selector, Function callback)
  Gets the text content from a dom obj found by the selector
• getTitle(Function callback)
  Gets the title of the page
• getValue(String selector, Function callback)
  Gets the value of a dom obj found by selector
• isSelected(String selector, Function callback)
  Return true or false if an OPTION element, or an INPUT element of type checkbox or radiobutton is currently selected (found by selector).
• isVisible(String selector, Function callback)
  Return true or false if the selected dom obj is visible (found by selector)
• leftClick(String selector, Function callback)
  Apply left click at an element. If selector is not provided, click at the last moved-to location.
• hold(String selector,Function callback)
  Long press on an element using finger motion events.
• middleClick(String selector, Function callback)
  Apply middle click at an element. If selector is not provided, click at the last moved-to location.
• moveToObject(String selector, Function callback)
  Moves the page to the selected dom object
• newWindow(String url, String name for the new window, String new window features (e.g. size, position, scrollbars, etc.), Function callback)
  equivalent function to Window.open() in a browser
• on(String eventName, Function fn)
  Register event listener on specific event (the following are already defined: init,command,end,error)
• once(String eventName, Function fn)
  Adds a one time listener for the event (the following are already defined: init,command,end,error)
• pause(Integer milliseconds, Function callback)
  Pauses the commands by the provided milliseconds
• refresh(Function callback)
  Refresh the current page
• release(String selector, Function callback)
  Finger up on an element
• removeListener(String eventName, Function fn)
  Remove a listener from the listener array for the specified event
• removeAllListeners([String eventName])
  Removes all listeners, or those of the specified event
• rightClick(String selector, Function callback)
  Apply right click at an element. If selector is not provided, click at the last moved-to location.
• saveScreenshot(String path to file, Function callback)
  Saves a screenshot as a png from the current state of the browser
• scroll(String selector, Functioncallback)
  Scroll to a specific element. You can also pass two offset values as parameter to scroll to a specific position (e.g. scroll(xoffset,yoffset,callback)).
• setCookie(Object cookie, Function callback)
  Sets a cookie for current page.
• setOrientation(String orientation, Function callback)
  Set the current browser orientation.
• setValue(String selector, String|String[] value, Function callback)
  Sets a value to an object found by a selector (clears value before). You can also use unicode characters like Left arrow or Back space. You'll find all supported characters here. To do that, the value has to correspond to a key from the table.
• submitForm(String selector, Function callback)
  Submits a form found by the selector
• switchTab(String tab ID)
  switch focus to a particular tab/window
• tap(String selector,Number x,Number y,Number tapCount,Number touchCount,Number duration,Function callback)
  Perform a tap on the screen or an element (works only on Appium)
• touch(String selector, Function callback)
  Finger down on an element.
• waitFor(String selector, Integer milliseconds, Function callback)
  Waits for an object in the dom (selected by selector) for the amount of milliseconds provided. the callback is called with false if the object isnt found.

More on Selenium and its protocol

• Latest standalone server
• The protocol
• Some useful Selenium resources

NPM Maintainers

The npm module for this library is maintained by:

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