Buster.JS Configuration

Version
0.2.0 (2011-12-05)
Module
require("buster-configuration");
In the browser
N/A (Node only)

The Buster configuration file (typically named buster.js) helps Buster understand how to automate your test runs. You can run tests on Node without the configuration file (i.e. with node my-test.js), but it is required when using buster test to run tests.

A configuration file can contain one or more test run configurations, called "groups". A group specifies what tests to run, in what environment (Node or browsers for now, possibly others later) to run them, and can provide certain configuration options to the test runner.

The configuration file is focused on how to automate test runs. It is designed specifically for project-specific settings only. User-specific settings, like whether or not to use colors, what reporter to use and so on, is not part of this configuration. Refer to the customizing page for more on how to customize Buster for developer happiness.

A simple configuration file

At its very simplest, a configuration file merely states what resources to load. For browser tests, this includes libraries and sources, while for Node you only need to specify tests (as typically they require their own sources).

var config = module.exports;
config["Browser tests"] = {
    environment: "browser",
    libs: ["lib/**/*.js"],
    sources: ["src/core.js", "src/**/*.js"],
    tests: ["test/**/*.js"]
};

The configuration file is a JavaScript file. In fact, it is a Node module, as you might have guessed from the first line. The first line is pure vanity by the way. We think "config" reads better throughout the file than "exports".

This configuration specifies a browser run (as seen from the environment property). It will cause all files in lib to be loaded first (using script tags), then all files in src, then all files in tests. Note how we specified src/core.js separately. Buster resolves these duplications, and you typically want to specify some files manually if ordering is important.

Configuration properties

To avoid wasting your time on typos and misunderstandings, Buster will fiercefully throw errors if you feed it configuration properties it does not recognize. The following is a list of all the properties Buster recognizes.

tests
The test files to load and run. Value is an array of file names and/or glob patterns. Files are loaded in the order provided. Like the libs and sources properties, it may include duplicates. However, it is highly recommended that your tests are not order dependent. Test helpers and similar utilities should be loaded with the testHelpers property (or just require them on Node).
specs
Alias for tests
environment
browser or node. The browser environment allows you to run tests from the command-line and have them executed in one or more browsers through the server component of Buster.JS. Refer to the browser testing page.
env
Alias for environment.
rootPath
By default, Buster will resolve file paths in the configuration file relative to the directory in which the configuration file is found. Setting a rootPath allows you to change the base of path lookups. Note that rootPath itself is also resolved relative to the directory where the configuration file is found.

The following properties only apply to the browser environment.

testHelpers
Library files to load in script tags in the browser. This setting should normally not be used for node runs. If it is, files will be require'd. Value is an array of file names and/or glob patterns. Files are loaded in the order provided. It may include duplicates, e.g. ["test/lib/core.js", "test/lib/**/*.js"], files will only be loaded once. testHelpers are loaded after libraries and sources, but before tests.
specHelpers
Alias for testHelpers
libs
Library files to load in script tags in the browser. This setting should normally not be used for node runs. If it is, files will be require'd. Value is an array of file names and/or glob patterns. Files are loaded in the order provided. It may include duplicates, e.g. ["lib/core.js", "lib/**/*.js"], files will only be loaded once. Libraries are loaded before anything else.
deps
Alias for libs
sources
Source files to load in script tags in the browser. This setting should normally not be used for node runs. If it is, files will be require'd. Value is an array of file names and/or glob patterns. Files are loaded in the order provided. It may include duplicates, e.g. ["src/core.js", "src/**/*.js"], files will only be loaded once. Sources are loaded after libraries and before test libraries and tests.
src
Alias for sources
resources

Additional resources that will be made available for test runs, but not explicitly loaded. Value is an array of resources. Resources are served from a context path on the server. To request a resource in your test runs, you need to scope resource paths with buster.env.contextPath. The resource /some/cookies.json can be requested as jQuery.get(buster.env.contextPath + "/some/cookies.json");

A resource can be a string, i.e. a glob pattern/file name, or an object. Objects may specify resources that are inlined content to be served as a file, a combination of other resources (optionally minified) or a proxy to another web server. See resource.

autoRun
Only applies to browser runs. When set to false, Buster will not run tests immediately after loading all files. Refer to starting test runs manually for more information.
extends

Takes a group name, and loads all the configuration from that group as the basis for this group. Content in libs, sources, tests and resources will be appended to the content from the original group. Other options will default to the value from the referenced group unless the group itself specifies a value.

var config = module.exports;
config["Shared tests"] = {
    tests: ["test/shared/**/*.js"]
};
config["Browser defaults"] = {
    extends: "Shared tests",
    environment: "browser",
    libs: ["lib/**.js"],
    extensions: ["buster-amd"]
};
config["Node tests"] = {
    extends: "Shared tests",
    tests: ["test/server/**.js"]
};
config["Browser unit tests"] = {
    extends: "Browser defaults",
    tests: ["test/browser/unit/**.js"]
};
config["Browser integration tests"] = {
    extends: "Browser defaults",
    tests: ["test/browser/integration/**.js"]
};

