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/webdriverjs/bin/selenium-server-standalone-2.31.0.jar

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, 68);
            })
            .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.

Extending

If you want to extend with your own set of commands there is a method called addCommand:

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

Options

desiredCapabilities

Type: Object
Default capabilities:

browserName: 'firefox',  // options: firefox, chrome, opera, safari
version: '',
javascriptEnabled: true,
platform: 'ANY'

If selenium can't find the browser binary, add the path as attribute in your desiredCapabilities object.

for Firefox:

'firefox_binary': <path to binary>
//e.g. '/Applications/Firefox.app/Contents/MacOS/firefox'

for Chrome:

'chrome.binary': <path to binary>

for Opera:

'opera.binary': <path to binary>

for Safari:

'safari.binary': <path to binary>

logLevel

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

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
• 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)
• 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)
  Get the elements size. The element is found with a 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
• getSize(String css selector, Function callback)
  Gets the width and height for an object based on the css selector
• 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)
• 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)

• buttondown
• buttonup
• element
• elementIdAttribute
• elementIdClick
• elementDoubleClick
• elementIdCssProperty
• elementIdDisplayed
• elementIdLocation
• elementIdLocationInView
• elementIdName
• elementIdSize
• elementIdText
• elementIdValue
• elementIdSelected
• elements
• execute
• frame
• init
• moveto
• screenshot
• session
• status
• submit
• title
• url
• source
• window
• windowHandles
• 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