|
| 1 | +Mocha allows you to define and use custom reporters install via `npm`. |
| 2 | + |
| 3 | +For example, if `mocha-foo-reporter` was published to the npm registry, you could install it via `npm install mocha-foo-reporter --save-dev`, then use it via `mocha --reporter mocha-foo-reporter`. |
| 4 | + |
| 5 | +## Example Custom Reporter |
| 6 | + |
| 7 | +If you're looking to get started quickly, here's an example of a custom reporter: |
| 8 | + |
| 9 | +<!-- AUTO-GENERATED-CONTENT:START (file:src=../../test/integration/fixtures/simple-reporter.js&header=// my-reporter.js)' --> |
| 10 | + |
| 11 | +```js |
| 12 | +// my-reporter.js |
| 13 | +'use strict'; |
| 14 | + |
| 15 | +const Mocha = require('mocha'); |
| 16 | +const { |
| 17 | + EVENT_RUN_BEGIN, |
| 18 | + EVENT_RUN_END, |
| 19 | + EVENT_TEST_FAIL, |
| 20 | + EVENT_TEST_PASS, |
| 21 | + EVENT_SUITE_BEGIN, |
| 22 | + EVENT_SUITE_END |
| 23 | +} = Mocha.Runner.constants; |
| 24 | + |
| 25 | +// this reporter outputs test results, indenting two spaces per suite |
| 26 | +class MyReporter { |
| 27 | + constructor(runner) { |
| 28 | + this._indents = 0; |
| 29 | + const stats = runner.stats; |
| 30 | + |
| 31 | + runner |
| 32 | + .once(EVENT_RUN_BEGIN, () => { |
| 33 | + console.log('start'); |
| 34 | + }) |
| 35 | + .on(EVENT_SUITE_BEGIN, () => { |
| 36 | + this.increaseIndent(); |
| 37 | + }) |
| 38 | + .on(EVENT_SUITE_END, () => { |
| 39 | + this.decreaseIndent(); |
| 40 | + }) |
| 41 | + .on(EVENT_TEST_PASS, test => { |
| 42 | + // Test#fullTitle() returns the suite name(s) |
| 43 | + // prepended to the test title |
| 44 | + console.log(`${this.indent()}pass: ${test.fullTitle()}`); |
| 45 | + }) |
| 46 | + .on(EVENT_TEST_FAIL, (test, err) => { |
| 47 | + console.log( |
| 48 | + `${this.indent()}fail: ${test.fullTitle()} - error: ${err.message}` |
| 49 | + ); |
| 50 | + }) |
| 51 | + .once(EVENT_RUN_END, () => { |
| 52 | + console.log(`end: ${stats.passes}/${stats.passes + stats.failures} ok`); |
| 53 | + }); |
| 54 | + } |
| 55 | + |
| 56 | + indent() { |
| 57 | + return Array(this._indents).join(' '); |
| 58 | + } |
| 59 | + |
| 60 | + increaseIndent() { |
| 61 | + this._indents++; |
| 62 | + } |
| 63 | + |
| 64 | + decreaseIndent() { |
| 65 | + this._indents--; |
| 66 | + } |
| 67 | +} |
| 68 | + |
| 69 | +module.exports = MyReporter; |
| 70 | +``` |
| 71 | + |
| 72 | +<!-- AUTO-GENERATED-CONTENT:END --> |
| 73 | + |
| 74 | +To use this reporter, execute `mocha --reporter /path/to/my-reporter.js`. |
| 75 | + |
| 76 | +For further examples, the built-in reporter implementations are the [best place to look](https://github.com/mochajs/mocha/tree/master/lib/reporters). The [integration tests](https://github.com/mochajs/mocha/tree/master/test/reporters) may also be helpful. |
| 77 | + |
| 78 | +## The `Base` Reporter Class |
| 79 | + |
| 80 | +[Base] is an "abstract" class. It contains console-specific settings and utilities, commonly used by built-in reporters. Browsing the built-in reporter implementations, you may often see static properties of [Base] referenced. |
| 81 | + |
| 82 | +It's often useful--but not necessary--for a custom reporter to extend [Base]. |
| 83 | + |
| 84 | +## Statistics |
| 85 | + |
| 86 | +Mocha adds a `stats` property of type [StatsCollector](/api/module-lib_stats-collector.html) to the reporter's `Runner` instance (passed as first argument to constructor). |
| 87 | + |
| 88 | +## Events |
| 89 | + |
| 90 | +A reporter should listen for events emitted from the `runner` (a singleton instance of [Runner]). |
| 91 | + |
| 92 | +The event names are exported from the `constants` property of `Mocha.Runner`: |
| 93 | + |
| 94 | +| Constant | Event Name | Event Arguments | Description | |
| 95 | +| -------------------- | ----------- | --------------- | ------------------------------------------------------------------------------------------- | |
| 96 | +| `EVENT_RUN_BEGIN` | `start` | _(n/a)_ | Execution will begin. | |
| 97 | +| `EVENT_RUN_END` | `end` | _(n/a)_ | All [Suite]s, [Test]s and [Hook]s have completed execution. | |
| 98 | +| `EVENT_DELAY_BEGIN` | `waiting` | _(n/a)_ | Waiting for `global.run()` to be called; only emitted when [delay] option is `true`. | |
| 99 | +| `EVENT_DELAY_END` | `ready` | _(n/a)_ | User called `global.run()` and the root suite is ready to execute. | |
| 100 | +| `EVENT_SUITE_BEGIN` | `suite` | `Suite` | The [Hook]s and [Test]s within a [Suite] will be executed, including any nested [Suite]s. | |
| 101 | +| `EVENT_SUITE_END` | `suite end` | `Suite` | The [Hook]s, [Test]s, and nested [Suite]s within a [Suite] have completed execution. | |
| 102 | +| `EVENT_HOOK_BEGIN` | `hook` | `Hook` | A [Hook] will be executed. | |
| 103 | +| `EVENT_HOOK_END` | `hook end` | `Hook` | A [Hook] has completed execution. | |
| 104 | +| `EVENT_TEST_BEGIN` | `test` | `Test` | A [Test] will be executed. | |
| 105 | +| `EVENT_TEST_END` | `test end` | `Test` | A [Test] has completed execution. | |
| 106 | +| `EVENT_TEST_FAIL` | `fail` | `Test`, `Error` | A [Test] has failed or thrown an exception. | |
| 107 | +| `EVENT_TEST_PASS` | `pass` | `Test` | A [Test] has passed. | |
| 108 | +| `EVENT_TEST_PENDING` | `pending` | `Test` | A [Test] was skipped. | |
| 109 | +| `EVENT_TEST_RETRY` | `retry` | `Test`, `Error` | A [Test] failed, but is about to be retried; only emitted if the `retry` option is nonzero. | |
| 110 | + |
| 111 | +**Please use these constants** instead of the event names in your own reporter! This will ensure compatibility with future versions of Mocha. |
| 112 | + |
| 113 | +> It's important to understand that all `Suite` callbacks will be run _before_ the [Runner] emits `EVENT_RUN_BEGIN`. Hooks and tests, however, won't run until _after_ the [Runner] emits `EVENT_RUN_BEGIN`. |
| 114 | +
|
| 115 | +[runner]: /api/mocha.runner |
| 116 | +[test]: /api/mocha.test |
| 117 | +[hook]: /api/mocha.hook |
| 118 | +[suite]: /api/mocha.suite |
| 119 | +[base]: /api/mocha.reporters.base |
| 120 | +[delay]: /#delayed-root-suite |
0 commit comments