Serenity/JS is a Node.js library designed to make acceptance and regression testing of modern full-stack applications faster, more collaborative and easier to scale.

Serenity/JS Mocha

The @serenity-js/mocha module contains an adaptor that can be registered with the Mocha test runner to enable integration between Mocha and Serenity/JS.


Install Mocha version 8.x or newer:

npm install --save-dev mocha@8.x

Install the @serenity-js/mocha adaptor, as well as @serenity-js/core and any Serenity/JS reporting modules you'd like to use, for example @serenity-js/console-reporter:

npm install --save-dev @serenity-js/mocha @serenity-js/core @serenity-js/console-reporter

Usage with standalone Mocha

To use Serenity/JS with standalone Mocha, for example to run tests of REST APIs, you'll need a setup file that configures Serenity/JS reporting services.


If you're writing your tests in JavaScript, create a setup.js file (for example under spec/support/setup.js, but you can use any location you like):

// spec/support/setup.js

    { ConsoleReporter } = require('@serenity-js/console-reporter'),
    { configure } = require('@serenity-js/core');

    crew: [

Next, run Mocha as follows:

mocha --reporter=@serenity-js/mocha \
      --require=spec/support/setup.js \


If you're writing your tests in TypeScript, you might want to run them via ts-node, which transpiles TypeScript in memory without you having to do it before every test run.

npm install --save-dev typescript ts-node

If you haven't done so already, configure your TypeScript transpiler via tsconfig.json:

  "compilerOptions": {
    "target": "es2018",
    "lib": ["es2018"],
    "module": "commonjs"

Create a setup.ts file (for example under spec/support/setup.ts, but you can use any location you like):

// spec/support/setup.ts

import { ConsoleReporter } from '@serenity-js/console-reporter';
import { configure } from '@serenity-js/core';

    crew: [

Next, run Mocha as follows:

mocha --reporter=@serenity-js/mocha \
      --require=ts-node/register \
      --require=spec/support/setup.ts \

Using Mocha configuration file

Please note that you can use Mocha configuration file to simplify your command line execution.

For example:

# .mocharc.yml
reporter: '@serenity-js/mocha'
  - ts-node/register
  - spec/support/setup.ts
check-leaks: false
timeout: 5000
v8-stack-trace-limit: 100
# ...other config

Usage with Protractor

Configure your Protractor installation as per instructions in @serenity-js/protractor module.

Next, instruct Serenity/JS to run your tests using Mocha. You can also use your protractor.conf.js file to configure Mocha if needed:

// protractor.conf.js

exports.config = {
    // Tell Protractor to use the Serenity/JS framework Protractor Adapter
    framework:      'custom',
    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),

    serenity: {
        runner: 'mocha',        // Use Mocha
        // ... other Serenity/JS-specific configuration

    mochaOpts: {
        // Mocha-specific configuration

    // ... other Protractor-specific configuration   

Learn more about supported Mocha configuration options.

Example projects

Study Serenity/JS example projects to learn more.