Integrating with Mocha

Mocha.js is a universal test runner providing a number of useful features, such as automatic retry of failed tests. If your project already uses Mocha to run its unit tests, you can use the same runner for your acceptance tests too.

When you integrate Mocha with Serenity/JS, the framework augments your test reports with additional information about your test scenarios, even if they don't follow the Screenplay Pattern yet!

If you prefer to dive straight into the code, several reference implementations are available in the Serenity/JS GitHub repository. Those implementations demonstrate using Mocha and Serenity/JS to run both REST API- and Web-based acceptance tests.

Integration architecture

@serenity-js/mocha module provides a test runner adapter, or "reporter" in Mocha-speak.

Serenity/JS test runner adapters translate the events that occur in the test runner to Serenity/JS DomainEvents; those can be then turned into test reports by Serenity/JS reporting services.

graph TB DEV(["fas:fa-laptop-code Developer"]) TR(["mocha"]) SC(["@serenity-js/core"]) TRA(["@serenity-js/mocha"]) CF["fas:fa-file config.ts"] R(["fas:fa-chart-pie Serenity/JS reporting services"]) DEV -- invokes --> TR TR -- loads --> CF TR -- notifies --> TRA TRA -- notifies --> SC CF -- configures --> SC SC -- notifies --> R class R socket click R "/handbook/reporting/index.html" click SC "/modules/core" click TRA "/modules/mocha"

PRO TIP: Integration architecture described in this chapter is applicable when you want to invoke mocha command line interface directly, for example for domain-level or [REST/HTTP API-level](/modules/rest) testing.

If you want your Mocha scenarios to interact with Web interfaces, check out [Integrating with Protractor](/handbook/integration/serenityjs-and-protractor.html) instead.


Assuming you already have a Node.js project set up, add the following dev dependencies:

To do that, run the following command in your terminal:

npm install --save-dev @serenity-js/{core,mocha} mocha

If you'd like to implement your test suite in TypeScript, also run:

npm install --save-dev typescript ts-node @types/{mocha,node}


In a TypeScript project, create a configuration file in a location of your choosing, i.e. spec/config.ts. This file will inform Serenity/JS what reporting services you wish to use:

// spec/config.ts
import { configure } from '@serenity-js/core';

    crew: [
        // ... reporting services

In a JavaScript project, create a configuration file at spec/config.js instead:

// spec/config.js
const { configure } = require('@serenity-js/core');

    crew: [
        // ... reporting services

Learn more about Serenity/JS reporting.


To register @serenity-js/mocha test runner adapter with Mocha, use the --reporter option when invoking the runner.

For example, when running Mocha in a JavaScript project:

npx mocha --reporter '@serenity-js/mocha' \
    --require 'spec/config.js' \
    [... any other options]

To make Mocha support test scenarios and configuration written in TypeScript, you'll need to add a dev dependency on ts-node and register it via --require:

npx mocha --reporter '@serenity-js/mocha' \
    --require 'ts-node/register' \
    --require 'spec/config.ts' \ 
    [... any other options]

To install and configure Serenity/JS reporting services appropriate for your project - follow the Serenity/JS reporting guide.

Love Serenity/JS? Spread the word on Twitter and LinkedIn!

Found a typo? You can fix it yourself or raise a ticket on GitHub.

If you'd like to help us bring more great tools and content to the Open-Source Community, become a GitHub Sponsor of Serenity/JS for as little as the cost of a cup of coffee.