0
# Reporters and Output
1

2
Comprehensive reporting system with built-in reporters for various output formats and support for custom reporters. Reporters listen to Runner events and format test results.
3

4
## Capabilities
5

6
### Base Reporter Class
7

8
Foundation class for all reporters providing shared functionality.
9

10
```javascript { .api }
11
/**
12
 * Base reporter class that all reporters extend
13
 * @param runner - Runner instance that emits test events
14
 * @param options - Reporter-specific options
15
 */
16
class Base {
17
  constructor(runner, options);
18
  
19
  /**
20
   * Called when test run completes
21
   * @param failures - Number of failed tests
22
   * @param callback - Completion callback
23
   */
24
  done(failures, callback);
25
  
26
  /**
27
   * Output test run summary/epilogue
28
   */
29
  epilogue();
30
  
31
  /**
32
   * Get test statistics
33
   * @returns {Object} Statistics object
34
   */
35
  stats;
36
}
37

38
/**
39
 * Statistics object structure
40
 */
41
interface Stats {
42
  suites: number;      // Number of suites
43
  tests: number;       // Total number of tests
44
  passes: number;      // Number of passing tests
45
  pending: number;     // Number of pending tests
46
  failures: number;    // Number of failing tests
47
  duration: number;    // Total execution time in ms
48
  start: Date;         // Test run start time
49
  end: Date;          // Test run end time
50
}
51
```
52

53
### Built-in Reporters
54

55
#### Spec Reporter (Default)
56

57
Hierarchical output showing test structure and results.
58

59
```javascript { .api }
60
/**
61
 * Spec reporter - hierarchical test output
62
 */
63
class Spec extends Base {
64
  constructor(runner, options);
65
}
66
```
67

68
**Output Example:**
69
```
70
Calculator
71
  #add()
72
    ✓ should add positive numbers
73
    ✓ should handle negative numbers
74
    - should handle decimals (pending)
75
  #multiply()
76
    ✓ should multiply numbers
77
    1) should handle zero
78

79
1) Calculator #multiply() should handle zero:
80
   Error: Expected 0 but got NaN
81
```
82

83
#### Dot Reporter
84

85
Minimal dot-based progress output.
86

87
```javascript { .api }
88
/**
89
 * Dot reporter - minimal dot progress
90
 */
91
class Dot extends Base {
92
  constructor(runner, options);
93
}
94
```
95

96
**Output Example:**
97
```
98
..·..
99

100
  4 passing (12ms)
101
  1 pending
102
```
103

104
#### TAP Reporter
105

106
Test Anything Protocol output.
107

108
```javascript { .api }
109
/**
110
 * TAP reporter - Test Anything Protocol format
111
 */
112
class TAP extends Base {
113
  constructor(runner, options);
114
}
115
```
116

117
**Output Example:**
118
```
119
1..5
120
ok 1 Calculator #add() should add positive numbers
121
ok 2 Calculator #add() should handle negative numbers
122
ok 3 Calculator #multiply() should multiply numbers # SKIP
123
not ok 4 Calculator #multiply() should handle zero
124
  ---
125
  message: Expected 0 but got NaN
126
  severity: fail
127
  ...
128
```
129

130
#### JSON Reporter
131

132
Machine-readable JSON output.
133

134
```javascript { .api }
135
/**
136
 * JSON reporter - structured JSON output
137
 */
138
class JSON extends Base {
139
  constructor(runner, options);
140
}
141
```
142

143
#### HTML Reporter (Browser)
144

145
Browser-specific HTML output with interactive features.
146

147
```javascript { .api }
148
/**
149
 * HTML reporter - browser HTML output with DOM integration
150
 * Only available in browser environments
151
 */
152
class HTML extends Base {
153
  constructor(runner, options);
154
}
155
```
156

157
#### List Reporter
158

159
Simple list format showing all tests.
160

161
```javascript { .api }
162
/**
163
 * List reporter - simple list of all tests
164
 */
165
class List extends Base {
166
  constructor(runner, options);
167
}
168
```
169

170
#### Min Reporter
171

172
Minimal output showing only summary.
173

174
```javascript { .api }
175
/**
176
 * Min reporter - minimal summary output
177
 */
178
class Min extends Base {
179
  constructor(runner, options);
180
}
181
```
182

183
#### Nyan Reporter
184

185
Colorful Nyan Cat progress reporter.
186

