jstest

Reporter plugins

jstest creates all its various output formats and integrates with browser test runners using objects called reporters. A reporter is an object that is notified by the framework about the progress of the tests and produces output for the user to see. You can set which reporters are used for a test run using this API:

JS.Test.autorun(function(runner) {
  runner.setReporter(reporter)
  runner.addReporter(another)
})

setReporter() removes any existing reporters and attaches a new one. addReporter() adds the given reporter, without replacing the existing ones.

Built-in reporters

These are all the reporters that are bundled with jstest. Each reporter is labelled with a type: browser and server indicate the reporter only runs in that environment, while text indicates it only writes text to stdout or the browser console and works in any environment.

Reporters live in the JS.Test.Reporters namespace, for example to instantiate the JSON reporter you call new JS.Test.Reporters.JSON().

• Browser [browser] – renders the jstest browser UI
• Buster [browser] – reports progress to Buster.JS
• Composite – delegates reporter events to a set of other reporters
• Dot [text] – prints a dot for each passing test
• Error [text] – prints error details as soon as they happen
• ExitStatus [server] – makes the process exit with status 0 or 1
• JSON [text] – prints a stream of JSON objects containing reporter events
• Karma [browser] – reports progress to Karma
• Headless [server] – reports on PhantomJS/SlimerJS tests in the terminal
• Progress [server] – prints an animated progress bar in the terminal
• Spec [text] – prints RSpec-style nested specdoc format
• TAP [text] – prints results in TAP format
• TAP_JSON [text] – prints results in TAP-JSON format
• TAP_YAML [text] – prints results in TAP-YAML format
• Teabag [browser] – reports progress to Teabag
• Testem [browser] – reports progress to Testem
• TestSwarm [browser] – reports progress to TestSwarm
• XML [text] – prints JUnit-style XML report to stdout

Most of these can be instantiated without arguments, but some are more complicated. For example, the Headless reporter takes an options object that specifies the output format, and relies on the test page using the JSON reporter – jstest sets this all up for you by default.

Similarly, jstest automatically selects whichever browser reporters are appropriate for the current environment. Attempting to use any of the browser-runner reporters (e.g. Buster) outside of those environments will produce errors when the reporter tries to log output.

The Composite reporter

The Composite reporter does not emit output itself but just delegates events to a set of other reporters. It also makes sure that the events it’s called with are dispatched in the correct order to the underlying reporters, which can be helpful if you’re sending test events over an I/O channel that might deliver events out of order. It can be convenient to use this instead of looping over a set of reporters yourself.

var R        = JS.Test.Reporters,
    spec     = new R.Spec(),
    exit     = new R.ExitStatus(),
    reporter = new R.Composite([spec, exit])

// Calls both the spec and exit reporters
reporter.startSuite()

Default reporters

If you don’t specify which reporters you want to use, jstest selects a default set for you based on the environment.

On the server, it will use whichever text reporter is specified by the FORMAT environment variable, or dot by default, and the ExitStatus reporter. If you set a different text reporter using setReporter(), remember to add the ExitStatus reporter using addReporter() afterwards.

In the browser, it will use the Browser reporter and pick others to run based on the environment. For example, if it detects it’s running on Buster.JS it will add the Buster reporter.