webdriverjs

Webdriver/selenium 2.0 javascript bindings for nodejs

This library is a webdriver module for nodejs. It makes it possible to write super easy selenium tests in your favorite BDD or TDD test framework.

Have a look at the many examples.

For news or announcements follow @webdriverjs on Twitter.

How to install it

npm install webdriverjs

Disclaimer

This is not the official WebdriverJS driver, for differences between this and the official driver, please take a look on this issue post.

Usage

webdriverjs implements most of selenium's JsonWireProtocol.

Make sure you have a running selenium standalone/grid/hub.

Or use selenium-standalone package to run one easily.

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

webdriverjs
    .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)

See helpers and protocol methods.

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. WebdriverJS 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">WebdriverJS</a>) query the text starting with an equal (=) sign. In this example use =WebdriverJS
• 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 WebdriverJS will cover more selector features like form selector (e.g. :password,:file etc) or positional selectors like :first or :nth.

Eventhandling

WebdriverJS 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 in NodeJS environment

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

Eventhandling on browser side

This is an experimental feature that helps you to listen on events within the browser. It is currently only supported in Chrome browser (other browser will eventually follow). To register an event call the addEventListener command. If an event gets invoked it returns almost the complete event object that got caught within the browser. Only the Window will be removed to avoid circular references. All objects from type HTMLElement will be replaced by their xPath. This will help you to query and identify this element with WebdriverJS.

Before you are able to use browser side eventhandling you need set the experimental flag on client initialization:

var client = WebdriverJS.remote({
    logLevel: 'verbose',
    experimental: true, // <-- enables browser side eventhandling
    desiredCapabilities: {
        browserName: 'chrome'
    }
});

After that you can use addEventListener to register events on one or multiple elements and removeEventListener to remove them.

Example

client
    .url('http://google.com')
    .addEventListener('dblclick','#hplogo', function(e) {
        console.log(e.target); // -> 'id("hplogo")'
        console.log(e.type); // -> 'dblclick'
        console.log(e.clientX, e.clientY); // -> 239 524
    })
    .doubleClick('#hplogo') // triggers event
    .end();

Again: this is still an experimental feature. Some events like hover will not be recorded by the browser. But click and custom events are working flawlessly.

Adding custom commands

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(cb) {
    this.url(function(err,urlResult) {
        this.getTitle(function(err,titleResult) {
            var specialResult = {url: urlResult.value, title: titleResult};
            cb(err,specialResult);
        })
    });
});

client
    .init()
    .url('http://www.github.com')
    .getUrlAndTitle(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 webdriverjs, 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

Webdriverjs supports

• Sauce Labs
• BrowserStack
• TestingBot

See the corresponding examples.

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

List of current implemented wire protocol bindings

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

• alertAccept
• alertDismiss
• alertText
• back
• buttonPress
• buttonDown
• buttonUp
• cookie
• cookieName
• doubleclick
• element
• elementIdAttribute
• elementIdClear
• elementIdClick
• elementIdCssProperty
• elementIdDisplayed
• elementIdLocation
• elementIdLocationInView
• elementIdName
• elementIdSize
• elementIdText
• elementIdValue
• elementIdSelected
• elements
• execute
• executeAsync
• file (undocumented protocol command)
• forward
• frame
• implicitWait
• init
• keys
• orientation
• moveto
• refresh
• screenshot
• session
• sessions
• source
• status
• submit
• timeouts
• title
• touchClick
• touchDoubleClick
• touchDown
• touchFlick
• touchFlickPrecise
• touchLongClick
• touchMove
• touchScroll
• touchSwipe
• touchTap
• touchUp
• url
• window
• windowHandle
• windowHandlePosition
• windowHandles
• windowHandleSize

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
• Vincent Voyer