187
```javascript { .api }
188
/**
189
 * Nyan reporter - colorful cat progress animation
190
 */
191
class Nyan extends Base {
192
  constructor(runner, options);
193
}
194
```
195

196
#### XUnit Reporter
197

198
XML output compatible with JUnit/xUnit format.
199

200
```javascript { .api }
201
/**
202
 * XUnit reporter - XML output for CI systems
203
 */
204
class XUnit extends Base {
205
  constructor(runner, options);
206
}
207
```
208

209
#### Progress Reporter
210

211
Progress bar with test count information.
212

213
```javascript { .api }
214
/**
215
 * Progress reporter - progress bar with counters
216
 */
217
class Progress extends Base {
218
  constructor(runner, options);
219
}
220
```
221

222
#### Landing Reporter
223

224
Landing strip style progress indicator.
225

226
```javascript { .api }
227
/**
228
 * Landing reporter - landing strip progress
229
 */
230
class Landing extends Base {
231
  constructor(runner, options);
232
}
233
```
234

235
#### JSON Stream Reporter
236

237
Streaming JSON output for real-time processing.
238

239
```javascript { .api }
240
/**
241
 * JSONStream reporter - streaming JSON events
242
 */
243
class JSONStream extends Base {
244
  constructor(runner, options);
245
}
246
```
247

248
### Reporter Selection and Configuration
249

250
```javascript { .api }
251
/**
252
 * Set reporter for a Mocha instance
253
 * @param name - Reporter name or constructor function
254
 * @param options - Reporter-specific options
255
 */
256
mocha.reporter(name, options);
257

258
/**
259
 * Available built-in reporters
260
 */
261
const reporters = {
262
  Base: Base,
263
  base: Base,
264
  Dot: Dot,
265
  dot: Dot,
266
  Doc: Doc,
267
  doc: Doc,
268
  TAP: TAP,
269
  tap: TAP,
270
  JSON: JSON,
271
  json: JSON,
272
  HTML: HTML,
273
  html: HTML,
274
  List: List,
275
  list: List,
276
  Min: Min,
277
  min: Min,
278
  Spec: Spec,
279
  spec: Spec,
280
  Nyan: Nyan,
281
  nyan: Nyan,
282
  XUnit: XUnit,
283
  xunit: XUnit,
284
  Markdown: Markdown,
285
  markdown: Markdown,
286
  Progress: Progress,
287
  progress: Progress,
288
  Landing: Landing,
289
  landing: Landing,
290
  JSONStream: JSONStream,
291
  'json-stream': JSONStream
292
};
293
```
294

295
**Usage Examples:**
296

297
```javascript
298
// Using built-in reporter by name
299
const mocha = new Mocha({
300
  reporter: 'spec'
301
});
302

303
// With reporter options
304
mocha.reporter('xunit', {
305
  output: './test-results.xml'
306
});
307

308
// Using reporter constructor
309
const CustomReporter = require('./custom-reporter');
310
mocha.reporter(CustomReporter);
311

312
// Programmatically
313
mocha.reporter('json').reporter('tap'); // Last one wins
314
```
315

316
### Custom Reporters
317

318
Create custom reporters by extending the Base class:
319

320
```javascript { .api }
321
/**
322
 * Custom reporter implementation
323
 */
324
class CustomReporter extends Base {
325
  constructor(runner, options) {
326
    super(runner, options);
327
    
328
    // Listen to runner events
329
    runner.on('start', () => {
330
      console.log('Tests starting...');
331
    });
332
    
333
    runner.on('pass', (test) => {
334
      console.log(`✓ ${test.fullTitle()}`);
335
    });
336
    
337
    runner.on('fail', (test, err) => {
338
      console.log(`✗ ${test.fullTitle()}: ${err.message}`);
339
    });
340
    
341
    runner.on('end', () => {
342
      this.epilogue();
343
    });
344
  }
345
}
346
```
347

348
### Reporter Events and Data
349

350
Reporters receive these events with associated data:
351

