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
andsources
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 thetestHelpers
property (or justrequire
them on Node). specs
:- Alias for
tests
environment
:browser
ornode
. 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 thatrootPath
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 berequire
‘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 berequire
‘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 berequire
‘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 asjQuery.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
andresources
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 ramp-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:`referee`, :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 theetag
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 setcontent
orfile
.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
. Whencontent
is set, you can not setcombine
orfile
. file
:- File to serve. When
file
is set, you can not setcombine
orcontent
.
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"