configuration.html

<div id="doc-nav"></div>
<div id="doc-content">
  <h1>Buster.JS Configuration</h1>
  <dl>
    <dt>Version</dt>
    <dd>0.2.0 <span class="date">(2011-12-05)</span>
    </dd>
    <dt>Module</dt>
    <dd><code>require("buster-configuration");</code></dd>
    <dt>In the browser</dt>
    <dd>N/A (Node only)</dd>
  </dl>
  <p>
    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 <kbd>node my-test.js</kbd>), but it is
    required when using <kbd>buster test</kbd> to run tests.
  </p>
  <p>
    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.
  </p>
  <p>
    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
    <a href="/docs/customizing/">customizing page</a> for more on how to
    customize Buster for developer happiness.
  </p>
  <h3>A simple configuration file</h3>
  <p>
    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 <code>require</code> their
    own sources).
  </p>
  <pre><code>var config = module.exports;

config["Browser tests"] = {
    environment: "browser",
    libs: ["lib/**/*.js"],
    sources: ["src/core.js", "src/**/*.js"],
    tests: ["test/**/*.js"]
};</code></pre>
  <p>
    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".
  </p>
  <p>
    This configuration specifies a browser run (as seen from the
    <code>environment</code> property). It will cause all files in <kbd>lib</kbd>
    to be loaded first (using <code>script</code> tags), then all files
    in <code>src</code>, then all files in <code>tests</code>.
    Note how we specified <code>src/core.js</code> separately. Buster resolves
    these duplications, and you typically want to specify some files manually if
    ordering is important.
  </p>
  <div class="section">
    <h2 id="properties">Configuration properties</h2>
    <p>
      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.
    </p>
    <dl>
      <dt><code>tests</code></dt>
      <dd>
        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
        <code>libs</code> and <code>sources</code> 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 <code>testLibs</code> property (or just <code>require</code> them on
        Node).
      </dd>
      <dt><code>specs</code></dt>
      <dd>
        Alias for <code>tests</code>
      </dd>
      <dt><code>environment</code></dt>
      <dd>
        <code>browser</code> or <code>node</code>. 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
        <a href="/docs/browser-testing/">browser testing page</a>.
      </dd>
      <dt><code>env</code></dt>
      <dd>
        Alias for <code>environment</code>.
      </dd>
      <dt><code>rootPath</code></dt>
      <dd>
        By default, Buster will resolve file paths in the configuration file
        relative to the directory in which the configuration file is
        found. Setting a <code>rootPath</code> allows you to change the base of
        path lookups. Note that <code>rootPath</code> itself is also resolved
        relative to the directory where the configuration file is found.
      </dd>
    </dl>
    <p>
      The following properties only apply to the browser environment.
    </p>
    <dl>
      <dt><code>testLibs</code></dt>
      <dd>
        Library files to load in <code>script</code> tags in the browser. This
        setting should normally not be used for node runs. If it is, files will be
        <code>require</code>'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. <code>["test/lib/core.js", "test/lib/**/*.js"]</code>,
        files will only be loaded once. <code>testLibs</code> are loaded after
        libraries and sources, but before tests.
      </dd>
      <dt><code>specLibs</code></dt>
      <dd>
        Alias for <code>testLibs</code>
      </dd>
      <dt><code>libs</code></dt>
      <dd>
        Library files to load in <code>script</code> tags in the browser. This
        setting should normally not be used for node runs. If it is, files will be
        <code>require</code>'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. <code>["lib/core.js", "lib/**/*.js"]</code>, files will
        only be loaded once. Libraries are loaded before anything else.
      </dd>
      <dt><code>deps</code></dt>
      <dd>
        Alias for <code>libs</code>
      </dd>
      <dt><code>sources</code></dt>
      <dd>
        Source files to load in <code>script</code> tags in the browser. This
        setting should normally not be used for node runs. If it is, files will be
        <code>require</code>'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. <code>["src/core.js", "src/**/*.js"]</code>, files will
        only be loaded once. Sources are loaded after libraries and before test
        libraries and tests.
      </dd>
      <dt><code>src</code></dt>
      <dd>
        Alias for <code>sources</code>
      </dd>
      <dt><code>resources</code></dt>
      <dd>
        <p>
          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 <code>buster.env.path</code>.
          The resource <code>/some/cookies.json</code> can be requested as
          <code>jQuery.get(buster.env.path + "/some/cookies.json");</code>
        </p>
        <p>
          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 <a href="#&lt;code&gt;resource&lt;/code&gt;">resource</a>.
        </p>
      </dd>
      <dt><code>server</code></dt>
      <dd>
        The server to run the group on, e.g. <code>"http://localhost:1919"</code>,
        <code>"localhost:8978"</code> or <code>"ci.myplace:8080"</code>.
      </dd>
      <dt><code>autoRun</code></dt>
      <dd>
        Only applies to browser runs. When set to <code>false</code>, Buster will
        not run tests immediately after loading all files.
        Refer to <a href="/docs/starting-testrun-manually/">starting
          test runs manually</a> for more information.
      </dd>
      <dt><code>extends</code></dt>
      <dd>
        <p>
          Takes a group name, and loads all the configuration from that group as the
          basis for this group. Content in <code>libs</code>, <code>sources</code>,
          <code>tests</code> and <code>resources</code> 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.
        </p>
        <pre><code>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"]
};</code></pre>
        <p>
          As you can see, the <code>extends</code> 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.
        </p>
      </dd>
      <dt><code>extensions</code></dt>
      <dd>
        <p>
          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 <a href="/#events">events</a> and the
          <a href="../extensions/">extensions page</a> (which also
          lists known extensions).
        </p>
        <p>
          To configure an extension, add settings under the name of the
          extension:
        </p>
        <pre><code>config["Browser integration tests"] = {
    extensions: [require("buster-jstestdriver"), require("buster-coverage")],
    "buster-coverage": {
        "outputDirectory": "coverage"
    }
};</code></pre>
      </dd>
    </dl>
  </div>
  <div class="section">
    <h2>API Documentation</h2>
    <p>
      The following is only relevant if you plan on working with the Buster.JS
      configuration file programatically.
    </p>
    <h2>The Configuration API</h2>
    <p>
      The <code>configuration</code> object allows you to work with a collection
      of groups, possibly read from a file.
    </p>
    <pre><code>// /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"]
});
</code></pre>
    <h3><code>conf.groups</code></h3>
    <p>
      An array consisting of all the <a href="#group">groups</a>.
    </p>
    <h3><code>conf.resolveGroups(function (err, groups) {})</code></h3>
    <p>Resolves all of the groups. See <a href="#group-resolve">group-resolve</a>.</p>
    <h3><code>conf.addGroup(name, groupData)</code></h3>
    <p>Adds a new group.</p>
    <h3><code>conf.filterEnv(envName)</code></h3>
    <p>
      Permanently removes all groups that aren't of <code>envName</code>'s
      environment. The available environments are <code>"browser"</code>
      and <code>"node"</code>.
    </p>
    <h3><code>conf.filterGroup(regex)</code></h3>
    <p>
      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 <code>RegExp</code> constructor.
    </p>
  </div>
  <div class="section">
    <h2 id="group">Configuration group</h2>
    <p>The individual object in the configuration's list of groups.</p>
    <h3 id="group-resource-set"><code>grp.resourceSet</code></h3>
    <p>
      A <a href="/docs/resources/">buster-resources</a> resource set, containing resources for all the
      objects in the config group.
    </p>
    <p>
      This property is undefined until <a href="#group-resolve">resolve</a>
      is called.
    </p>
    <h3 id="group-resolve">var promise = grp.resolve()</h3>
    <p>
      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 <code>resourceSet</code> property defined.
    </p>
    <p>
      The promise is resolved with the <code>resourceSet</code> object when the
      group has been fully loaded.
    </p>
    <h3 id="group-setup-framework">grp.setupFrameworkResources()</h3>
    <p>
      Adds all the framework resources such
      as <a href="/docs/assertions/">buster-assertions</a>,
      <a href="/docs/test/">buster-test</a>
      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.
    </p>
    <p>
      <strong>NOTE</strong>: This method is going away in favor of generic
      hooks. Buster will load its "framework resources" as extensions using these
      hooks (work in progress).
    </p>
    <pre><code>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");
});</code></pre>
  </div>
  <div class="section">
    <h2 id="supporting-objects">Supporting objects</h2>
    <h3 id="resource">Resource</h3>
    <p>
      A "resource" is something exposed on the server when you run browser tests
      using <code>buster-server</code> and
      <code>buster-test</code>. Exposing the resource <code>/something.json</code>
      allows you to request it in your tests using e.g.
      <code>jQuery.ajax({ url: "something.json" });</code>.
    </p>
    <h4>Content/file resources</h4>
    <dl>
      <dt><code>etag</code></dt>
      <dd>
        The <code>etag</code> is used by Buster to cache resources on the
        server. If the <code>etag</code> 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.
      </dd>
      <dt><code>minify</code></dt>
      <dd>
        If set to <code>true</code>, Buster will serve this resource minified with
        Ugliy.JS.
      </dd>
      <dt><code>combine</code></dt>
      <dd>
        Takes an array of resources to combine into one. Useful to run tests
        against a combined build of your project:
        <pre><code>config["Browser build tests"] = {
    environment: "browser",
    libs: ["lib/**.js"],
    resources: [
        "src/**.js",
        { path: "/mylib.min.js",
          combine: ["src/base.js", "src/dom.js"],
          minify: true  }
    ],
    sources: ["/mylib.min.js"],
    tests: ["test/**.js"]
};
</code></pre>
        <p>
          The above configuration will run tests against a combined and minified
          bundle of your application. Note that the <code>combine</code> property
          unfortunately does <strong>not</strong> understand globs (yet).
        </p>
        <p>
          When <code>combine</code> is set, you can not set <code>content</code>
          or <code>file</code>.
        </p>
      </dd>
      <dt><code>headers</code></dt>
      <dd>
        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.
      </dd>
      <dt><code>content</code></dt>
      <dd>
        Contents to serve as a string or a <code>Buffer</code>. When
        <code>content</code> is set, you can not set <code>combine</code> or
        <code>file</code>.
      </dd>
      <dt><code>file</code></dt>
      <dd>
        File to serve. When <code>file</code> is set, you can not set
        <code>combine</code> or <code>content</code>.
      </dd>
    </dl>
    <h4>Proxy resources</h4>
    <dl>
      <dt><code>backend</code></dt>
      <dd>
        Another HTTP server that will handle the requests for <code>path</code>.
        <pre><code>config["Browser integration tests"] = {
    resources: [
        { path: "/todo-items", backend: "http://localhost:8000/todo/todo-items" }
    ]
};</code></pre>
        <p>
          With this configuration, a request to
          <code>buster.env.path + "/todo-items/2"</code> would be proxyed to
          <code>"http://localhost:8000/todo/todo-items/2"</code>
        </p>
      </dd>
    </dl>
  </div>
</div>