mochawesome

The parity gate uses a deterministic process to ensure report stability:

• fixtures/: A suite of tests covering various scenarios (pass, fail-with-diff, pending, nested, hooks, and addContext). These use hand-built errors to ensure output stability across Node versions.
• normalize.js: A normalization step that replaces non-deterministic values (UUIDs, durations, timestamps, absolute paths, and stack frames) with stable placeholders. It also sorts JSON keys and parallel-mode suite ordering to ensure a deterministic comparison.
• golden/: The directory containing the committed, expected JSON output files used as the baseline for comparison.

You can dynamically alter the generated report filename using the following tokens in the reportFilename option:

• [name]: Replaced with the spec filename (works when running one spec file per process, e.g., in Cypress).
• [status]: Replaced with the status (pass or fail) of the test run.
• [datetime]: Replaced with a timestamp. The format can be customized using the timestamp option.

Example Configuration:

{
  reporter: "mochawesome",
  reporterOptions: {
    reportFilename: "[status]_[datetime]-[name]-report",
    timestamp: "longDate"
  }
}

If the spec is cypress/integration/sample.spec.js, the resulting file might be named pass_February_23_2022-sample-report.html.

To use mochawesome as a reporter for your Mocha test runs, install it as a development dependency using npm:

npm install --save-dev mochawesome

The parity gate verifies that the reporter's output contract remains unchanged by running a fixed fixture suite and comparing the generated JSON against committed golden snapshots. This ensures that any changes to the report shape or content are caught as regressions.

Use the following commands to manage the parity gate:

• To verify the current output against existing snapshots (will exit with code 1 on mismatch).
• To regenerate snapshots after making an intentional change to the report format.

Note: This gate runs automatically during npm test and is enforced in CI and during the prepack phase.

npm run test:parity          # verify against golden snapshots (exit 1 on mismatch)
npm run test:parity:update   # regenerate snapshots after an intentional change

Mochawesome does not include its own type definitions. You can install them from DefinitelyTyped via npm:

npm install --save-dev @types/mochawesome

When using mocha@8 or newer with the --parallel flag, mochawesome must be registered as a hook to function correctly. Use the --require flag to load mochawesome/register:

mocha tests --reporter mochawesome --require mochawesome/register

To perform a manual check comparing your local working tree against a version currently published on npm (useful before cutting a major release), use the test:parity:published command. This command installs both your local code and the target version into temporary projects to diff their normalized JSON outputs.

• To compare against mochawesome@latest on npm.
• To compare against a specific version (e.g., 7.1.4).

npm run test:parity:published            # vs mochawesome@latest on npm
npm run test:parity:published -- 7.1.4   # vs a specific published version

The reporter can be configured using environment variables. All variable names must be in uppercase and must start with the prefix MOCHAWESOME_.

Example:

$ export MOCHAWESOME_REPORTFILENAME=customReportFilename

You can pass comma-separated options to the reporter using Mocha's --reporter-options flag. These options take precedence over environment variables.

CLI Usage:

$ mocha test.js --reporter mochawesome --reporter-options reportDir=customReportDir,reportFilename=customReportFilename

Programmatic Usage:

var mocha = new Mocha({
  reporter: 'mochawesome',
  reporterOptions: {
    reportFilename: 'customReportFilename',
    quiet: true,
  },
});

You can configure mochawesome using environment variables. The variable name must be MOCHAWESOME_ followed by the uppercase version of the option name.

For example:

• To set quiet to true: MOCHAWESOME_QUIET=true
• To set reportFilename to 'results': MOCHAWESOME_REPORTFILENAME=results

# Example: Running mocha with environment variable configuration
MOCHAWESOME_QUIET=true MOCHAWESOME_REPORTFILENAME=test_results mocha

To use mochawesome to generate HTML and JSON reports for your Mocha test runs, register it as a reporter in your Mocha configuration or CLI command.

When initialized, mochawesome performs the following:

1. Console Output: It can wrap an existing Mocha reporter (like spec) to provide real-time console feedback while the tests run.
2. UUID Assignment: It automatically assigns a unique uuid to every suite, test, hook, and pending test to ensure traceability.
3. Report Generation: Upon completion of the test suite, it uses mochawesome-report-generator to create the final HTML and JSON files based on your configuration.
4. Parallel Support: It is compatible with Mocha's ParallelBufferedRunner, correctly aggregating suites and tests from worker processes.

# Example CLI usage
npx mocha --reporter mochawesome

If the parity gate fails, it means the generated report output has changed. You must determine if the change was unintended or intended:

1. Unintended Change (Regression): If the change was not planned, fix the reporter code until the gate passes against the existing golden snapshots.
2. Intended Change: If you deliberately changed the report format, run npm run test:parity:update. Review the resulting diff in the golden files to ensure it is correct, then commit the updated snapshots to document the change in your PR.