mochawesome writes an offline HTML report for every Mocha run

Mochawesome is a reporter that sits behind Mocha

Mochawesome is not a test framework and it never runs your tests. It is a reporter you hand to Mocha, and Mocha calls it when a run ends so the reporter can collect what happened. The result is a standalone HTML and CSS report you can open from disk, email, or attach to a CI artifact without a server behind it.

The problem it addresses is narrow and real: Mocha's own console output disappears once the terminal scroll is gone. A team that wants a browsable record of a run, including which suites passed, what a failure's stack trace said, and what extra context a test attached, has to assemble that itself. Mochawesome packages the work as a drop-in reporter.

Its audience is engineers running Mocha on Node.js, especially those who want a shareable report per test run rather than a raw JSON blob for a custom pipeline. The project requires Node.js 18 or newer and declares Mocha 8 through 12 as a peer dependency, so Mocha is installed alongside the reporter rather than bundled inside it.

Two output files, and the raw JSON is the stable one

The output directory has a fixed shape. Inside the project directory you get a folder named mochawesome-report holding the rendered page, a raw data file, and an assets directory with the stylesheet, the page script and the bundled webfonts.

The rendered page, mochawesome.html, is the file a person opens. It is written to be self-contained, so it can be viewed with no network connection. The second file, mochawesome.json, holds the raw run data, described in the project documentation as the raw json output used to render the report. That separation is the design decision worth noticing: the JSON is a clean hand-off point. Anything you want to do with the numbers, store them, compare two runs, or push them into a dashboard, can read the JSON rather than scraping the page.

Which of the two files gets written is configurable. The html and json options are booleans that both default to true, so switching one off is the way to keep only the data. Whether the assets directory still appears after such a change is not described in the option list, so it is worth looking at the directory before assuming the output is minimal.

Installing the reporter and producing a first report

Install the reporter as a development dependency, then point Mocha at it by name.

npm install --save-dev mochawesome

That keeps the reporter out of the production dependency tree. The next step is to run Mocha with the reporter selected, using a spec file of your own.

mocha testfile.js --reporter mochawesome

After the run, look for the mochawesome-report directory in the project root. It contains mochawesome.html, mochawesome.json and the assets folder. Open the HTML file in a browser to see the summary of the run, per suite and per test results, and the stack trace for anything that failed.

If you drive Mocha from your own code, the same reporter is selected through the constructor. The export shape changed in Mocha 12, so the snippet below covers both cases.

const { Mocha } = require('mocha'); // Mocha <= 11: const Mocha = require('mocha')

const mocha = new Mocha({
  reporter: 'mochawesome',
});

The comment on the first line matters. On Mocha 12 the constructor is a named export, while on earlier versions the module itself is the constructor. Copying the newer form into an older project fails at load time rather than at report time, which is a cheap way to lose an afternoon.

Reporter options arrive two ways, and the flag wins

Options can be supplied in two ways, and the two are not equal in precedence. The reporter reads environment variables whose names begin with MOCHAWESOME_, and it insists they are written in uppercase.

$ export MOCHAWESOME_REPORTFILENAME=customReportFilename

When Mocha's --reporter-options flag is used, the comma-separated values it carries take precedence over the environment. A report filename set in the shell can therefore still be overridden by a flag on the same command line.

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

The same options can be set programmatically through reporterOptions on the Mocha constructor. The reporter-specific option list is short: quiet to silence console messages, reportFilename for the saved name, html and json to switch each output file on or off, and consoleReporter, which names the Mocha reporter used for console output and accepts none to turn console reporting off entirely. That last one defaults to spec, so adding Mochawesome does not silence the familiar terminal output.

Filenames can be assembled from tokens. The [name] token becomes the spec filename, [status] becomes pass or fail, and [datetime] becomes a timestamp whose format is set by the timestamp option. One constraint catches people out: the [name] token only applies when Mocha runs one spec file per process and writes a separate report for each spec, which the project names Cypress as the usual case.

