@serenity-js/mocha

Serenity/JS

Serenity/JS is an innovative open-source framework designed to make acceptance and regression testing of complex software systems faster, more collaborative and easier to scale.

⭐️ Get started with Serenity/JS!

• Serenity/JS web testing tutorial
• Serenity/JS Handbook and Getting Started guides
• API documentation
• Serenity/JS Project Templates

👋 Join the Serenity/JS Community!

• Meet other Serenity/JS developers and maintainers on the Serenity/JS Community chat channel,
• Find answers to your Serenity/JS questions on the Serenity/JS Forum,
• Learn how to contribute to Serenity/JS,
• Support the project and gain access to Serenity/JS Playbooks by becoming a Serenity/JS GitHub Sponsor!

Serenity/JS Mocha

@serenity-js/mocha contains an adapter you register with Mocha test runner to enable integration between Mocha and Serenity/JS.

Installation

Install Mocha version 8.x or newer:

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

Install the @serenity-js/mocha adapter, 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/core @serenity-js/console-reporter @serenity-js/mocha

To learn more about Serenity/JS and how to use it on your project, follow the Serenity/JS Getting Started guide.

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.

JavaScript

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

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

configure({
    crew: [
        ConsoleReporter.forDarkTerminals(),
    ],
})

Next, run Mocha as follows:

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

TypeScript

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'

configure({
    crew: [
        ConsoleReporter.forDarkTerminals(),
    ],
})

Next, run Mocha as follows:

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

Using Mocha configuration file

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

For example:

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

Configuring a custom requirements hierarchy root

reporter: '@serenity-js/mocha'
reporter-options:       # Note: array, not an object
  - 'specDirectory=e2e' # Configure custom requirements hierarchy root, such as "e2e"

Using Serenity/JS Mocha 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 adapter
    framework:      'custom',
    frameworkPath:  require.resolve('@serenity-js/protractor/adapter'),
  
    serenity: {
        runner: 'mocha',        // Use Mocha
        // ... other Serenity/JS-specific configuration
    },

    mochaOpts: {
        // Custom requirements hierarchy root, optional 
        reporterOptions: [
            'specDirectory=e2e'
        ],
        
        // ... other Mocha-specific configuration
    },

    // ... other Protractor-specific configuration   
}

Learn more about supported Mocha configuration options.

Using Serenity/JS Mocha with WebdriverIO

Configure your WebdriverIO installation as per instructions in @serenity-js/webdriverio module.

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

// wdio.conf.ts

export const config = {
    // Tell WebdriverIO to use the Serenity/JS framework adapter
    framework: '@serenity-js/webdriverio',

    // Serenity/JS configuration
    serenity: {
        // Configure Serenity/JS to use an appropriate test runner adapter
        runner: 'mocha',        // Use Mocha
        // ... other Serenity/JS-specific configuration
    },

    mochaOpts: {
        // Custom requirements hierarchy root, optional 
        reporterOptions: [
            'specDirectory=e2e'
        ],

        // ... other Mocha-specific configuration
    },

    // ... other Protractor-specific configuration   
}

Learn more about supported Mocha configuration options.

Example projects

Study Serenity/JS example projects to learn more.

📣 Stay up to date

New features, tutorials, and demos are coming soon! Follow Serenity/JS on LinkedIn, subscribe to Serenity/JS channel on YouTube and join the Serenity/JS Community Chat to stay up to date! Please also make sure to star ⭐️ Serenity/JS on GitHub to help others discover the framework!

💛 Support Serenity/JS

If you appreciate all the effort that goes into making sophisticated tools easy to work with, please support our work and become a Serenity/JS GitHub Sponsor today!

Changelog

3.31.8 (2025-02-04)

Bug Fixes

• deps: update dependency semver to v7.7.1 (640931b)
• deps: update playwright dependencies to v1.50.1 (66f4946)
• deps: update webdriverio dependencies to ^9.7.2 (26b0d4b)