karma-subunit-reporter/README.md

karma-subunit-reporter

Writes Karma results to Subunit streams compatible with Subunit consumers like stackviz and subunit2sql.

Installation

npm install --save-dev karma-subunit-reporter

Usage

Trivial usage only requires that you install the plugin and then add it as a reporter in your karma.conf.js:

module.exports = function(config) {
  config.set({
    // ...

    reporters: ['some', 'other', 'reporters', 'subunit'], // <----

    // ...
  });    
};

You can also specify some configuration parameters with the subunitReporter object (defaults are shown below):

module.exports = function(config) {
  config.set({
    reporters: ['subunit'],

    // ...

    subunitReporter: {
      outputFile: 'karma.subunit',
      tags: [],       // tag strings to append to all tests
      slug: false,    // if true, convert whitespace to '_'
      separator: '.', // separator for suite components + test name
      normalize: null // an optional normalization function, see below
    }
  });    
};

Normalizing Test Names

Given that JavaScript's test name formatting conventions are dissimilar to those in other subunit-supported languages (particularly, Python) it may be desirable to convert tokens to something that more closely resembles the other languages in your environment. Additionally, tooling may require that test names be reasonably well-formed for parsing and categorization purposes.

In all cases, test name tokens are gathered from karma's suite field along with the test's description. For Jasmine tests, suite is an ordered list of enclosing describe() strings for each test. The list of tokens (i.e. suites plus description) are then passed to some mapping function.

If not otherwise configured, this mapping function simply returns the list of tokens unaltered; however, it can also be configured to perform simple conversions from Jasmine-style test descriptions to simple, dot-separated Python-ish test names. If configured with slug: true, spaces will be collapsed and converted to _, which yields decent results in some cases.

If more advanced conversion is needed, a custom mapping function can be provided using the normalize parameter, which accepts a list of tokens and returns a modified list of tokens.

As a final step, mapped tokens are then joined using the separator parameter (. by default).

Tags

The plugin automatically appends certain tags to each test: the browser ID (browser-*) and the spec ID (spec-*). If multiple browsers are tested concurrently these tags can be used to match results across browsers.

Constant tags to apply to all tests can be also be specified using the tags config option. Each string in the list is unconditionally appended to all tests, and can be used as a potential compatibility measure (for example, to support tools that assume a worker-* tag should exist).

Output Differences

While in theory this plugin's output should work correctly with all subunit-compatible tooling, in practice it may violate some assumptions that can be made safely in other languages.

For one, tests only run in a single worker thread (and unless configured, no worker-# tag is present). Additionally, within the single worker, tests are (at least potentially) run asynchronously and may have overlapping execution timelines.

Some other minor differences also exist. Currently file attachments aren't supported, so log output, error messages, and tracebacks won't be included in the subunit output. There's also no 'setUpClass' or other events that might be logged in Python tests.