Parallel mode drops addContext data unless the hook is registered

Parallel mode is where the reporter has a genuine failure mode. Since mocha@8, Mocha can run test files in parallel with the --parallel flag. Tests then execute in worker processes and their data is serialized back to the main process, and the report is built from that serialized data.

Serialization is lossy for the parts Mochawesome attaches itself. Information added through addContext and the skipped-test counts do not survive the trip unless Mochawesome is registered as a hook. When they are dropped, the reporter logs a warning.

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

With the hook registered, the context data comes back. Without it, a parallel run still produces a report, so the failure is quiet rather than loud: the page renders and the details are simply absent. If you rely on addContext inside a parallel suite, treat the --require mochawesome/register flag as part of the command, not as an optional extra.

addContext and the arrow function trap

Mochawesome ships an addContext helper that attaches extra information to a test so it shows up in the report. The helper takes the test object and a context, and the context may be a string or an object.

Simple strings are displayed as they are, and the reporter tries to turn a string that looks like a URL into a link. If the URL points at an image or a video, the reporter embeds it instead of only linking it.

The sharp edge is stated plainly: arrow functions will not work with addContext. The helper needs the this binding of the test, and a test written as an arrow function has no usable this to read. The fix is to write the test body as a regular function and call addContext inside it.

On suites that also run in parallel, the two constraints meet in the same command line, so the register hook and the regular function form have to be applied together. A report that renders without the expected context is the symptom of one or the other being missing.

Where the HTML page comes from, and where Mochawesome stops

It is worth being clear about what Mochawesome does not do. It does not touch how your tests are written or which assertions they make. It also does not build the HTML page by itself. The report is produced in conjunction with mochawesome-report-generator, a separate package pinned in the dependency list at ^6.3.2, and the reporter points at that package for the full set of options. Anyone reading the reporter's own option table needs the generator's documentation alongside it.

The plain alternative is to skip HTML entirely. A team that wants its own dashboard or a comparison view between two runs can read mochawesome.json and ignore the page. The trade is the charting, the filters, the inline test code review and the before and after hooks display, all of which exist only in the generated HTML.

A second alternative is to stay on console output. The consoleReporter option already lets you keep the spec reporter, or none, alongside the report files, so Mochawesome can be added to an existing pipeline without changing what engineers see in the terminal. Neither alternative gives you the offline HTML page, and Mochawesome does not displace Mocha's own reporters.

A current 8.x line under the MIT license

The repository is not archived, and the last push was on 2026-09-28, so the code is current with the Node.js ecosystem rather than parked. Releases sit on the 8.x line, with 8.1.1 published on 2026-09-15, 8.1.0 on 2026-09-11 and 8.0.1 on 2026-07-31. Those three dates sit close together, which reads as a burst of smaller corrections rather than a slow drip of new features, though the changelog is the place to confirm what each one changed.

Upgrading costs little in terms of shape. The package entry point is src/mochawesome.js and the published files are limited to addContext.js, register.js and src, so the public surface is small and a minor bump is unlikely to alter the command line you already run. The repository also carries an ESM-MIGRATION.md, the file to read before moving a suite to native ES modules, and a test-parity directory whose run.js script compares behaviour against published versions.

The licence is MIT, so the code can be used, modified and redistributed in commercial and non-commercial projects under its terms, including in internal tooling that ships with a product. That is a statement about the licence text, not advice on how to apply it.

Editorial conclusion

Adopt mochawesome when a team runs Mocha on Node.js and wants a shareable offline HTML page per run, and set the consoleReporter option deliberately so terminal output stays predictable. Do not adopt it if you only need the raw numbers for a custom pipeline, since mochawesome.json already holds those and the page adds nothing there. Before switching, verify that your Mocha version falls between 8 and 12, that arrow function tests are rewritten where addContext is used, and that the --require mochawesome/register flag is present in every parallel invocation.

Frequently asked questions

Official sources

1. adamgruber/mochawesome on GitHub
2. License: MIT
3. Project website
4. README
5. Releases