feat(reporter): add output option to 'JSON' (#4607)

Co-authored-by: Juerg B <44573692+juergba@users.noreply.github.com>

Author: dorny

docs/index.md

@@ -1933,6 +1933,8 @@ Alias: `JSON`, `json`
 
 The JSON reporter outputs a single large JSON object when the tests have completed (failures or not).
 
+By default, it will output to the console. To write directly to a file, use `--reporter-option output=filename.json`.
+
 ![json reporter](images/reporter-json.png?withoutEnlargement&resize=920,9999){:class="screenshot" loading="lazy"}
 
 ### JSON Stream

example/config/.mocharc.js

@@ -33,7 +33,7 @@ module.exports = {
   parallel: false,
   recursive: false,
   reporter: 'spec',
-  'reporter-option': ['foo=bar', 'baz=quux'],
+  'reporter-option': ['foo=bar', 'baz=quux'], // array, not object
   require: '@babel/register',
   retries: 1,
   slow: '75',

example/config/.mocharc.yml

@@ -35,7 +35,7 @@ package: './package.json'
 parallel: false
 recursive: false
 reporter: 'spec'
-reporter-option:
+reporter-option: # array, not object
   - 'foo=bar'
   - 'baz=quux'
 require: '@babel/register'

lib/reporters/base.js

@@ -90,7 +90,7 @@ exports.colors = {
 
 exports.symbols = {
   ok: symbols.success,
-  err: symbols.err,
+  err: symbols.error,
   dot: '.',
   comma: ',',
   bang: '!'

lib/reporters/json.js

@@ -7,12 +7,16 @@
  */
 
 var Base = require('./base');
+var fs = require('fs');
+var path = require('path');
+const createUnsupportedError = require('../errors').createUnsupportedError;
+const utils = require('../utils');
 var constants = require('../runner').constants;
 var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
+var EVENT_TEST_PENDING = constants.EVENT_TEST_PENDING;
 var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
 var EVENT_TEST_END = constants.EVENT_TEST_END;
 var EVENT_RUN_END = constants.EVENT_RUN_END;
-var EVENT_TEST_PENDING = constants.EVENT_TEST_PENDING;
 
 /**
  * Expose `JSON`.
@@ -30,14 +34,22 @@ exports = module.exports = JSONReporter;
  * @param {Runner} runner - Instance triggers reporter actions.
  * @param {Object} [options] - runner options
  */
-function JSONReporter(runner, options) {
+function JSONReporter(runner, options = {}) {
   Base.call(this, runner, options);
 
   var self = this;
   var tests = [];
   var pending = [];
   var failures = [];
   var passes = [];
+  var output;
+
+  if (options.reporterOption && options.reporterOption.output) {
+    if (utils.isBrowser()) {
+      throw createUnsupportedError('file output not supported in browser');
+    }
+    output = options.reporterOption.output;
+  }
 
   runner.on(EVENT_TEST_END, function(test) {
     tests.push(test);
@@ -66,7 +78,20 @@ function JSONReporter(runner, options) {
 
     runner.testResults = obj;
 
-    process.stdout.write(JSON.stringify(obj, null, 2));
+    var json = JSON.stringify(obj, null, 2);
+    if (output) {
+      try {
+        fs.mkdirSync(path.dirname(output), {recursive: true});
+        fs.writeFileSync(output, json);
+      } catch (err) {
+        console.error(
+          `${Base.symbols.err} [mocha] writing output to "${output}" failed: ${err.message}\n`
+        );
+        process.stdout.write(json);
+      }
+    } else {
+      process.stdout.write(json);
+    }
   });
 }