1 | # mochawesome
|
2 |
|
3 | [![npm](https://img.shields.io/npm/v/mochawesome.svg?style=flat-square)](http://www.npmjs.com/package/mochawesome) ![Node.js CI](https://github.com/adamgruber/mochawesome/workflows/Node.js%20CI/badge.svg) [![Gitter](https://img.shields.io/gitter/room/nwjs/nw.js.svg?style=flat-square)](https://gitter.im/mochawesome/general)
|
4 |
|
5 | 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.
|
6 |
|
7 | ## Features
|
8 |
|
9 | <img align="right" src="./docs/marge-report-1.0.1.png" alt="Mochawesome Report" width="55%" />
|
10 |
|
11 | - Simple, clean, and modern design
|
12 | - Beautiful charts (via ChartJS)
|
13 | - Support for test and suite nesting
|
14 | - Displays before and after hooks
|
15 | - Review test code inline
|
16 | - Stack trace for failed tests
|
17 | - Support for adding context information to tests
|
18 | - Filters to display only the tests you want
|
19 | - Responsive and mobile-friendly
|
20 | - Offline viewing
|
21 | - Supports `parallel` mode
|
22 |
|
23 | ## Usage
|
24 |
|
25 | 1. Add Mochawesome to your project:
|
26 |
|
27 | `npm install --save-dev mochawesome`
|
28 |
|
29 | 2. Tell mocha to use the Mochawesome reporter:
|
30 |
|
31 | `mocha testfile.js --reporter mochawesome`
|
32 |
|
33 | 3. If using mocha programatically:
|
34 |
|
35 | ```js
|
36 | var mocha = new Mocha({
|
37 | reporter: 'mochawesome',
|
38 | });
|
39 | ```
|
40 |
|
41 | ### Parallel Mode
|
42 |
|
43 | 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.
|
44 |
|
45 | `mocha tests --reporter mochawesome --require mochawesome/register`
|
46 |
|
47 | ### Output
|
48 |
|
49 | Mochawesome generates the following inside your project directory:
|
50 |
|
51 | ```
|
52 | mochawesome-report/
|
53 | ├── assets
|
54 | │ ├── app.css
|
55 | │ ├── app.js
|
56 | │ ├── MaterialIcons-Regular.woff
|
57 | │ ├── MaterialIcons-Regular.woff2
|
58 | │ ├── roboto-light-webfont.woff
|
59 | │ ├── roboto-light-webfont.woff2
|
60 | │ ├── roboto-medium-webfont.woff
|
61 | │ ├── roboto-medium-webfont.woff2
|
62 | │ ├── roboto-regular-webfont.woff
|
63 | │ └── roboto-regular-webfont.woff2
|
64 | ├── mochawesome.html
|
65 | └── mochawesome.json
|
66 | ```
|
67 |
|
68 | The two main files to be aware of are:
|
69 |
|
70 | **mochawesome.html** - The rendered report file
|
71 |
|
72 | **mochawesome.json** - The raw json output used to render the report
|
73 |
|
74 | ### Options
|
75 |
|
76 | Options can be passed to the reporter in two ways.
|
77 |
|
78 | #### Environment variables
|
79 |
|
80 | The reporter will try to read environment variables that begin with `MOCHAWESOME_`.
|
81 |
|
82 | ```bash
|
83 | $ export MOCHAWESOME_REPORTFILENAME=customReportFilename
|
84 | ```
|
85 |
|
86 | _Note that environment variables must be in uppercase._
|
87 |
|
88 | #### Mocha reporter-options
|
89 |
|
90 | 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.
|
91 |
|
92 | ```bash
|
93 | $ mocha test.js --reporter mochawesome --reporter-options reportDir=customReportDir,reportFilename=customReportFilename
|
94 | ```
|
95 |
|
96 | Alternately, `reporter-options` can be passed in programatically:
|
97 |
|
98 | ```js
|
99 | var mocha = new Mocha({
|
100 | reporter: 'mochawesome',
|
101 | reporterOptions: {
|
102 | reportFilename: 'customReportFilename',
|
103 | quiet: true,
|
104 | },
|
105 | });
|
106 | ```
|
107 |
|
108 | #### Available Options
|
109 |
|
110 | The options below are specific to the reporter. For a list of all available options see [mochawesome-report-generator options][marge-options].
|
111 |
|
112 | | Option Name | Type | Default | Description |
|
113 | | :---------------- | :------ | :---------- | :-------------------------------------------------------------------------------------------------------------------------------- |
|
114 | | `quiet` | boolean | false | Silence console messages |
|
115 | | `reportFilename` | string | mochawesome | Filename of saved report (html and json) <br> _See [notes](#reportfilename-replacement-tokens) for available token replacements._ |
|
116 | | `html` | boolean | true | Save the HTML output for the test run |
|
117 | | `json` | boolean | true | Save the JSON output for the test run |
|
118 | | `consoleReporter` | string | spec | Name of mocha reporter to use for console output, or `none` to disable console report output entirely |
|
119 |
|
120 | #### reportFilename replacement tokens
|
121 |
|
122 | Using the following tokens it is possible to dynamically alter the filename of the generated report.
|
123 |
|
124 | - **[name]** will be replaced with the spec filename when possible.
|
125 | - **[status]** will be replaced with the status (pass/fail) of the test run.
|
126 | - **[datetime]** will be replaced with a timestamp. The format can be - specified using the `timestamp` option.
|
127 |
|
128 | For example, given the spec `cypress/integration/sample.spec.js` and the following config:
|
129 |
|
130 | ```
|
131 | {
|
132 | reporter: "mochawesome",
|
133 | reporterOptions: {
|
134 | reportFilename: "[status]_[datetime]-[name]-report",
|
135 | timestamp: "longDate"
|
136 | }
|
137 | }
|
138 | ```
|
139 |
|
140 | The resulting report file will be named `pass_February_23_2022-sample-report.html`
|
141 |
|
142 | **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.
|
143 |
|
144 | ### Adding Test Context
|
145 |
|
146 | 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.
|
147 |
|
148 | **Please note: arrow functions will not work with `addContext`.** See the [example](#example).
|
149 |
|
150 | ### `addContext(testObj, context)`
|
151 |
|
152 | | param | type | description |
|
153 | | :------ | :------------- | :---------------------------------- |
|
154 | | testObj | object | The test object |
|
155 | | context | string\|object | The context to be added to the test |
|
156 |
|
157 | **Context as a string**
|
158 |
|
159 | 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.
|
160 |
|
161 | **Context as an object**
|
162 |
|
163 | Context passed as an object must adhere to the following shape:
|
164 |
|
165 | ```js
|
166 | {
|
167 | title: 'some title'; // must be a string
|
168 | value: {
|
169 | } // can be anything
|
170 | }
|
171 | ```
|
172 |
|
173 | #### Example
|
174 |
|
175 | Be sure to use ES5 functions and not ES6 arrow functions when using `addContext` to ensure `this` references the test object.
|
176 |
|
177 | ```js
|
178 | const addContext = require('mochawesome/addContext');
|
179 |
|
180 | describe('test suite', function () {
|
181 | it('should add context', function () {
|
182 | // context can be a simple string
|
183 | addContext(this, 'simple string');
|
184 |
|
185 | // context can be a url and the report will create a link
|
186 | addContext(this, 'http://www.url.com/pathname');
|
187 |
|
188 | // context can be an image url and the report will show it inline
|
189 | addContext(this, 'http://www.url.com/screenshot-maybe.jpg');
|
190 |
|
191 | // context can be an object with title and value properties
|
192 | addContext(this, {
|
193 | title: 'expected output',
|
194 | value: {
|
195 | a: 1,
|
196 | b: '2',
|
197 | c: 'd',
|
198 | },
|
199 | });
|
200 | });
|
201 | });
|
202 | ```
|
203 |
|
204 | It is also possible to use `addContext` from within a `beforeEach` or `afterEach` test hook.
|
205 |
|
206 | ```js
|
207 | describe('test suite', () => {
|
208 | beforeEach(function () {
|
209 | addContext(this, 'some context');
|
210 | });
|
211 |
|
212 | afterEach(function () {
|
213 | addContext(this, {
|
214 | title: 'afterEach context',
|
215 | value: { a: 1 },
|
216 | });
|
217 | });
|
218 |
|
219 | it('should display with beforeEach and afterEach context', () => {
|
220 | // assert something
|
221 | });
|
222 | });
|
223 | ```
|
224 |
|
225 | ## Typescript
|
226 |
|
227 | This project does not maintain its own type definitions, however they are available on npm from [DefinitelyTyped](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/mochawesome).
|
228 |
|
229 | ```
|
230 | $ npm install --save-dev @types/mochawesome
|
231 | ```
|
232 |
|
233 | ## Related
|
234 |
|
235 | [mochawesome-report-generator][marge]
|
236 |
|
237 | ## License
|
238 |
|
239 | mochawesome is [MIT licensed][license].
|
240 |
|
241 | [mocha]: https://mochajs.org/
|
242 | [marge]: https://github.com/adamgruber/mochawesome-report-generator
|
243 | [marge-options]: https://github.com/adamgruber/mochawesome-report-generator#options
|
244 | [changelog]: CHANGELOG.md
|
245 | [license]: LICENSE.md
|