mochawesome

![npm](http://www.npmjs.com/package/mochawesome) !Node.js CI ![Gitter](https://gitter.im/mochawesome/general)

Mochawesome is a custom reporter for use with the Javascript testing framework, [mocha][mocha]. It runs on Node.js (>=10) and works in conjunction with [mochawesome-report-generator][marge] to generate a standalone HTML/CSS report to help visualize your test runs.

Features

Mochawesome Report

- Simple, clean, and modern design
- Beautiful charts (via ChartJS)
- Support for test and suite nesting
- Displays before and after hooks
- Review test code inline
- Stack trace for failed tests
- Support for adding context information to tests
- Filters to display only the tests you want
- Responsive and mobile-friendly
- Offline viewing
- Supports parallel mode

Usage

1. Add Mochawesome to your project:

npm install --save-dev mochawesome

2. Tell mocha to use the Mochawesome reporter:

mocha testfile.js --reporter mochawesome

3. If using mocha programatically:

``js var mocha = new Mocha({ reporter: 'mochawesome', });`

`$3`

Since mocha@8 test files can be run in parallel using the --parallel flag. In order for mochawesome to work properly it needs to be registered as a hook.

mocha tests --reporter mochawesome --require mochawesome/register

`$3`

Mochawesome generates the following inside your project directory:

`mochawesome-report/ ├── assets │ ├── app.css │ ├── app.js │ ├── MaterialIcons-Regular.woff │ ├── MaterialIcons-Regular.woff2 │ ├── roboto-light-webfont.woff │ ├── roboto-light-webfont.woff2 │ ├── roboto-medium-webfont.woff │ ├── roboto-medium-webfont.woff2 │ ├── roboto-regular-webfont.woff │ └── roboto-regular-webfont.woff2 ├── mochawesome.html └── mochawesome.json`

The two main files to be aware of are:

mochawesome.html - The rendered report file

mochawesome.json - The raw json output used to render the report

`$3`

Options can be passed to the reporter in two ways.

#### Environment variables

The reporter will try to read environment variables that begin with MOCHAWESOME_.

`bash $ export MOCHAWESOME_REPORTFILENAME=customReportFilename`

_Note that environment variables must be in uppercase._

#### Mocha reporter-options

You can pass comma-separated options to the reporter via mocha's --reporter-options flag. Options passed this way will take precedence over environment variables.

`bash $ mocha test.js --reporter mochawesome --reporter-options reportDir=customReportDir,reportFilename=customReportFilename`

Alternately, reporter-options can be passed in programatically:

`js var mocha = new Mocha({ reporter: 'mochawesome', reporterOptions: { reportFilename: 'customReportFilename', quiet: true, }, });`

#### Available Options

The options below are specific to the reporter. For a list of all available options see [mochawesome-report-generator options][marge-options].

#### reportFilename replacement tokens

Using the following tokens it is possible to dynamically alter the filename of the generated report.

- [name] will be replaced with the spec filename when possible. - [status] will be replaced with the status (pass/fail) of the test run. - [datetime] will be replaced with a timestamp. The format can be - specified using thetimestamp option.

For example, given the spec cypress/integration/sample.spec.js and the following config:

`{ reporter: "mochawesome", reporterOptions: { reportFilename: "[status]_[datetime]-[name]-report", timestamp: "longDate" } }`

The resulting report file will be named pass_February_23_2022-sample-report.html

Note: The [name] replacement only occurs when mocha is running one spec file per process and outputting a separate report for each spec. The most common use-case is with Cypress.

`$3`

Mochawesome ships with an addContext helper method that can be used to associate additional information with a test. This information will then be displayed inside the report.

Please note: arrow functions will not work with addContext. See the example.

`$3`

Context as a string

Simple strings will be displayed as is. If you pass a URL, the reporter will attempt to turn it into a link. If the URL links to an image or video, it will be shown inline.

Context as an object

Context passed as an object must adhere to the following shape:

`js { title: 'some title'; // must be a string value: { } // can be anything }`

#### Example

Be sure to use ES5 functions and not ES6 arrow functions when using addContext to ensure this references the test object.

`js const addContext = require('mochawesome/addContext');

describe('test suite', function () { it('should add context', function () { // context can be a simple string addContext(this, 'simple string');

// context can be a url and the report will create a link addContext(this, 'http://www.url.com/pathname');

// context can be an image url and the report will show it inline addContext(this, 'http://www.url.com/screenshot-maybe.jpg');

// context can be an object with title and value properties addContext(this, { title: 'expected output', value: { a: 1, b: '2', c: 'd', }, }); }); });`

It is also possible to use addContext from within a beforeEach or afterEach test hook.

`js describe('test suite', () => { beforeEach(function () { addContext(this, 'some context'); });

afterEach(function () { addContext(this, { title: 'afterEach context', value: { a: 1 }, }); });

it('should display with beforeEach and afterEach context', () => { // assert something }); });`

`Typescript`

This project does not maintain its own type definitions, however they are available on npm from DefinitelyTyped.

`$ npm install --save-dev @types/mochawesome``

[mochawesome-report-generator][marge]

License

mochawesome is [MIT licensed][license].

[mocha]: https://mochajs.org/
[marge]: https://github.com/adamgruber/mochawesome-report-generator
[marge-options]: https://github.com/adamgruber/mochawesome-report-generator#options
[changelog]: CHANGELOG.md
[license]: LICENSE.md