mochawesome-merge

What is mochawesome-merge?

The 'mochawesome-merge' npm package is a utility that allows you to merge multiple Mochawesome JSON reports into a single JSON report. This is particularly useful when running tests in parallel or across different environments and you want to consolidate the results into one comprehensive report.

What are mochawesome-merge's main functionalities?

Merge Multiple Reports

This feature allows you to merge multiple Mochawesome JSON reports into a single JSON report. The code sample demonstrates how to use the 'mochawesome-merge' package to merge 'report1.json' and 'report2.json' into one consolidated report.

const merge = require('mochawesome-merge');
const options = { files: ['report1.json', 'report2.json'] };
merge(options).then(report => {
  console.log(report);
});

Custom Output File

This feature allows you to specify a custom output file for the merged report. The code sample demonstrates how to merge 'report1.json' and 'report2.json' and then write the merged report to 'merged-report.json'.

const merge = require('mochawesome-merge');
const fs = require('fs');
const options = { files: ['report1.json', 'report2.json'] };
merge(options).then(report => {
  fs.writeFileSync('merged-report.json', JSON.stringify(report));
});

Merge Reports with Custom Options

This feature allows you to merge reports with custom options such as specifying a custom directory and filename for the merged report. The code sample demonstrates how to use these custom options while merging 'report1.json' and 'report2.json'.

const merge = require('mochawesome-merge');
const options = { files: ['report1.json', 'report2.json'], reportDir: 'custom-dir', reportFilename: 'custom-report' };
merge(options).then(report => {
  console.log(report);
});

Other packages similar to mochawesome-merge

mochawesome

Mochawesome is a custom reporter for the Mocha test framework that generates a visually appealing HTML report along with a JSON report. While 'mochawesome-merge' focuses on merging JSON reports, 'mochawesome' is used for generating the initial reports.

mocha-multi-reporters

Mocha Multi Reporters allows you to use multiple reporters at once in Mocha. It can be used to generate different types of reports (e.g., JSON, HTML) simultaneously. Unlike 'mochawesome-merge', it does not merge reports but rather facilitates the generation of multiple reports in one test run.

mocha-parallel-tests

Mocha Parallel Tests is a tool that allows you to run Mocha tests in parallel. While it does not merge reports, it can be used in conjunction with 'mochawesome-merge' to run tests in parallel and then merge the resulting reports.

README

mochawesome-merge

Merge several Mochawesome JSON reports

Installation

via yarn:

$ yarn add mochawesome-merge --dev

via npm:

$ npm install mochawesome-merge --save-dev

Examples

JavaScript API

const { merge } = require('mochawesome-merge')

// See Params section below
const options = {
  files: [
    './report/*.json',

    // you can specify more files or globs if necessary:
    './mochawesome-report/*.json',
  ],
}

merge(options).then(report => {
  console.log(report)
})

CLI

$ npx mochawesome-merge ./report/*.json -o output.json

or legacy usage

$ npx mochawesome-merge ./report/*.json > output.json

You can specify as many paths as you wish:

$ npx mochawesome-merge ./report/*.json ./mochawesome-report/*.json -o output.json

You can also use a named option for the files like so:

$ npx mochawesome-merge -f ./report/*.json ./mochawesome-report/*.json -o output.json

Params

• files: list of source report file paths. Can include glob patterns.
• Aliases: -f | --files or first positional argument
• Defaults to ["./mochawesome-report/mochawesome*.json"].

• output: a file path to the bundled results. Should be a json file
• Aliases: -o | --output
• Defaults to stdout.

Migration to v4

Version 4 has come with a breaking change — it no more accepts params like reportDir or rootDir. Instead, it now accepts a list of file paths or glob patterns to source report files. If you are migrating to version 4 you likely have to change your params accordignly.

JavaScript API

Let's say you have a bunch of reports that you want to merge under ./mochawesome-report directory. Then you're probably using mochawesome-merge like this:

merge({
  reportDir: "mochawesome-report",
});

After switching to version 4 you need to rename reportDir param to files and change the value to point to your files rather than the directory:

merge({
-  reportDir: "mochawesome-report",
+  files: ["./mochawesome-report/*.json"],
})

CLI

After upgrading to version 4 all you need is to remove the --reportDir option and instead specify a glob pattern or several ones if necessary, separating each one with a space:

- npx mochawesome-merge --reportDir mochawesome-report > mochawesome.json
+ npx mochawesome-merge ./mochawesome-report/*.json > mochawesome.json

Cypress

The main motivation to create this library was to be able to use mochawesome together with Cypress.

Since the version 3.0.0, Cypress runs every spec separately, which leads to generating multiple mochawesome reports, one for each spec. mochawesome-merge can be used to merge these reports and then generate one HTML report for all your cypress tests.

First, configure cypress.json:

{
  // use mochawesome reporter as usually
  "reporter": "mochawesome",
  "reporterOptions": {
    // disable overwrite to generate many JSON reports
    "overwrite": false,
    // do not generate intermediate HTML reports
    "html": false,
    // generate intermediate JSON reports
    "json": true
  }
}

Then, write your custom script to run cypress together with mochawesome-merge:

const cypress = require('cypress')
const marge = require('mochawesome-report-generator')
const { merge } = require('mochawesome-merge')

cypress.run().then(
  () => {
    generateReport()
  },
  error => {
    generateReport()
    console.error(error)
    process.exit(1)
  }
)

function generateReport(options) {
  return merge(options).then(report => marge.create(report, options))
}

Alternatively, you can use CLI to merge JSON reports and generate HTML report. For example, an AWS CodeBuild buildspec.yml file might look something like this:

phases:
  install:
    commands:
      - yarn install
  build:
    commands:
      - yarn cypress run
  post_build:
    commands:
      - yarn mochawesome-merge > mochawesome.json
      - yarn marge mochawesome.json