Webdriver/selenium 2.0 javascript bindings for nodejs

A WebDriver module for nodejs. Either use the super easy help commands or use the base Webdriver wire protocol commands.

It is written so its easy to add new protocol implementations and add helper commands so make testing easier. Each command resides as one file inside the node module folder which makes it easy to extend.

The two main reasons for this projects are:

1. Ease of use - Writing tests with webdriver should be very easy

2. Easy to extend - Adding helper functions, or more complicated sets and combinations of existing commands, should also be very easy.

How to install it

Either download it from github or use npm:

npm install webdriverjs

Example of webdriverjs

Run selenium server first:

java -jar node_modules/.bin/selenium-server-standalone-2.35.0.jar

Webdriverjs has just a few methods. Most of the methods you will use regurarly are the methods available from the client. To begin using Webdriverjs you just need to create a client. For testing you can use any nodejs test framework as well as any BDD/TDD assertion library.

example using Mocha and Chai

describe('my webdriverjs tests', function(){

    this.timeout(99999999);
    var client = {};

    before(function(){
            client = webdriverjs.remote(options);
            client.init();
    });

    it('Github test',function(done) {
        client
            .url('https://github.com/')
            .getElementSize('.header-logo-wordmark', function(err, result) {
                expect(err).to.be.null;
                assert.strictEqual(result.height , 30);
                assert.strictEqual(result.width, 94);
            })
            .getTitle(function(err, title) {
                expect(err).to.be.null;
                assert.strictEqual(title,'GitHub · Build software better, together.');
            })
            .getElementCssProperty('class name','subheading', 'color', function(err, result){
                expect(err).to.be.null;
                assert.strictEqual(result, 'rgba(136, 136, 136, 1)');
            })
            .call(done);
    });

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

See more examples with other libraries in the example directory.

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)

logLevel

Type: String
Default: verbose
Options: verbose | silent | command | data | result

singleton

Create client as singleton instance for use in different files
Type: Boolean
Default: true

Sauce Labs support

To run your tests via Sauce Labs, add the following attributes to your option object. If you have a public repository, never publish your Sauce Labs key! Export these informations as enviroment variables.

host: 'ondemand.saucelabs.com',               // Sauce Labs remote host
user: 'webdriverjs',                          // your username
key:  'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX'  // your account key

Find a Gist example here!

BrowserStack support

You can also run your tests with BrowserStack on a remote machine. To do that, put your username and BrowserStack key in your desiredCapabilities attribute and define BrowserStack as remote host.

desiredCapabilities: {
    'browser': 'firefox',
    ...
    'browserstack.user' : '<username>',
    'browserstack.key': '<key>'
},
host: 'hub.browserstack.com'

Find a Gist example here!

webdriverjs.endAll

If you wish to end all sessions, you can call the endAll method:

require("webdriverjs").endAll(callback);

Where callback is an optional parameter. This method can be used if you run lots of tests, and you want to make sure that all sessions on your selenium server are closed when you are done. Usually its enough to close each client with its end() method, but if you, for some reason, want to make sure that no sessions are open, use endAll(). (note: this method is also available from the client returned from .remote() as well, but its the same as webdriverjs.endAll())

webdriverjs.sessions

To get a list of all open sessions, you can call:

require("webdriverjs").sessions(callback);

which wil return an array with all sessions from selenium (note: this method is also available from the client returned from .remote() as well, but its the same as webdriverjs.sessions()).

Extending

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

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

// create a command the returns the current url and title as one result
// just to show an example
client.addCommand("getUrlAndTitle", function(callback) {
    this.url(function(err,urlResult) {
        this.getTitle(function(err,titleResult) {
            var specialResult = {url: urlResult.value, title: titleResult};
            if (typeof callback == "function") {
                callback(err,specialResult);
            }
        })
    });
});

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

List of current helper methods

These are the current implemented helper 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.

• addValue(String css selector, String value, Function callback)
  adds a value to an object found by a css 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.
• buttonClick(String css selector, Function callback)
  click on a button using a css selector
• call(callback)
  call given function in async order of current command queue
• clearElement(String css selector, Function callback)
  clear an element of text
• click(String css selector, Function callback)
  Clicks on an element based on a css selector
• deleteCookie(String name, Function callback)
  Delete a cookie for current page.
• doubleClick(String css selector, Function callback)
  Clicks on an element based on a css selector
• dragAndDrop(String sourceCssSelector, String destinationCssSelector, Function callback)
  Drags an item to a destination
• end(Function callback)
  Ends a sessions (closes the browser)
• endAll(Function callback)
  Ends all sessions (closes the browser)
• execute(String script, Array arguments, Function callback)
  Inject a snippet of JavaScript into the page for execution in the context of the currently selected frame.
• getAttribute(String css selector, String attribute name, Function callback)
  Get an attribute from an dom obj based on the css selector and attribute name
• getCookie(name, Function callback)
  Gets the cookie for current page.
• getCssProperty(String css selector, String css property name, Function callback)
  Gets a css property from a dom object selected with a css selector
• getElementCssProperty(String find by, String finder, String css property name, Function callback)
  Gets a css property from a dom object selected with one of the base selecting mechanisms in the webdriver protocol (class name, css selector, id, name, link text, partial link text, tag name, xpath)
• getElementSize(String css selector, Function callback)
  Gets the width and height for an object based on the css selector
• getLocation(String css selector, Function callback)
  Gets the x and y coordinate for an object based on the css selector
• getLocationInView(String css selector, Function callback)
  Gets the x and y coordinate for an object based on the css selector in the view
• getSource(Function callback)
  Gets source code of the page
• getTagName(String css selector, Function callback)
  Gets the tag name of a dom obj found by the css selector
• getText(String css selector, Function callback)
  Gets the text content from a dom obj found by the css selector
• getTitle(Function callback)
  Gets the title of the page
• getValue(String css selector, Function callback)
  Gets the value of a dom obj found by css selector
• isSelected(String css 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 css selector).
• isVisible(String css selector, Function callback)
  Return true or false if the selected dom obj is visible (found by css selector)
• moveToObject(String css selector, Function callback)
  Moves the page to the selected dom object
• pause(Integer milliseconds, Function callback)
  Pauses the commands by the provided milliseconds
• refresh(Function callback)
  Refresh the current page
• saveScreenshot(String path to file, Function callback)
  Saves a screenshot as a png from the current state of the browser
• setCookie(Object cookie, Function callback)
  Sets a cookie for current page.
• setValue(String css selector, String value, Function callback)
  Sets a value to an object found by a css 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 css selector, Function callback)
  Submits a form found by the css selector
• waitFor(String css selector, Integer milliseconds, Function callback)
  Waits for an object in the dom (selected by css selector) for the amount of milliseconds provided. the callback is called with false if the object isnt found.

List of current implemented wire protocol bindings

Here are the implemented bindings (and links to the official json protocol binding)

• alertAccept
• alertDismiss
• alertText
• buttondown
• buttonup
• element
• elementIdAttribute
• elementIdClick
• elementDoubleClick
• elementIdCssProperty
• elementIdDisplayed
• elementIdLocation
• elementIdLocationInView
• elementIdName
• elementIdSize
• elementIdText
• elementIdValue
• elementIdSelected
• elements
• execute
• frame
• init
• moveto
• screenshot
• session
• sessions
• status
• submit
• title
• url
• source
• window
• windowHandles
• windowHandlePosition
• windowHandleSize
• forward
• back
• refresh
• cookie
• cookieName

More on selenium and its protocol

• Latest standalone server
• The protocol

NPM Maintainers

The npm module for this library is maintained by:

• Camilo Tapia
• Dan Jenkins
• Christian Bromann