How to Generate Mocha Test Reports With Mochawesome

Mochawesome generates readable HTML reports and raw JSON from Mocha tests. Install it as a development dependency, run Mocha with --reporter mochawesome, and open the generated mochawesome-report/mochawesome.html. HTML and JSON output are both enabled by default.

1. Install Mochawesome

Mochawesome is a custom reporter for Mocha. Its package documentation currently lists Node.js 18 or later and Mocha 8–12 as requirements; check the package metadata when upgrading because compatibility can change.

npm install --save-dev mochawesome

Confirm the project uses compatible versions:

node --version
npx mocha --version
npm ls mochawesome mocha

If Mocha is not already installed locally, add it as a development dependency too:

npm install --save-dev mocha

2. Generate the report

Run the reporter against a test file:

npx mocha testfile.js --reporter mochawesome

Or use a glob for a test directory:

npx mocha "test/**/*.js" --reporter mochawesome

On completion, open mochawesome-report/mochawesome.html in a browser. The raw report data is mochawesome-report/mochawesome.json. The HTML is intended for reading; the JSON is structured report data that another tool can consume.

Add a package script so developers and CI use the same command:

{
  "scripts": {
    "test:report": "mocha \"test/**/*.js\" --reporter mochawesome"
  }
}

npm run test:report

3. Configure report output

Pass comma-separated options after --reporter-options to change the directory or filename:

npx mocha "test/**/*.js" --reporter mochawesome --reporter-options reportDir=artifacts/mocha,reportFilename=ci-results

This writes the report using the selected name under artifacts/mocha. Use a directory that your CI system collects as an artifact if reports should be retained after a run.

Option	Default	Purpose
reportDir	mochawesome-report	Directory for generated output.
reportFilename	mochawesome	Base name for report files.
html	true	Generate rendered HTML.
json	true	Generate raw JSON.
quiet	false	Reduce reporter output in the terminal.
consoleReporter	spec	Choose terminal reporter output; set to none to suppress it.

For example, to keep only HTML output and suppress the console reporter:

npx mocha test.js --reporter mochawesome --reporter-options html=true,json=false,consoleReporter=none

Options can also be provided as a reporterOptions object in programmatic use. Mochawesome documents environment variables prefixed with MOCHAWESOME_; directly supplied reporter options take precedence over environment variables.

4. Use Mochawesome with Mocha parallel mode

Mochawesome documents an extra registration step for parallel mode. Require its registration module when invoking Mocha:

npx mocha "test/**/*.js" --parallel --reporter mochawesome --require mochawesome/register

Mocha creates a separate instance for each test file in parallel mode. If you need hooks to apply across files, Mocha recommends defining root hooks in a required file. Do not rely on a deterministic execution order between files. Review the parallel-mode behavior in the Mocha documentation and the reporter setup in the Mochawesome package documentation.

5. Render an existing JSON report separately

If tests already produce Mochawesome JSON, or you want report rendering to be a separate step, use mochawesome-report-generator (also known as marge):

npm install --save-dev mochawesome-report-generator
npx marge mochawesome-report/mochawesome.json

The generator accepts controls for report name and directory, title, asset handling, chart display, and whether to save HTML or JSON. Consult its package documentation for the exact option names and supported values for the installed version. This split is useful when JSON is produced in one job and rendered in another.

6. Mochawesome versus Mocha’s built-in JSON reporter

Mocha also includes a JSON reporter. It writes one JSON object after the tests finish and can write that output to a named file; it does not by itself produce Mochawesome’s HTML report. Choose based on what will consume the results:

Approach	Use it when	Output
Mochawesome reporter	People need a rendered report during the test run.	HTML and JSON by default.
Mocha JSON reporter	A downstream system needs Mocha’s JSON output and no Mochawesome HTML is required.	JSON object.
Mochawesome JSON plus marge	Tests and HTML rendering should be separate stages.	JSON first, then generated HTML.

See Mocha’s JSON reporter documentation for its behavior.

7. Troubleshoot common problems

Symptom	Likely cause	Fix
Reporter "mochawesome" not found	The package is missing from the project or the command runs outside the project that installed it.	Run npm install --save-dev mochawesome in the project and invoke it with npx mocha from that project.
Node or Mocha compatibility error	The installed runtime or Mocha version falls outside the package’s stated requirements.	Check node --version, npx mocha --version, and current package metadata; use compatible versions.
No report appears	Mocha did not complete normally, the report path differs from the expected default, or both output formats were disabled.	Inspect the command’s exit status and terminal output, check reportDir, and ensure html or json is enabled.
The report is in an unexpected folder	reportDir was customized or the process working directory differs from the assumed project root.	Set reportDir explicitly and resolve the artifact path relative to the directory from which Mocha runs.
Parallel run fails to report correctly	The reporter registration step was omitted.	Add --require mochawesome/register and review Mocha’s worker and root-hook behavior.
Terminal output is noisy or missing	consoleReporter or quiet changes console reporting.	Set consoleReporter=spec for spec output, or consoleReporter=none to suppress it; check quiet.
Only JSON is available	HTML generation may have been disabled, or the workflow is using Mocha’s built-in JSON reporter.	Enable Mochawesome’s html option, or pass the Mochawesome JSON file to marge.

8. Performance, reliability, and cost considerations

• Runtime: Report generation adds work after test results are collected. For large suites, measure the total job duration in your own CI workflow and keep report generation in the same job if immediate HTML artifacts are useful.
• Parallelism: Parallel mode can affect how hooks and per-file Mocha instances behave. Use the documented registration step and avoid assumptions about file execution order.
• Reliability: Keep the raw JSON when another process needs to regenerate HTML or inspect results. Ensure the report directory is uploaded or retained by CI; a local report is not automatically a durable artifact.
• Cost: Mochawesome is an npm development dependency. The cited package workflow introduces no paid service requirement; CI compute and artifact storage costs depend on your own provider and retention configuration.

Or skip the browser setup

If this report work is part of a workflow that also needs screenshots of tested pages, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. It does not generate Mocha test reports; it can capture the pages your tests exercise.

cURL:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

See the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.

FAQ

Does Mochawesome replace Mocha?

No. Mocha runs the tests; Mochawesome reports their results.

Can I keep JSON but skip HTML?

Yes. Set html=false and leave json=true in the reporter options.

Can I generate HTML from a report created earlier?

Yes. Pass the Mochawesome JSON file to the separate marge generator.

Is parallel mode’s extra require optional?

Mochawesome documents --require mochawesome/register for parallel mode. Include it in that invocation.