buster-configuration

Module:
require("buster-configuration");
In the browser:
N/A (Node only)

The Buster configuration file (typically named buster.js) helps Buster to 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 which tests to run, in which environment (Node or browser) 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.

A simple configuration file

At its very simplest, a configuration file merely specifies the environment and which 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", "!test/**/*integration-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. To exclude files you just need to prepend a ! as you can see in the second pattern of the tests property. In the example that pattern prevents the integration tests to be run.

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 Manually starting test run 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 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"
    }
};

The Configuration API

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

Configuration

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"]
};

Example:

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"]
});
config.groups

An array consisting of all the Configuration group.

config.resolveGroups()
config.resolveGroups(function (err, groups) {});

Resolves all of the groups. See configGroup.resolve().

config.addGroup()
config.addGroup(name, groupData);

Adds a new group.

config.filterEnv()
config.filterEnv(envName);

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

config.filterGroup()
config.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.

configGroup.resourceSet

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

This property is undefined until configGroup.resolve() is called.

configGroup.resolve()
var promise = configGroup.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.

configGroup.setupFrameworkResources()
  configGroup.setupFrameworkResources();
Adds all the framework resources such as :ref:`buster-assertions`,
:ref:`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).

Example:

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");
});

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"