Skip to end of metadata
Go to start of metadata

The packages, scripts, and information in this page (and it's children) are either deprecated or managed by a third party

Grunt is a task-based command line build tool, based on node.js, for JavaScript projects. Grunt-Saucelabs is a Grunt task that lets you run your JavaScript unit tests with browsers in the Sauce Labs automated testing cloud. This topic explains how to set up Grunt-Saucelabs to run tests with your favorite testing framework. 


  • You need to have node.js installed
  • You need to have Grunt installed


The GitHub repository for grunt-saucelabs contains example files including sample GruntFile.js files, package.json files, and HTML test pages for frameworks including YUI, Mocha, Jasmine, QUnit, and custom frameworks. 

Set Up

Grunt-saucelabs is available as a node package. To install, run this command.

npm install grunt-saucelabs

To use the task in grunt.js, load the npmTask.


It can also be included as a devDependency in package.json in your node project, as described in the next section. 


There are two main files you need to configure to use your testing framework with grunt-saucelabs, package.json and GruntFile.js.

The package.json File

The package.json file contains meta-data information about your project. You can find full documentation about how to write this file on the website, but for using grunt-saucelabs with your testing framework, the most important section is the devDependencies, which is used to load the dependencies for your project. You should set up this section of your file like this:

  "devDependencies": {
    "grunt": "^0.4.5",
    "grunt-contrib-connect": "^0.7.1",
    "grunt-saucelabs": "*"

The GruntFile.js file will load the devDependencies from package.json, so it's important to make sure you have this section set up correctly in order to run grunt-saucelabs. 

The GruntFile.js File

The GruntFile.js file is where all the action happens. It starts up a web server and lets Sauce Connect access your tests on a localhost port, sets the browser and operating system configurations for your test, and lets you set the options for your test such as the URL of your test page, the name of the test, tags, and other Sauce Labs job settings. There are four sections in this file:

  1. var browsers where you set the browsers and operating systems you want to test against.
  2. The grunt.initConfig section that sets up the Sauce Connect connection to localhost:9999.

    Setting localhost Ports

    This example file sets Sauce Connect to use port 9999, but it can also connect to any other port on localhost. 

  3. The options section where you set the options for your test.

    Grunt Options

    The options object was introduced in grunt-saucelabs-* version 4.0.0 to be compatible with grunt@0.4.0. The topic Parameters for Grunt-Saucelabs Tasks includes a full list of options that you can set up. Check out Best Practice: Use Environment Variables for Authentication Credentials for information on setting up your username and key as environment variables. 

  4. grunt.registerTask, where you define the task alias that you will call from the command line. In the Sample GruntFile.js files this alias is default, and it runs the tasks connect and the task for the specified testing framework. For example, in the  GruntFile.js for Mocha, the second task is named saucelabs-mocha. The Grunt documentation has more information on defining tasks and arguments for the task alias. 

You can find example GruntFile.js files for each of the testing frameworks in Sample GruntFile.js Files, but they are all essentially the same. This example is for Mocha. Check out the official Grunt documentation on the GruntFile.js for a complete explanation of how to set up your own files.

You can also clone this script directly from our GitHub repo

module.exports = function (grunt) {
  var browsers = [{
    browserName: 'firefox',
    version: '19',
    platform: 'XP'
  }, {
    browserName: 'googlechrome',
    platform: 'XP'
  }, {
    browserName: 'googlechrome',
    platform: 'linux'
  }, {
    browserName: 'internet explorer',
    platform: 'WIN8',
    version: '10'
  }, {
    browserName: 'internet explorer',
    platform: 'VISTA',
    version: '9'
    pkg: grunt.file.readJSON('package.json'),
    connect: {
      server: {
        options: {
          base: '',
         port: 9999
    'saucelabs-mocha': {
      all: {
        options: {
          username: 'saucelabs-user-name', // if not provided it'll default to ENV SAUCE_USERNAME (if applicable)
          key: 'saucelabs-key', // if not provided it'll default to ENV SAUCE_ACCESS_KEY (if applicable)
          urls: [
          browsers: browsers,
          build: process.env.TRAVIS_JOB_ID,
          testname: 'mocha tests',
          throttled: 3,
          sauceConfig: {
            'video-upload-on-pass': false
    watch: {}
  grunt.registerTask('default', ['connect', 'saucelabs-mocha']);

Incorporating Your JavaScript Unit Tests into a Continuous Integration Process

In the example options section, you  can see that the build option is set to process.env.TRAVIS_JOB_ID, which enables these test results to be incorporated into a TravisCI continuous build process. Check out the topics under Using Sauce Labs with Continuous Integration Platforms to see how to use Sauce with CI platforms like Jenkins and Bamboo.

Finding Your Username and Access Key

You can find your Sauce Labs username and access key in the User Profile > User Settings section of your Sauce Labs dashboard.

Running the Task

With everything set up, you can run your task from the command line with a single command that references your task alias (default in the example file).

grunt default

This will start up the Web server, and you can then access your tests at the page referenced as the URL in the options section of your GruntFile.js to see how they have executed against the browsers you defined. 

  • No labels

1 Comment

  1. Anonymous

    Don't know how to help documentation fix. But in the GruntFile.js it's mentioned letting Sauce Connect to access localhost:9999. I think it is not port specific, so you might want to drop the port 9999.