How to Generate Awesome Mocha Reports with Mocha Awesome

In this article I show you how to generate HTML and JSON test result reports for MochaJS using Mocha Awesome.

Step 1. Clone the starter project

Use git to clone my starter repo into a new folder.

git clone mocha-awesome

cd mocha-awesome/

npm install

Run the default tests to make sure the install went okay:

npm test

Step 2. Install Mocha Awesome

Install the mochawesome package from npm as a dev dependency using the –save-dev flag.

npm install --save-dev mochawesome

Because it is only used for testing, it is saved as a dev dependency alongside mocha.

Step 3. Add a new test script to package.json

Edit package.json and add two new scripts after the basic test script:

"scripts": {
  "test": "mocha",
  "test:awesome": "mocha --reporter mochawesome || true",
  "open:report": "open mochawesome-report/mochawesome.html"

The scripts do the following:

  • test:awesome - the --reporter flag tells mocha to report the resuts to the mochawesome package
  • open:report - on a Mac this will open the generated report in a browser

I appended || true to the awesome script because mochawesome would report a confusing exit failure if a test failed. This makes the output a little cleaner and less confusing.

Step 4. Run the tests with the reporter

The starter repo already has some code defined in src/index.ts and tests defined in test/smoke-test.js. So we can use that to generate a report.

To run the tests and generate a report, run the test:awesome script:

npm run test:awesome

The output should look like this:

 > mocha --reporter mochawesome

  smoke test
    ✓ should pass if mocha is working
      ✓ should return an object that is not null
      greeting property
        ✓ should have a greeting property
        ✓ should return default greeting if not set
        ✓ should return set value
        ✓ should return constructor greeting if set
      greet method
        ✓ should have a greet method
Hello World!
        ✓ should be able to call greet method
Yo World!
        ✓ should be able to call greet method with new greeting

  9 passing (10ms)

[mochawesome] Report JSON saved to ./mochawesome-report/mochawesome.json

[mochawesome] Report HTML saved to ./mochawesome-report/mochawesome.html

At the end of the output you will see that two reports were generated. One in JSON format and the other in HTML format.

A new folder for the test results will be created automatically. That assumes that who or what is running the tests has the rights to create a new folder under your project.

Step 5. Open the report in your browser

On a Mac you can do it like this:

open ./mochawesome-report/mochawesome.html

I also had you add a script for Mac users that wraps that call. To open the results in a browser using the script:

npm run open:report

Expand one of the results to see the test details.

Step 6. Add a failing test

To see how the report looks for a fail, add a failing test to test/smoke-test.js like this:

it('should fail', done => {
  var hello = helloFactory.createHelloWorld();
  hello.greeting = 'Yo World!';
  hello.greet();'This test will fail too!');

Run the test again to generate the report:

npm run test:awesome

To see how the reporter handles a failing test, find the fail and expand it. You should also see an indicator of how many tests failed in the header of the report.


  • If mocha has trouble finding mochawesome, try installing them both globally
  • If the report folder cannot be created, check the rights of who or what is running the tests


In this article you learned how to:

  • Install a new mocha reporter (mochawesome)
  • Add a test script to generate a report from mocha
  • Open the report and expand the contents
  • Write a script to open the report in a browser
  • Fail a test to see how the reporter handles it


  • mochawesome-report-generator (marge) [1]

About the Author

Mitch Allen has worked for software companies in Silicon Valley, along Boston’s Route 128 and in New York’s Silicon Alley. He currently works for a robotics company in Massachusetts.