test/utils

We are planning to deprecate the use by Firefox add-ons of the techniques described in this document.

Don't use these techniques to develop new add-ons. Use WebExtensions instead.

If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions instead.

Add-ons developed using these techniques might not work with multiprocess Firefox (e10s), which is already the default in Firefox Nightly and Firefox Developer Edition, and will soon be the default in Beta and Release versions of Firefox. We have documentation on making your add-ons multiprocess-compatible, but it will be more future-proof for you to migrate to WebExtensions.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

Unstable

Helper methods used in the CommonJS Unit Testing suite.

Usage

Before and After

Helper functions before() and after() are available for running a function before or after each test in a suite. They're useful when you need to guarantee a particular state before running a test, and to clean up after your test.

let { before, after } = require('sdk/test/utils');
let { search } = require('sdk/places/bookmarks');

exports.testCountBookmarks = function (assert, done) {
  search().on('end', function (results) {
    assert.equal(results, 0, 'should be no bookmarks');
    done();
  });
};

before(exports, function (name, assert) {
  removeAllBookmarks();
});

require('sdk/test').run(exports);

Both before and after may be asynchronous. To make them asynchronous, pass a third argument done, which is a function to call when you have finished:

let { before, after } = require('sdk/test/utils');
let { search } = require('sdk/places/bookmarks');

exports.testCountBookmarks = function (assert, done) {
  search().on('end', function (results) {
    assert.equal(results, 0, 'should be no bookmarks');
    done();
  });
};

before(exports, function (name, assert, done) {
  removeAllBookmarksAsync(function () {
    done();
  });
});

require('sdk/test').run(exports);

Globals

Functions

before(exports, beforeFn)

Runs beforeFn before each test in the file. May be asynchronous if beforeFn accepts a third argument, which is a callback.

Parameters

exports : Object
A test file's exports object

beforeFn : Function
The function to be called before each test. It has two arguments, or three if it is asynchronous:

  • the first argument is the test's name as a String.
  • the second argument is the assert object for the test.
  • the third, optional, argument is a callback. If the callback is defined, then the beforeFn is considered asynchronous, and the callback must be invoked before the test runs.

after(exports, afterFn)

Runs afterFn after each test in the file. May be asynchronous if afterFn accepts a third argument, which is a callback.

Parameters

exports : Object
A test file's exports object

afterFn : Function
The function to be called after each test. It has two arguments, or three if it is asynchronous:

  • the first argument is the test's name as a String.
  • the second argument is the assert object for the test.
  • the third, optional, argument is a callback. If the callback is defined, then the afterFn is considered asynchronous, and the callback must be invoked before the next test runs.

waitUntil(predicate, interval)

waitUntil returns a promise that resolves upon the predicate returning a truthy value, which is called every interval milliseconds.

Parameters

predicate : Function
A function that gets called every interval milliseconds to determine if the promise should be resolved.

interval : Number
The frequency in milliseconds to execute predicate. Defaults to 10.

Returns

Promise : waitUntil returns a promise that becomes resolved once the predicate returns a truthy value. The promise cannot be rejected.

Document Tags and Contributors

 Contributors to this page: wbamberg
 Last updated by: wbamberg,