Find file
Fetching contributors…
Cannot retrieve contributors at this time
222 lines (178 sloc) 9.97 KB


Selenium-grid has special needs and therefore a driver is required. Wd being the most active webdriver library in node.js, we decided to rely on it for low level driver.

Provided driver is promised style, so it is possible to enqueue actions and to execute commands.


Commands are run immediately against the current browser. It requires the grid to be initialized. Usualy you want to use this in a then statement.

If an error happens, an error is thrown.


method callback description
`status(cb)` cb(statusCode) read current request status. Map the [JSONWireProtocol status](


session, altSessionCapabilities, sessionCapabilities, setPageLoadTimeout, setAsyncScriptTimeout, setImplicitWaitTimeout wraps the native WD methods.

Script evaluation

method callback description
`execute(script[, args], cb)` cb(result) execute method and return results. Map the [JSONWireProtocol execute](
`safeExecute(script[, args], cb)` cb(result) execute method and always return results. Map the [JSONWireProtocol execute](
`eval(script, cb)` cb(result) execute script and return results. Map the [JSONWireProtocol execute](
`safeEval(script, cb)` cb(result) execute script and always return results. Map the [JSONWireProtocol execute](
`executeAsync(script, cb)` cb(result) execute script and return results. Map the [JSONWireProtocol execute](
`safeExecuteAsync(script, cb)`| cb(result) execute script and always return results. Map the [JSONWireProtocol execute](
### Window manipulation
method callback description
`frame(frameRef, cb)` cb() Set focus to another frame Map the [JSONWireProtocol frame](
`window(name, cb)` cb() Set focus to another window. Map the [JSONWireProtocol window](
`windowHandle(cb)` cb(handle) Retrieve the current window handle.
`windowHandles(cb)` cb(arrayOfHandles) Retrieve the list of all window handles available to the session.
`windowSize([handle, ]width, height, cb)` cb() Map the [JSONWireProtocol size](
`setWindowSize([handle,] cb)` cb() Map the [JSONWireProtocol size ](
`getWindowSize([handle,] cb)` cb(size) Map the [JSONWireProtocol size](
`setWindowPosition(x, y, [handle,] cb)` cb() Map the [JSONWireProtocol position](
`getWindowPosition([handle,] cb)` cb(position) Map the [JSONWireProtocol position](
`maximize([handle,] cb)` cb() Maximize specified window. Map the [JSONWireProtocol maximize](
`forward(cb)` cb()
`back(cb)` cb()
`refresh(cb)` cb()
`close(cb)` cb() close session
`moveTo(element[, offsetx, offsety], cb` cb() Move the mouse by an offset of the specificed element. Map the [JSONWireProtocol moveto](

To be documented

For now, please refer to the wd mapping documentation.

'allCookies', 'setCookie', 'deleteAllCookies', 'deleteCookie', 'source', 'url', 'title', 'active', 'keys', 'getOrientation', 'alertText', 'alertKeys', 'acceptAlert', 'dismissAlert', 'buttonDown', 'buttonUp', 'flick', 'setLocalStorageKey', 'clearLocalStorage', 'getLocalStorageKey', 'removeLocalStorageKey', 'newWindow', 'windowName', 'getPageIndex', 'uploadFile', 'takeScreenshot', 'waitForCondition', 'waitForConditionInBrowser'

'clickHere', 'doubleClickHere', 'buttonUpHere', 'buttonDownHere'

Deferred commands

Commands are also accessible as deferred methods, this means you can enqueue scenario steps by prefixing the command with then.

If you don't provide any callback argument, scenario will continue as soon as the commands is over, otherwise you have to call the next method to resume scenario.

    .thenStatus(function (status, next) {
        if (200 === status) {
            this.log('Google is up');
        // call next manualy
    // next will be called automaticly
    .thenLog('executed when upload is done.');

Scenarios API

execute immediately

It is possible to interact with elements very simply using this methods:

method callback description
click(selector, [cb]) cb() click on element
doubleClick(selector, [cb]) cb() double click on element
sendKeys(selector, keys, [cb]) cb() Send a sequence of key strokes to element
submit(selector, [cb]) cb() submit form
clear(selector, [cb]) cb() clear input element
text(selector, keys, [cb]) cb(text) return element's text
isVisible(selector, [cb]) cb(result) is the element visible
isSelected(selector, [cb]) cb(result) is the element selected
isEnabled(selector, [cb]) cb(result) is the element enabled
isDisplayed(selector, [cb]) cb(result) is the element displayed
getAttribute(selector, attrName, [cb]) cb(value) retrieve an attribute for element
getLocation(selector, [cb]) cb(location) return location for element
getSize(selector, [cb]) cb(size) read element's size
getComputedCss(selector, [cb]) cb(css) returns css for element
waitForElement(selector, timeout, [cb]) cb() wait for an element to be in page
waitForVisible(selector, timeout, [cb]) cb() wait for an element to be visible
fill(selector, values[, validate] [, cb]) cb() fill the form with values

Example of form filling:

    .fill('form', {
        'input[type=text]': 'some text',
        'textarea': 'some long text',
        'input[type=file]': '/home/themouette/some/file.txt',
        'input[type=radio]': 'Mr'

// or, using fluid interface

browser.thenFill('selector', {'.name': 'selenium'});

Scenario as deferred

You can chain commands using the deferred api, using following methods:

thenClick thenDoubleClick thenText thenSendKeys thenPressKeys thenSubmit thenClear thenIsVisible(selector, [cb]) thenIsSelected thenIsEnabled thenIsDisplayed thenGetAttribute thenGetLocation thenGetSize thenGetComputedCss

thenWaitForElement(selector, timeout, [cb]) thenWaitForVisible(selector, timeout, [cb])

thenFill(selector, values[, validate] [, cb])

Omitting the callback will call next step directly, but if you provide one, you MUST call the next method, provided as the last argument, whatever happens.

    // will call next automaticly
    // will defer for 1 second
    .thenClick('[name=q]', function (next) {
        setTimeout(next, 1000);
    // will block execution
    .thenClick('[name=q]', function (next) {})

Note on selectors

A selector can either be a css selector or an xpath selector using the require('selenium-grid').xpath method:

var x = require('selenium-grid').xpath;

    .thenGetSize(x('//input'), function (size, next) {

Error Handling

Any error or exception occuring in the process quit the browser and is forwarded to the reporter.