or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-cypress--multi--reporters

Generate multiple mocha reports in a single mocha execution.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cypress-multi-reporters@2.0.x

To install, run

npx @tessl/cli install tessl/npm-cypress--multi--reporters@2.0.0

index.mddocs/

Cypress Multi Reporters

Cypress Multi Reporters is a Mocha reporter that enables multiple report formats to be generated in a single test execution. It allows you to combine different reporters like spec, JSON, XML, TAP, and custom reporters simultaneously, providing flexibility for different stakeholders who require different report formats from the same test suite.

Package Information

  • Package Name: cypress-multi-reporters
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install --save-dev cypress-multi-reporters
  • Peer Dependencies: mocha >=3.1.2

Core Imports

const MultiReporters = require("cypress-multi-reporters");

Basic Usage

Command Line Usage

# With default configuration
mocha --reporter cypress-multi-reporters

# With custom configuration file
mocha --reporter cypress-multi-reporters --reporter-options configFile=config.json

Programmatic Usage

const Mocha = require('mocha');

const mocha = new Mocha({
  reporter: "cypress-multi-reporters",
  reporterOptions: {
    reporterEnabled: "spec,json,xunit",
    jsonReporterOptions: {
      output: "results.json"
    },
    xunitReporterOptions: {
      output: "xunit.xml"
    }
  }
});

mocha.addFile('test/sample.test.js');
mocha.run();

Cypress Integration

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    reporter: 'cypress-multi-reporters',
    reporterOptions: {
      configFile: 'reporter-config.json'
    }
  }
});

Architecture

Cypress Multi Reporters works as a meta-reporter that:

  • Coordinates Multiple Reporters: Instantiates and manages multiple Mocha reporters simultaneously
  • Event Distribution: Forwards test events to all enabled reporters
  • Configuration Management: Merges default and custom configurations for each reporter
  • Output Coordination: Ensures multiple reporters can write to different outputs without conflicts
  • Error Handling: Gracefully handles reporter loading failures and continues execution

Capabilities

MultiReporters Class

The main class that implements the multi-reporter functionality.

/**
 * Multi-reporter class that coordinates multiple Mocha reporters
 * @param {Object} runner - Mocha test runner instance
 * @param {Object} options - Configuration options
 */
function MultiReporters(runner, options) {}

Configuration Management

getOptions()

/**
 * Merges default, custom, and dynamic options into resultant configuration
 * @param {Object} options - Input options object
 * @returns {Object} Merged configuration options
 */
MultiReporters.prototype.getOptions = function(options) {}

getCustomOptions()

/**
 * Loads custom configuration from JSON/JS file or directly from options
 * @param {Object} options - Input options object containing configFile reference
 * @returns {Object} Custom configuration from file or reporterOptions
 */
MultiReporters.prototype.getCustomOptions = function(options) {}

getDefaultOptions()

/**
 * Loads and parses default configuration from CONFIG_FILE
 * @returns {Object} Default configuration options
 */
MultiReporters.prototype.getDefaultOptions = function() {}

getReporterOptions()

/**
 * Extracts and processes configuration options for a specific reporter
 * @param {Object} options - Global options object
 * @param {string} name - Name of the specific reporter
 * @returns {Object} Reporter-specific configuration options
 */
MultiReporters.prototype.getReporterOptions = function(options, name) {}

Reporter Lifecycle

done()

/**
 * Coordinates completion of all enabled reporters with done handlers
 * @param {number} failures - Number of test failures
 * @param {Function} fn - Callback function to execute after all reporters are done
 */
MultiReporters.prototype.done = function(failures, fn) {}

Static Properties

CONFIG_FILE

/**
 * Default configuration file path
 * @type {string}
 */
MultiReporters.CONFIG_FILE = '../config.json';

Configuration Structure

Basic Configuration

{
  "reporterEnabled": "spec,json,xunit",
  "reporterOptions": {
    "id": "default"
  },
  "jsonReporterOptions": {
    "output": "results.json"
  },
  "xunitReporterOptions": {
    "output": "xunit.xml"
  }
}

Reporter Naming Convention

Configuration options for each reporter follow the pattern: {camelCasedReporterName}ReporterOptions

{
  "reporterEnabled": "@my-org/custom-reporter,mocha-junit-reporter",
  "myOrgCustomReporterReporterOptions": {
    "output": "custom-report.json"
  },
  "mochaJunitReporterReporterOptions": {
    "mochaFile": "junit.xml"
  }
}

Dynamic Configuration with JavaScript Files

// reporter-config.js
const locale = process.env.SITE_LOCALE || 'US';

module.exports = {
  "reporterEnabled": "mochawesome,mocha-junit-reporter",
  "mochawesomeReporterOptions": {
    "reportDir": `.reports/${locale}`
  },
  "mochaJunitReporterReporterOptions": {
    "mochaFile": `./junit/${locale}/results.xml`
  }
};