352
```javascript { .api }
353
/**
354
 * Runner events available to reporters
355
 */
356
const events = [
357
  'start',      // Test run begins
358
  'end',        // Test run ends  
359
  'suite',      // Suite begins
360
  'suite end',  // Suite ends
361
  'test',       // Test begins
362
  'test end',   // Test ends
363
  'pass',       // Test passes
364
  'fail',       // Test fails
365
  'pending',    // Test is pending
366
  'hook',       // Hook begins
367
  'hook end'    // Hook ends
368
];
369

370
/**
371
 * Test object structure passed to reporter events
372
 */
373
interface Test {
374
  title: string;           // Test title
375
  fullTitle(): string;     // Full hierarchical title
376
  duration: number;        // Test execution time
377
  state: 'passed' | 'failed' | 'pending';
378
  err?: Error;            // Error if test failed
379
  parent: Suite;          // Parent suite
380
  pending: boolean;       // Whether test is pending
381
  timeout(): number;      // Test timeout value
382
  slow(): number;         // Test slow threshold
383
}
384

385
/**
386
 * Suite object structure
387
 */
388
interface Suite {
389
  title: string;           // Suite title
390
  fullTitle(): string;     // Full hierarchical title
391
  parent?: Suite;         // Parent suite
392
  tests: Test[];          // Child tests
393
  suites: Suite[];        // Child suites
394
  pending: boolean;       // Whether suite is pending
395
  timeout(): number;      // Suite timeout value
396
  slow(): number;         // Suite slow threshold
397
}
398
```
399

400
### Reporter Utilities
401

402
Base reporter provides utility methods:
403

404
```javascript { .api }
405
/**
406
 * Utility methods available in Base reporter
407
 */
408
class Base {
409
  /**
410
   * Get color function for terminal output
411
   * @param name - Color name
412
   * @returns {Function} Color function
413
   */
414
  color(name);
415
  
416
  /**
417
   * Generate cursor movement for terminal
418
   * @returns {Object} Cursor utilities
419
   */
420
  cursor;
421
  
422
  /**
423
   * Check if output supports color
424
   * @returns {boolean} Whether colors are supported
425
   */
426
  useColors;
427
  
428
  /**
429
   * Get window size for formatting
430
   * @returns {Object} Window dimensions
431
   */
432
  window;
433
  
434
  /**
435
   * Get symbols for different output types
436
   * @returns {Object} Symbol definitions
437
   */
438
  symbols;
439
}
440

441
/**
442
 * Available color names
443
 */
444
const colors = [
445
  'pass',     // Green
446
  'fail',     // Red  
447
  'bright pass',  // Bright green
448
  'bright fail',  // Bright red
449
  'bright yellow', // Bright yellow
450
  'pending',  // Cyan
451
  'suite',    // Blue
452
  'error title',   // Red background
453
  'error message', // Red text
454
  'error stack',   // Gray
455
  'checkmark',     // Green
456
  'fast',     // Gray
457
  'medium',   // Yellow
458
  'slow',     // Red
459
  'green',    // Green
460
  'light',    // Gray
461
  'diff gutter',   // Gray
462
  'diff added',    // Green
463
  'diff removed'   // Red
464
];
465
```
466

467
### Reporter Configuration Options
468

469
Different reporters accept various configuration options:
470

471
```javascript { .api }
472
/**
473
 * Common reporter options
474
 */
475
interface ReporterOptions {
476
  output?: string;         // Output file path
477
  reporterOptions?: any;   // Reporter-specific options
478
}
479

480
/**
481
 * XUnit reporter specific options
482
 */
483
interface XUnitOptions {
484
  output?: string;         // XML output file
485
  suiteName?: string;      // Test suite name in XML
486
}
487

488
/**
489
 * JSON reporter specific options  
490
*/
491
interface JSONOptions {
492
  output?: string;         // JSON output file
493
}
494

495
/**
496
 * HTML reporter specific options
497
 */
498
interface HTMLOptions {
499
  inline?: boolean;        // Inline CSS/JS
500
  timeout?: number;        // Test timeout
501
}
502
```
503

504
**Configuration Examples:**
505

506
```javascript
507
// XUnit with file output
508
mocha.reporter('xunit', {
509
  reporterOptions: {
510
    output: './test-results.xml',
511
    suiteName: 'My Test Suite'
512
  }
513
});
514

515
// JSON with custom formatting
516
mocha.reporter('json', {
517
  reporterOptions: {
518
    output: './results.json'
519
  }
520
});
521

522
// Multiple reporters (using third-party libraries)
523
const MultiReporter = require('mocha-multi-reporters');
524
mocha.reporter(MultiReporter, {
525
  reporterOptions: {
526
    configFile: './reporter-config.json'
527
  }
528
});
529
```