sauce-tap-runner

Run TAP unit tests in the browser using Sauce Labs hosted browsers. This helper takes care of setting up the tunnel to Sauce Labs servers and provides the test page and TAP parsing. It will also set the test result status on Sauce Labs so that you can use the awesome status images. (Note that you must also set the build field on the desired capabilities object for the images to work.)

Example

var Runner = require('sauce-tap-runner'),
    browserify = require('browserify'),
    async = require('async');

var tests = new Runner(sauceUser, sauceKey),
    // Browserify is not required, can use either a string or stream of JS code
    src = browserify().add('tests.js').bundle();

async.series([run('chrome'), run('firefox')], closeTests);

function run(browser) {
    // Return a function that when called will run tests in the specified
    // browser

    return function(callback) {
        tests.run(src, { browserName: browser }, function(err, results) {
            if (err) {
                return callback(err);
            }

            console.log(results);
            callback();
        });
    };
}

function closeTests(err) {
    if (err) {
        console.error(err);
    } else {
        console.log('Tests completed');
    }

    tests.close(function() {
        // Runner is closed
    });
}

Reference

new Runner(sauceUser, sauceKey)

Creates a new test runner. A single test runner maintains a single Sauce Connect tunnel. Using a single runner for all your tests will improve speed as it takes time to setup the tunnel. A tunnel will only be created when you run the tests.

sauceUser and sauceKey must be your Sauce Labs username and key.

#run(src, desiredCapabilities, [options], [callback])

Runs the tests in a new browser. It will create a new WebDriver connection to the browser and run the JS tests provided. It is not able to run tests in parallel; you must wait till one test is completed before running the next.

src can be a string or stream containing the JS code for the tests. The tests should output TAP-compatible results to the browser console using console.log.

desiredCapabilities is an object that will be passed to the Sauce Labs server when creating the browser. See the docs for information on what options you can provide. The username and password is automatically set.

options is an optional object containing the options for the test runner. See the wd-tap-runner docs for valid options.

callback is an optional function that will be called with the error if any occurred and the test results. Note that failed tests are not considered errors; they will be reported in the results. The results are the same as for wd-tap-runner.

#close([callback])

Closes the Sauce Connect tunnel. Will call callback when everything is closed. All tests must be finished before closing.

Events

Runner inherits from EventEmitter. It will emit the following events:

• tunnel-connect: Starting to connect the Sauce Connect tunnel
• tunnel(tunnel): The Sauce Connect tunnel has been connected
• tunnel-error(err): An error occurred when connecting the Sauce Connect tunnel
• browser(browser): Successfully connected to a new browser
• results(results): A test run has finished
• close: The runner has been closed