buster.testRunner

var testRunner = require("buster-test").testRunner;
var xUnitConsoleReporter = require("buster-test").xUnitConsoleReporter;
var runner = testRunner.create();
var reporter = xUnitConsoleReporter.create({ color: true });
reporter.listen(runner);
runner.runSuite([context, context2, ...]);

Events

Event: "suite:start", function () {}

Emitted once, as the runner starts running a test suite (typically when runSuite is called).

Event: "suite:end", function (results) {}

Emitted once, when all contexts are run (typically when runSuite completes).

Event: "context:start", function (context) {}

Emitted every time a context is entered.

Event: "context:end", function (context) {}

Emitted every time a context is completed.

Event: "context:unsupported", function (ctx) {}

Emitted every time a context fails its requirements (when that happens, neither context:start or context:end are emitted).

Event: "test:setUp", function (context) {}

Emitted once per test before the setup method(s) for a test is called.

Event: "test:start", function (context) {}

Emitted after running the test's setup(s), but before the test itself runs.

Event: "test:async", function (test) {}

Emitted when a test has been found to be asynchronous (usually means that the test function was called and has returned).

Event: "test:tearDown", function (test) {}

Emitted once per test before the tear down method(s) for a test is called.

Event: "test:failure", function (error) {}

Emitted when the test throws (or otherwise flags) an AssertionFailure. Only emitted once per test.

Event: "test:error", function (error) {}

Emitted when the test throws any error that is not an AssertionFailure. Only emitted once per test.

Event: "test:success", function (test) {}

Emitted if the test passes.

Event: "test:timeout", function (test) {}

Emitted if the test runner forcefully aborts the test. This happens when the test is asynchronous and does not resolve within the configured timeout.

Event: "test:deferred", function (test) {}

Emitted when a test is marked as deferred. The test is not run.

Event: "uncaughtException", function (err) {}

Uncaught errors are errors that the test runner is unable to associate with the test that threw it. They occur in two situations:

1. A synchronous test spawns an asynchronous task that results in an error. For instance, calling setTimeout with a callback that throws an error in a synchronous test.
2. An aborted asynchronous test throws (for instance, by failing an assertion).

The "uncaughtException" event will only be emitted when the environment supports it and the handleUncaughtExceptions property is set to true. Browsers that do not support window.onerror are unable to support this feature.

Methods

var runner = buster.testRunner.create([opts]);

Creates a new test runner instance.

buster.testRunner.onCreate(function (runner) {});

Register a callback which is called everytime a runner is created with create.

runner.runSuite([context, context2, ...]);

Run an array of context objects as a test suite.

runner.run(context);

Run a single context. Note that this method does not trigger the suite:start event, and using it instead of runSuite may cause unintended behavior in reporters.

var count = runner.assertionCount();

The default implementation of this method is a no-op function. This method is called by the runner after each test to determine the number of assertions used in the test. It should not accumulate the assertion count.

Because the runner itself has no knowledge of the assertion library, this method is intended to be overridden by the assertion library in use. For instance, this is the integration necessary to count assertions with buster-assertions:

var assertions = 0;
buster.assert.on("pass", function () {
    assertions += 1;
});
buster.testRunner.onCreate(function (runner) {
    runner.on("test:start", function () {
        assertions = 0;
    });
});
buster.testRunner.assertionCount = function () {
    return assertions;
};

runner.assertionFailure(exception);

Can be called from assertion libraries that do not throw an exception on assertion failure. For assertion failures to be picked up no matter what in asynchronous tests, this method needs to be called, as some exceptions are not possible for the runner to catch.

Properties

Test runner properties can be set when creating an instance, or simply by assigning to the property on an existing runner.

var runner = buster.testRunner.create({
    timeout: 500
});
// Or:
var runner = buster.testRunner.create();
runner.timeout = 500;

failOnNoAssertions (true)

When true, a test with no assertions is considered a failure. The number of assertions are measured with assertionCount.

timeout (250)

When an asynchronous test runs for more than timeout ms, the runner will abort it and emit a test:timeout event.

handleUncaughtExceptions (true)

When true, the runner will attempt to handle uncaught exceptions, by registering a listener on process for "uncaughtException" (node.js) and assigning a callback to window.onerror (browsers).

Supporting objects

results

A high-level numeric report. Emitted with suite:end.

{
    contexts: 0,
    tests: 0,
    errors: 0,
    failures: 0,
    assertions: 0,
    timeouts: 0,
    deferred: 0
}

error

An object representing a test failure (or error), emitted with test:failure and test:error.

{
    name: "Name of test",
    error: {
        name: "Type of exception",
        message: "Exception message",
        stack: "Stack trace as string"
    }
}

exception

An exception-like object, emitted with uncaughtException. In browsers, this object does not have a stack trace.

{
    name: "Type of exception",
    message: "Exception message",
    stack: "Stack trace as string"
}

unsupported

Information about an unsupported context. Emitted with context:unsupported. Contains an array of names of failed requirements and a context object.

{
    context: context,
unsupported: ["label1", "label2"]
}