cmrOutput Option

Dynamic output file replacement mechanism for parameterized test runs.

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

Command line usage:

mocha --reporter cypress-multi-reporters --reporter-options configFile=config.json,cmrOutput=json+output+testSuite1

This replaces {id} placeholders with testSuite1 in the JSON reporter output path.

Supported Reporter Types

Built-in Mocha Reporters

The package automatically detects and loads built-in Mocha reporters:

  • spec: Default console output with test results
  • json: JSON format test results
  • xunit: XML format compatible with JUnit
  • tap: TAP (Test Anything Protocol) format
  • dot: Dot matrix representation
  • nyan: Nyan Cat reporter
  • landing: Landing strip reporter
  • list: List format reporter
  • progress: Progress bar reporter
  • min: Minimal reporter
  • markdown: Markdown format

External Reporters

Support for npm packages and local reporter files:

{
  "reporterEnabled": "mocha-junit-reporter,@my-org/custom,./local-reporter.js"
}

Reporter Loading Priority

  1. Built-in Mocha reporters via mocha.reporters[name]
  2. npm packages via require(name)
  3. Local files via require(path.resolve(process.cwd(), name))

Error Handling

Reporter Loading Errors

  • Missing Reporter: Warns "reporter_name" reporter not found when reporters cannot be found or loaded
  • Runtime Errors: Warns "reporter_name" reporter blew up with error: followed by stack trace for reporter initialization failures
  • Module Resolution: Tries multiple loading strategies: built-in Mocha reporters → npm packages → local file paths
  • Graceful Degradation: Continues execution with successfully loaded reporters, skipping failed ones
  • No Reporters: Errors Unable to invoke fn(failures) - no reporters were registered if no reporters load successfully

Configuration Errors

  • Invalid JSON: Throws errors for malformed JSON in configuration files with detailed error messages
  • File Access: Logs detailed errors when configuration files cannot be read or accessed
  • JavaScript Config: Supports .js configuration files with dynamic logic and environment variables
  • Validation: Validates configuration structure before processing reporters

Mocha Version Compatibility

  • Version Detection: Automatically detects Mocha version for compatibility handling
  • Fallback Warning: Warns Couldn't determine Mocha version if version detection fails
  • Stats Collector: Uses appropriate stats collection method based on detected Mocha version

Advanced Features

Scoped Package Support

Handles npm scoped packages with automatic option key transformation:

// Reporter: @angular/testing-reporter
// Options key: angularTestingReporterReporterOptions
{
  "reporterEnabled": "@angular/testing-reporter",
  "angularTestingReporterReporterOptions": {
    "output": "angular-results.json"
  }
}

Mocha Version Compatibility

  • Mocha 6+: Uses mocha/lib/stats-collector for enhanced statistics
  • Mocha <6: Maintains backward compatibility
  • Version Detection: Automatically detects Mocha version via package.json parsing

Multi-Environment Support

JavaScript configuration files enable environment-specific setups:

module.exports = {
  "reporterEnabled": process.env.CI ? "json,junit" : "spec",
  "jsonReporterOptions": {
    "output": `./reports/${process.env.BUILD_NUMBER || 'local'}/results.json`
  }
};

Types

interface ReporterOptions {
  /** Comma-separated list or array of enabled reporters */
  reporterEnabled: string | string[];
  /** Custom configuration file path (JSON or JS) */
  configFile?: string;
  /** Dynamic output replacement specification */
  cmrOutput?: string | string[];
  /** Global options applied to all reporters */
  reporterOptions?: Record<string, any>;
  /** Skip reporter execution (for testing) */
  execute?: boolean;
}

interface ReporterConfig {
  reporterEnabled: string;
  reporterOptions: Record<string, any>;
  [reporterName: string]: any;
}

interface DynamicOutputSpec {
  /** Target reporter name */
  reporter: string;
  /** Property to replace */
  property: string;
  /** Replacement value */
  value: string;
}

Common Usage Patterns

CI/CD Pipeline Integration

{
  "reporterEnabled": "spec,mocha-junit-reporter,json",
  "mochaJunitReporterReporterOptions": {
    "mochaFile": "./test-results/junit.xml"
  },
  "jsonReporterOptions": {
    "output": "./test-results/results.json"
  }
}

Multi-Environment Testing

#!/bin/bash
for env in dev staging prod; do
  export TEST_ENV=$env
  mocha --reporter cypress-multi-reporters --reporter-options configFile=multi-env-config.js
done

Custom Reporter Integration

{
  "reporterEnabled": "spec,./custom-slack-reporter.js",
  "customSlackReporterReporterOptions": {
    "webhook": "https://hooks.slack.com/...",
    "channel": "#test-results"
  }
}