Getting Started

This guide walks you through installation and very basic setup of tests in a project.

Installing

To run Buster.JS we recommend Node 0.6.3 or newer and NPM. Node 0.6.3 and newer comes with NPM bundled.

OS X

  1. Get the latest Node installer from nodejs.org. You need Node 0.6.3 or newer.
  2. sudo npm install -g buster

Linux

  1. Install Node 0.6.3 or later with your favorite package manager. If you don't have one, follow these simple build instructions.
  2. npm install -g buster

Windows

Unfortunately Buster.JS support for Windows is unconfirmed at this time.

As far as we know, the glob module is our only obstacle for your Windows JavaScript testing pleasure. Windows support is a priority and will land soon.

Create config file

Add a config file to your project. Call it test/buster.js or spec/buster.js, so you don't have to specify --config every time you run tests.

var config = module.exports;
config["My tests"] = {
    environment: "browser",        // or "node"
    sources: [
        "../lib/mylib.js", // Paths are relative to config file
        "../lib/**/*.js"   // Glob patterns supported
    ],
    tests: [
        "*-test.js"
    ]
}
// Add more configuration groups as needed

For browser tests, list all your source files in "sources" and test files in "tests". For Node tests, you don't need to specify "sources" as you typically require your source files directly in the test files.

Read the full buster-configuration documentation for details.

All the paths are relative to the config file itself.

Write tests

Given the config file above, all files named something-test.js in the same folder as the config file itself will be loaded. You can of course change the glob pattern to better suit your needs. "**/*-test.js" would for example recursively load all something-test.js in the same folder the config file is in, and all its sub folders.

A test case looks like this:

// Browser tests
buster.testCase("A module", {
    "states the obvious": function () {
        assert(true);
    }
});

The BDD inclined might prefer this alternate syntax:

buster.spec.expose(); // Make some functions global
describe("A module", function () {
    it("states the obvious", function () {
        expect(true).toEqual(true);
    });
});

If your test is a Node test, you also need to require Buster.JS.

// Node tests
var buster = require("buster");
var myLib = require("../lib/my-lib");
buster.testCase("A module", {
    "states the obvious": function () {
        assert(true);
    }
});

See the full buster.testCase docs and buster-assertions docs for details. There are also mocks and stubs and more, via the sinon-buster module.

Run tests

When you have a config file, you're ready to run tests.

Node tests

For Node tests, you don't need any additional setup. Open a terminal, go to your project, and type in buster test. Here's the output from the test run of buster-args.

See the Node testing documentation for more.

Browser tests

First, start a server. Open a terminal and type in buster server.

Capture some browsers to run the tests in by visiting the URL. Click the grey capture button to actually perform the capture.

Then you're ready to run the tests with buster test.

See the browser testing documentation for more.

Hybrid tests

If your project has both Node and browser tests, and your config file specifies multiple groups for the different environments, running buster test will automatically run all the groups, both Node and browser. This requires that you already have a buster server up and running.

If you only want to run tests for one environment, use buster test --environment browser or buster test -e node.

You have to manually make sure your test cases and source files are able to run in both browsers and Node. Here's an example:

(function(){
    if (typeof require != "undefined") {
        var buster = require("buster");
        var myLib = require("../lib/my-lib");
    }
}());
buster.testCase("A test case", {
    "test it": function () {
        assert(true);
    }
})

See the hybrid testing documentation for more.