external@serenity-js/mocha
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!