As you can see, the extends property makes it possible to greatly reduce the duplication in configuration files if you use multiple groups. It also encourages the use of multiple groups for multiple test profiles.

extensions

Extensions to load at runtime. The value is an array of extension objects which will be pinged when the configuration is loaded. If you are interested in developing extensions, check out events and the extensions page (which also lists known extensions).

To configure an extension, add settings under the name of the extension:

config["Browser integration tests"] = {
    extensions: [require("buster-jstestdriver"), require("buster-coverage")],
    "buster-coverage": {
        "outputDirectory": "coverage"
    }
};

API Documentation

The following is only relevant if you plan on working with the Buster.JS configuration file programatically.

The Configuration API

The configuration object allows you to work with a collection of groups, possibly read from a file.

// /tmp/buster.js:
// var config = exports;
//
// exports["Browser tests"] = {
//     environment: "browser",
//     sources: ["client/src/*.js"],
//     tests: ["client/test/*.js"]
// };
//
// exports["Server tests"] = {
//     environment: "node",
//     tests: ["server/test/*.js"]
// };
var configuration = require("buster-configuration");
var config = configuration.create();
config.loadFile("/tmp/buster.js");
config.filterEnv("browser");
config.filterGroup(/browser/);
config.resolveGroups(function (err, groups) {
    // groups[0].resourceSet.load ==
    // ["/client/src/todo-list.js", "/client/test/todo-list-test.js"]
});

conf.groups

An array consisting of all the groups.

conf.resolveGroups(function (err, groups) {})

Resolves all of the groups. See group-resolve.

conf.addGroup(name, groupData)

Adds a new group.

conf.filterEnv(envName)

Permanently removes all groups that aren't of envName's environment. The available environments are "browser" and "node".

conf.filterGroup(regex)

Permanently filters out groups which name doesn't match the regex. If the name provided is a string, it will be converted to a regular expression through the RegExp constructor.

Configuration group

The individual object in the configuration's list of groups.

grp.resourceSet

A buster-resources resource set, containing resources for all the objects in the config group.

This property is undefined until resolve is called.

var promise = grp.resolve()

Creates the resource set by performing all globs and file system operations neccesary to build up the full resource set for the config group. The group is pretty much useless until this method is called. It won't even have a resourceSet property defined.

The promise is resolved with the resourceSet object when the group has been fully loaded.

grp.setupFrameworkResources()

Adds all the framework resources such as buster-assertions, buster-test and Sinon to the resource set for the group. These resources are prepended so they appear before the files of the config group, so that everything is loaded beforehand.

NOTE: This method is going away in favor of generic hooks. Buster will load its "framework resources" as extensions using these hooks (work in progress).

grp.resolve().then(function () {
    // Load custom-thing before the files in the config group.
    grp.resourceSet.addResource("/custom-thing", {...});
    grp.resourceSet.prependToLoad("/custom-thing");
    // Load framework files, will be prepended so it loads before
    // the stuff added above
    grp.setupFrameworkResources();
    // If you wish, you can load stuff before the framework resources.
    // You probably don't need to do that though.
    grp.resourceSet.addResource("/something-else", {...});
    grp.prependToLoad("/something-else");
});

Supporting objects

Resource

A "resource" is something exposed on the server when you run browser tests using buster-server and buster-test. Exposing the resource /something.json allows you to request it in your tests using e.g. jQuery.ajax({ url: "something.json" });.

Content/file resources

etag
The etag is used by Buster to cache resources on the server. If the etag has not changed since the last time the resource was uploaded on the server, it will use the cached version. This improves the performance, especially if only one or two out of potentially tens or hundreds of files changed since the last run.
combine
Takes an array of resources to combine into one. Useful to run tests against a combined build of your project:
config["Browser build tests"] = {
    environment: "browser",
    libs: ["lib/**.js"],
    resources: [
        "src/**.js",
        { path: "/mylib.min.js",
          combine: ["src/base.js", "src/dom.js"] }
    ],
    sources: ["/mylib.min.js"],
    tests: ["test/**.js"]
};

The above configuration will run tests against a combined and minified bundle of your application. Note that the combine property unfortunately does not understand globs (yet).

When combine is set, you can not set content or file.

headers
Custom headers to serve the resource with. Content is an object where the property name is the header name, and the value is the header value.
content
Contents to serve as a string or a Buffer. When content is set, you can not set combine or file.
file
File to serve. When file is set, you can not set combine or content.

Proxy resources

backend
Another HTTP server that will handle the requests for path.
config["Browser integration tests"] = {
    resources: [
        { path: "/todo-items", backend: "http://localhost:8000/todo/todo-items" }
    ]
};

With this configuration, a request to buster.env.contextPath + "/todo-items/2" would be proxyed to "http://localhost:8000/todo/todo-items/2"