@serenity-js/mocha

Serenity/JS Mocha

@serenity-js/mocha brings full Serenity reporting capabilities to Mocha and enables writing tests using the Screenplay Pattern.

Features

• Enables Screenplay Pattern APIs in Mocha tests
• Supports all Serenity/JS reporting features
• TypeScript-first design with strong typing for safer and more predictable test code.

Installation

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

See the Serenity/JS Installation Guide.

Quick Start

import { actorCalled } from '@serenity-js/core';
import { describe, it } from 'mocha';

describe('Example Test', () => {
    it('supports actors', async () => {
        await actorCalled('Alice').attemptsTo(
            // Add tasks and interactions here
        )
    })
})

Explore practical examples and in-depth explanations in the Serenity/JS Handbook.

Reporting

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 serenity.config.js file (for example under spec/support/serenity.config.js, but you can use any location you like):

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

configure({
    crew: [
      '@serenity-js/console-reporter',
    ],
})

Next, run Mocha as follows:

mocha --reporter=@serenity-js/mocha \
      --require=spec/support/serenity.config.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": {
    "lib": ["ES2023"],
    "module": "nodenext",
    "target": "ES2023"
  }
}

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

// spec/support/setup.ts
import { configure } from '@serenity-js/core'

configure({
  crew: [
    '@serenity-js/console-reporter',
  ],
})

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

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/serenity.config.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 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.

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.

Documentation

• API Reference
• Screenplay Pattern Guide
• Serenity/JS Project Templates
• More examples and reference implementations
• Tutorial: First Web Scenario
• Tutorial: First API Scenario

Contributing

Contributions of all kinds are welcome! Get started with the Contributing Guide.

Community

• Community Chat
• Discussions Forum
  • Visit the How to... ? section for answers to common questions

If you enjoy using Serenity/JS, make sure to star ️ Serenity/JS on GitHub to help others discover the framework!

License

The Serenity/JS code base is licensed under the Apache-2.0 license, while its documentation and the Serenity/JS Handbook are licensed under the Creative Commons BY-NC-SA 4.0 International.

See the Serenity/JS License.

Support

Support ongoing development through GitHub Sponsors. Sponsors gain access to Serenity/JS Playbooks and priority help in the Discussions Forum.

For corporate sponsorship or commercial support, please contact Jan Molak.