Buster extensions

Note: Extension hooks are still in their infancy. If you find it impossible to add some desired behavior through an extension, file an issue.

Extensions adds to or enhances the capabilities of Buster.JS at runtime. An extension will typically use regular Buster APIs to do their bidding. However, in order to hook you into the right places, Buster provides a series of extension points where you can add custom functionality. This page describes available extensions, as well as building extensions.

Available extensions

buster-syntax

This extension is unique in that it is bundled by default when you run tests in browsers. It verifies that all files are syntactically correct before sending them to the server for execution. This ensures good error messages and reduces browser hangs (especially in older less stable browsers).

buster-jstestdriver

Run test cases written for JsTestDriver with the Buster runner. The extension does not currently support :DOC style comments or async test cases.

Install

npm install buster-jstestdriver

Usage

Load in your configuration file:

var config = module.exports;
config["Browser tests"] = {
    rootPath: "../",
    sources: ["src/**/*.js"]
    tests: ["test/**/*.js"],
    extensions: [require("buster-jstestdriver")]
};

buster-amd

Use an AMD loader to test asynchronous modules.

Install

npm install buster-amd

Usage

Load in your configuration file:

var config = module.exports;
config["Browser tests"] = {
    rootPath: "../",
    sources: ["src/**/*.js"]
    tests: ["test/**/*.js"],
    extensions: [require("buster-amd")]
};

Configure

The AMD extension has one configuration option: a path mapper. The path mapper is an optional function that translate Buster.JS paths (which are absolute, e.g. /test/my-test.js) to AMD friendly module IDs. The default mapper converts /test/my-test.js to test/my-test, i.e. strips leading slash and file suffix. Use this option to e.g. use AMD loader plugins.

var config = module.exports;
config["Browser tests"] = {
    rootPath: "../",
    sources: ["src/**/*.js"]
    tests: ["test/**/*.js"],
    extensions: [require("buster-amd")],
    "buster-amd": {
        pathMapper: function (path) {
            return "plugin!" + path.replace(/^\//, "").replace(/\.js$/, "");
        }
    }
};

buster-lint

Incorporate linting (JsLint or JsHint) in your test runs. Optionally fail test runs if lint is found.

Install

npm install buster-lint

Usage

Load in your configuration file:

var config = module.exports;
config["Browser tests"] = {
    rootPath: "../",
    sources: ["src/**/*.js"]
    tests: ["test/**/*.js"],
    extensions: [require("buster-lint")]
};

Configure

Configuration options are those supported by the wonderful autolint tool by Magnar Sveen. In fact, if you're already using autolint, you can integrate it with Buster by simply requiring your existing configuration (assuming you're not still using pre-1.0 json config files):

var config = module.exports;
config["Browser tests"] = {
    rootPath: "../",
    sources: ["src/**/*.js"]
    tests: ["test/**/*.js"],
    extensions: [require("buster-lint")],
    "buster-lint": require("./autolint")
};

If you don't already have an autolint configuration, here's to get you started. All options are documented here.

var config = module.exports;
config["Browser tests"] = {
    rootPath: "../",
    sources: ["src/**/*.js"]
    tests: ["test/**/*.js"],
    extensions: [require("buster-lint")],
    "buster-lint": {
        linterOptions: {
            node: true
        },
        excludes: [
            "jquery",
            "underscore",
            "raphael"
       ]
    }
};

buster-lint on GitHub

Building extensions

A Buster.JS extension is an object that optionally exposes a create method, that will receive custom configuration, and one or more methods that implement an extension hook. The number of hooks is expected to increase in the near future.

var instance = ext.create([options]);

If provided, the create method is called with any custom configuration for the extension. Custom configuration is any value assigned to the property named after the extension in the configuration file, e.g.:

module.exports["Some tests"] = {
    extensions: [require("my-extension")],
    "my-extension": whatever
};

In order for this to work, the extension must export a name property, i.e. module.exports = { name: "my-extension", ... } in the case above. Although you don't explicitly have to, it's good practice to name the extension after it's package name.

The create method is not required. If it's not provided, the extension will not receive its custom configuration.

Hook: configure

The configure hook allows extensions to manipulate resource sets assigned to a test run. Resource sets contain all files and other resources required for a test run. You can use this hook to modify only sources, only tests, framework resources, everything or any other combination. Read the documentation for buster-configuration to understand how files are loaded and how you can hook into that process.

To implement this hook, simply provide a configure method on your extension object. The following example adds a resource to the framework group:

module.exports = {
    create: function (options) {
        var instance = Object.create(this);
        instance.options = options;
        return instance;
    },
    configure: function (group) {
        group.on("load:framework", function (resourceSet) {
            resourceSet.addResource({
                path: "/oh-yeah.js",
                content: "buster.log('Extension calling!');"
            });
        });
    }
};

Hook: beforeRun

TODO