0
# Mocha Multi Reporters
1

2
Mocha Multi Reporters is a Mocha reporter plugin that enables generating multiple test reports in a single test execution run. It allows developers to configure and use multiple Mocha reporters simultaneously, such as spec, xunit, json, and other built-in or custom reporters, through a simple configuration file.
3

4
## Package Information
5

6
- **Package Name**: mocha-multi-reporters
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install mocha-multi-reporters --save-dev`
10

11
## Core Imports
12

13
```javascript
14
const MultiReporters = require('mocha-multi-reporters');
15
```
16

17
ES6 imports:
18

19
```javascript
20
import MultiReporters from 'mocha-multi-reporters';
21
```
22

23
## Basic Usage
24

25
The most common usage is to configure it as a Mocha reporter with a configuration file:
26

27
```bash
28
# Basic usage with default config
29
./node_modules/.bin/mocha --reporter mocha-multi-reporters
30

31
# Using custom configuration file
32
./node_modules/.bin/mocha --reporter mocha-multi-reporters --reporter-options configFile=config.json
33
```
34

35
Example configuration file:
36

37
```json
38
{
39
  "reporterEnabled": "spec, json, xunit",
40
  "jsonReporterOptions": {
41
    "output": "test-results.json"
42
  },
43
  "xunitReporterOptions": {
44
    "output": "test-results.xml"
45
  }
46
}
47
```
48

49
## Architecture
50

51
Mocha Multi Reporters extends Mocha's Base reporter class and acts as a meta-reporter that instantiates and coordinates multiple child reporters. It handles the lifecycle management of multiple reporters, ensuring proper initialization, event handling, and completion coordination.
52

53
## Capabilities
54

55
### Reporter Instantiation
56

57
Creates a MultiReporters instance that manages multiple child reporters.
58

59
```javascript { .api }
60
function MultiReporters(runner, options);
61
```
62

63
**Parameters:**
64
- `runner` (object): Mocha test runner instance
65
- `options` (object): Configuration options object
66

67
**Options object properties:**
68
- `execute` (boolean, default: true): Whether to execute reporter initialization
69
- `reporterOptions` (object): Reporter configuration options
70

71
### Completion Handling
72

73
Coordinates completion across multiple reporters with done callbacks.
74

75
```javascript { .api }
76
MultiReporters.prototype.done = function(failures, fn);
77
```
78

79
**Parameters:**
80
- `failures` (number): Number of test failures
81
- `fn` (function): Callback function to invoke when all reporters complete
82

83
### Configuration Management
84

85
#### Get Merged Options
86

87
Merges default, custom, and runtime options into a single configuration object.
88

89
```javascript { .api }
90
MultiReporters.prototype.getOptions = function(options);
91
```
92

93
**Parameters:**
94
- `options` (object): Raw options object
95

96
**Returns:** (object) Merged configuration options
97

98
#### Get Custom Options
99

100
Loads custom configuration from a file or options object.
101

102
```javascript { .api }
103
MultiReporters.prototype.getCustomOptions = function(options);
104
```
105

106
**Parameters:**
107
- `options` (object): Options containing configFile path or reporterOptions
108

109
**Returns:** (object) Custom configuration options
110

111
Supports both JSON and JavaScript configuration files. The configFile path is resolved relative to the current working directory.
112

113
#### Get Default Options
114

115
Loads the default configuration from the built-in config.json file.
116

117
```javascript { .api }
118
MultiReporters.prototype.getDefaultOptions = function();
119
```
120

121
**Returns:** (object) Default configuration options from config.json
122

123
#### Get Reporter-Specific Options
124

125
Extracts and processes options for a specific reporter by name.
126

127
```javascript { .api }
128
MultiReporters.prototype.getReporterOptions = function(options, name);
129
```
130

131
**Parameters:**
132
- `options` (object): Global options object
133
- `name` (string): Reporter name
134

135
**Returns:** (object) Reporter-specific configuration options
136

137
Reporter-specific options follow the pattern `{camelCaseName}ReporterOptions`. For example, options for the `xunit` reporter would be specified in `xunitReporterOptions`.
138

139
### Configuration Format
140

141
#### Basic Configuration
142

143
```javascript { .api }
144
interface ReporterConfig {
145
  reporterEnabled: string | string[];
146
  reporterOptions?: object;
147
  [reporterName + 'ReporterOptions']?: object;
148
  cmrOutput?: string | string[][];
149
}
150
```
151

152
#### Reporter Output Configuration
153

154
The `cmrOutput` option allows dynamic output file naming:
155

156
```javascript
157
{
158
  "reporterEnabled": "json, xunit",
159
  "cmrOutput": "json+output+results.json:xunit+output+results.xml"
160
}
161
```
162

163
Or as an array:
164

165
```javascript
166
{
167
  "reporterEnabled": "json, xunit", 
168
  "cmrOutput": [
169
    ["json", "output", "results.json"],
170
    ["xunit", "output", "results.xml"]
171
  ]
172
}
173
```
174

175
## Static Properties
176

177
### CONFIG_FILE
178

179
Path to the default configuration file.
180

181
```javascript { .api }
182
MultiReporters.CONFIG_FILE = '../config.json';
183
```
184

185
## Error Handling
186

187
The reporter handles several error conditions:
188

189
- **Missing reporters**: Logs error message when a specified reporter cannot be loaded
190
- **Invalid config files**: Throws errors when configuration files cannot be parsed
191
- **Module loading errors**: Attempts to load reporters from both npm modules and local paths
192

193
## Supported Reporter Types
194

195
The plugin supports:
196

197
- **Built-in Mocha reporters**: spec, json, xunit, tap, dot, etc.
198
- **External npm packages**: Any reporter published to npm
199
- **Local reporters**: Custom reporters in the local file system
200

201
## Instance Properties
202

203
### _reporters
204

205
Array of instantiated reporter instances.
206

207
```javascript { .api }
208
MultiReporters.prototype._reporters: Array<object>;
209
```
210

211
Each element in the array is an instantiated reporter object that follows Mocha's reporter interface.