Mocha Multi Reporters

Mocha Multi Reporters is a Mocha reporter plugin that enables generating multiple test reports in a single test execution run. It allows developers to configure and use multiple Mocha reporters simultaneously, such as spec, xunit, json, and other built-in or custom reporters, through a simple configuration file.

Package Information

• Package Name: mocha-multi-reporters
• Package Type: npm
• Language: JavaScript
• Installation: npm install mocha-multi-reporters --save-dev

Core Imports

const MultiReporters = require('mocha-multi-reporters');

ES6 imports:

import MultiReporters from 'mocha-multi-reporters';

Basic Usage

The most common usage is to configure it as a Mocha reporter with a configuration file:

# Basic usage with default config
./node_modules/.bin/mocha --reporter mocha-multi-reporters

# Using custom configuration file
./node_modules/.bin/mocha --reporter mocha-multi-reporters --reporter-options configFile=config.json

Example configuration file:

{
  "reporterEnabled": "spec, json, xunit",
  "jsonReporterOptions": {
    "output": "test-results.json"
  },
  "xunitReporterOptions": {
    "output": "test-results.xml"
  }
}

Architecture

Mocha Multi Reporters extends Mocha's Base reporter class and acts as a meta-reporter that instantiates and coordinates multiple child reporters. It handles the lifecycle management of multiple reporters, ensuring proper initialization, event handling, and completion coordination.

Capabilities

Reporter Instantiation

Creates a MultiReporters instance that manages multiple child reporters.

function MultiReporters(runner, options);

Parameters:

• runner (object): Mocha test runner instance
• options (object): Configuration options object

Options object properties:

• execute (boolean, default: true): Whether to execute reporter initialization
• reporterOptions (object): Reporter configuration options

Completion Handling

Coordinates completion across multiple reporters with done callbacks.

MultiReporters.prototype.done = function(failures, fn);

Parameters:

• failures (number): Number of test failures
• fn (function): Callback function to invoke when all reporters complete

Configuration Management

Get Merged Options

Merges default, custom, and runtime options into a single configuration object.

MultiReporters.prototype.getOptions = function(options);

Parameters:

• options (object): Raw options object

Returns: (object) Merged configuration options

Get Custom Options

Loads custom configuration from a file or options object.

MultiReporters.prototype.getCustomOptions = function(options);

Parameters:

• options (object): Options containing configFile path or reporterOptions

Returns: (object) Custom configuration options

Supports both JSON and JavaScript configuration files. The configFile path is resolved relative to the current working directory.

Get Default Options

Loads the default configuration from the built-in config.json file.

MultiReporters.prototype.getDefaultOptions = function();

Returns: (object) Default configuration options from config.json

Get Reporter-Specific Options

Extracts and processes options for a specific reporter by name.

MultiReporters.prototype.getReporterOptions = function(options, name);

Parameters:

• options (object): Global options object
• name (string): Reporter name

Returns: (object) Reporter-specific configuration options

Reporter-specific options follow the pattern {camelCaseName}ReporterOptions. For example, options for the xunit reporter would be specified in xunitReporterOptions.

Configuration Format

Basic Configuration

interface ReporterConfig {
  reporterEnabled: string | string[];
  reporterOptions?: object;
  [reporterName + 'ReporterOptions']?: object;
  cmrOutput?: string | string[][];
}

Reporter Output Configuration

The cmrOutput option allows dynamic output file naming:

{
  "reporterEnabled": "json, xunit",
  "cmrOutput": "json+output+results.json:xunit+output+results.xml"
}

Or as an array:

{
  "reporterEnabled": "json, xunit", 
  "cmrOutput": [
    ["json", "output", "results.json"],
    ["xunit", "output", "results.xml"]
  ]
}

Static Properties

CONFIG_FILE

Path to the default configuration file.

MultiReporters.CONFIG_FILE = '../config.json';

Error Handling

The reporter handles several error conditions:

• Missing reporters: Logs error message when a specified reporter cannot be loaded
• Invalid config files: Throws errors when configuration files cannot be parsed
• Module loading errors: Attempts to load reporters from both npm modules and local paths

Supported Reporter Types

The plugin supports:

• Built-in Mocha reporters: spec, json, xunit, tap, dot, etc.
• External npm packages: Any reporter published to npm
• Local reporters: Custom reporters in the local file system

Instance Properties

_reporters

Array of instantiated reporter instances.

MultiReporters.prototype._reporters: Array<object>;

Each element in the array is an instantiated reporter object that follows Mocha's reporter interface.