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

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

See the Serenity/JS Installation Guide.

Quick Start

`typescript
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

$3

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):

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

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

Next, run Mocha as follows:

`console
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:

`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):

`typescript
// 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:

`yaml title=".mocharc.yml"
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

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

$3

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:

`typescript title="wdio.conf.ts"
// 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.

$3

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:

`typescript title="protractor.conf.js"
// 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.