Generate Custom Cypress Test Reports with Mochawesome (2026)

Mochawesome is a custom reporter for Mocha, a JavaScript test framework, that generates charming, easily readable HTML reports for your test runs.

Imagine you’ve got a suite of Cypress tests. By default, Cypress gives you a decent terminal output and a basic HTML report, but it’s not always the most insightful or visually appealing. Mochawesome steps in to transform that raw test data into a rich, interactive report that makes debugging and understanding your test results much easier.

Here’s a Cypress test file (cypress/e2e/example.cy.js):

describe('My First Test', () => {
  it('Visits the app and checks the title', () => {
    cy.visit('https://example.cypress.io/');
    cy.get('h1').should('contain', 'Kitchen Sink');
  });

  it('Finds an element and clicks it', () => {
    cy.visit('https://example.cypress.io/');
    cy.contains('type').click();
    cy.url().should('include', '/commands/actions');
  });
});

To use Mochawesome, you first need to install it as a dev dependency:

npm install --save-dev mochawesome
# or
yarn add --dev mochawesome

Next, you need to tell Cypress to use Mochawesome as its reporter. You do this in your cypress.config.js (or cypress.json if you’re on an older version). Add the following configuration:

const { defineConfig } = require('cypress');

module.exports = defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here
    },
    reporter: 'mochawesome',
    reporterOptions: {
      charts: true,
      overwrite: false,
      html: true,
      json: true,
      reportDir: 'cypress/results',
    },
  },
});

Let’s break down reporterOptions:

• charts: true: This enables charts within the report, showing pass/fail rates and other statistics.
• overwrite: false: If set to true, it will overwrite existing report files. false will append a timestamp to new report files.
• html: true: Generates an HTML report.
• json: true: Generates a JSON report, which is useful for CI/CD systems or further processing.
• reportDir: 'cypress/results': Specifies the directory where the reports will be saved. This is a common convention to keep reports organized.

Now, when you run your Cypress tests (e.g., npx cypress run --e2e), Cypress will execute your tests and, upon completion, generate an HTML report in the cypress/results directory. You’ll find a file named something like mochawesome.html. Open this file in your browser.

You’ll see a beautifully laid-out report. It lists your test suites and individual tests, clearly indicating which ones passed and failed. For failed tests, it provides detailed information, including the error message, the stack trace, and crucially, screenshots and videos of the test run (if configured in Cypress). The interactive nature allows you to expand and collapse test suites, making it easy to navigate through a large number of tests.

The core problem Mochawesome solves is the lack of detailed, human-readable reporting in automated testing. While terminal output is great for quick feedback during development, it’s often insufficient for understanding complex failures or for sharing test results with stakeholders who aren’t deeply technical. Mochawesome bridges this gap by providing a clear, visual representation of your test execution.

Internally, Mochawesome hooks into Mocha’s event system. When Mocha finishes a test run, it emits events like test end, suite end, and run end. Mochawesome listens for these events, collects the test results (status, duration, errors, titles, etc.), and then uses these aggregated results to generate the HTML and JSON files. The HTML generation involves templating, where the collected data is injected into an HTML structure to create the interactive report.

The reporterOptions are your primary levers for controlling the output. Beyond the basic options, you can customize the report title (reportTitle), add a console log for each test (log: true), and even integrate with other tools by generating a JSON report (json: true). The overwrite option is particularly useful in CI environments to ensure you always have the latest results without accumulating old ones.

One thing most people don’t realize is how easily Mochawesome can be integrated with Cypress’s built-in video recording and screenshot capabilities. When a test fails in Cypress, it automatically takes a screenshot. If you have video recording enabled (video: true in cypress.config.js), Cypress records the entire test run. Mochawesome then automatically picks up these artifacts and embeds them directly into the HTML report, providing a complete visual history of what happened during the test execution, right alongside the test steps.

The next step after generating comprehensive reports is often automating the distribution of these reports, perhaps by uploading them to a cloud storage service or integrating them into a dashboard.