A Grunt task for running WebDriver scripts in the Sauce Labs cloud.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



Build Status Dependency Status NPM version

Test Status

A Grunt task for running WebDriver scripts in the Sauce Labs cloud.

In addition to supporting custom scripts, standard scripts are provided for running javascript unit tests in Jasmine and Siesta Lite.

Inspired by the grunt-saucelabs plugin, this project aims to provide greater flexibility and support for custom WebDriver scripts, as well as the option to run tests locally.

Local Tests

Local tests are currently supported for Google Chrome and Internet Explorer. To run tests locally, ensure you have downloaded the appropriate ChromeDriver or InternetExplorerDriver server for your platform and made it available on your PATH environment variable.



var saucedriver = require('grunt-sauce-driver');

	saucedriver: {
		options: {
			username: 'saucelabs-user-name',
			key: 'saucelabs-key',
			tunneled: true,
			tags: ['example', 'sample'],
			browsers: [{
				browserName: 'opera'
		jasmine: {
			url: 'http://example.com/test/jasmine.html',
			script: saucedriver.jasmine
		siesta: {
			url: 'http://example.com/test/siesta.html',
			script: saucedriver.siesta
		custom: {
			url: 'http://example.com/test/custom.html',
			script: function(browser, options) {
				return (
					.then(function(el) {
						return browser.moveTo(el);
					.log('Test complete')


Basic Options

  • url : String Required

    The URL of the page to be tested.

  • script : Function Required

    The WebDriver script to run, either a custom function or one provided by grunt-sauce-driver. The function should accept the following parameters:

    • browser: The WebDriver browser object (using the promises API).
    • options: The Grunt options object.
  • browsers : Object[] Required

    An array of objects representing the browsers on which this test should run.

  • concurrency : Number Optional

    Number of concurrent browsers to test against. When running on Sauce Labs, check your account info for your maximum allowed concurrency. Defaults to 1.

  • slow : Boolean/Number Optional

    Adds a delay between each WebDriver action, to make tests easier to watch and debug. Can be specified either as a boolean flag, or a number of milliseconds to delay. If set to true, a default value of 500 milliseconds will be used. Defaults to false.

  • logging : Boolean Optional

    If enabled, logs information about the running script to the console. Defaults to true.

  • testTimeout : Number Optional

    Number of milliseconds to wait for javascript tests to complete on each page before timeout and failing the test. Default to 180000.

  • testInterval : Number Optional

    Number of milliseconds between each poll to see if a javascript test is complete. Defaults to 2000.

  • testReadyTimeout : Number Optional

    Number of milliseconds to wait for the test page to load. Defaults to 10000.

  • mirrorTestFailure : Boolean Optional

    When enabled, the grunt task will fail whenever any of the javascript tests fail. Otherwise, the task will fail only on WebDriver error (page load failure, test timeout, etc). Defaults to true.

  • ignoreFailure : Boolean Optional

    If enabled, specifies that the grunt task should always pass regardless of WebDriver errors or javascript test failures. (The task may still fail under certain catastrophic errors, however.) Defaults to false.

SauceLabs Options

  • username : String Optional

    The username that will be used to connect to Sauce Labs. Defaults to process.env.SAUCE_USERNAME.

  • key : String Optional

    The access key to provide when connecting Sauce Labs. For security purposes, don't hard-code this value in your Gruntfile. Instead, load it via local config file or environment variable. Defaults to process.env.SAUCE_ACCESS_KEY.

  • tunneled : Boolean Optional

    If enabled, uses a Sauce Connect tunnel when running tests on Sauce Labs. Defaults to true.

  • tunnelTimeout : Number Optional

    The connection timeout to use when initializing Sauce Connect, in seconds. Defaults to 120.

  • testname : String Optional

    The name of the test, to be displayed on the Sauce Labs dashboard. Defaults to "".

  • tags : String[] Optional

    An array of tags for this test, used when filtering the Sauce Labs dashboard. Defaults to [].

  • build : String Optional

    The build identifier to be associated with this test. Defaults to null.

Local Options

  • local : Boolean Optional

    If enabled, will run the current test on the local machine rather than Sauce Labs. Defaults to false.

  • autoclose : Boolean Optional

    When running local tests, determines whether the browser under test will be automatically closed after the test completes. Defaults to true.

  • driverPorts : Object Optional

    A map of browser names to port numbers, for use when communicating with the local WebDriver server. Defaults to { "chrome": 9515, "internet explorer": 5555 }.


This project is published under the terms of the MIT License.

Copyright © 2013 by Nat Burns.