mocha 9.0.3 → 9.1.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 9.1.0 / 2021-08-20
+
+## :tada: Enhancements
+
+- [#4716](https://github.com/mochajs/mocha/issues/4716): Add new option `--fail-zero` ([**@juergba**](https://github.com/juergba))
+- [#4691](https://github.com/mochajs/mocha/issues/4691): Add new option `--node-option` ([**@juergba**](https://github.com/juergba))
+- [#4607](https://github.com/mochajs/mocha/issues/4607): Add output option to `JSON` reporter ([**@dorny**](https://github.com/dorny))
+
 # 9.0.3 / 2021-07-25
 
 ## :bug: Fixes

package/bin/mocha

@@ -10,7 +10,6 @@
  * @private
  */
 
-const {deprecate} = require('../lib/utils');
 const {loadOptions} = require('../lib/cli/options');
 const {
   unparseNodeFlags,
@@ -23,6 +22,7 @@ const {aliases} = require('../lib/cli/run-option-metadata');
 
 const mochaArgs = {};
 const nodeArgs = {};
+let hasInspect = false;
 
 const opts = loadOptions(process.argv.slice(2));
 debug('loaded opts', opts);
@@ -59,48 +59,39 @@ Object.keys(opts).forEach(opt => {
 
 // disable 'timeout' for debugFlags
 Object.keys(nodeArgs).forEach(opt => disableTimeouts(opt));
+mochaArgs['node-option'] &&
+  mochaArgs['node-option'].forEach(opt => disableTimeouts(opt));
 
 // Native debugger handling
 // see https://nodejs.org/api/debugger.html#debugger_debugger
-// look for 'inspect' or 'debug' that would launch this debugger,
+// look for 'inspect' that would launch this debugger,
 // remove it from Mocha's opts and prepend it to Node's opts.
 // A deprecation warning will be printed by node, if applicable.
 // (mochaArgs._ are "positional" arguments, not prefixed with - or --)
 if (mochaArgs._) {
-  const i = mochaArgs._.findIndex(val => val === 'inspect' || val === 'debug');
+  const i = mochaArgs._.findIndex(val => val === 'inspect');
   if (i > -1) {
-    const [command] = mochaArgs._.splice(i, 1);
+    mochaArgs._.splice(i, 1);
     disableTimeouts('inspect');
-    nodeArgs._ = [command];
+    hasInspect = true;
   }
 }
 
-// historical
-if (nodeArgs.gc) {
-  deprecate(
-    '"-gc" is deprecated and will be removed from a future version of Mocha.  Use "--gc-global" instead.'
-  );
-  nodeArgs['gc-global'] = nodeArgs.gc;
-  delete nodeArgs.gc;
-}
-
-// --require/-r is treated as Mocha flag except when 'esm' is preloaded
-if (mochaArgs.require && mochaArgs.require.includes('esm')) {
-  nodeArgs.require = ['esm'];
-  mochaArgs.require = mochaArgs.require.filter(mod => mod !== 'esm');
-  if (!mochaArgs.require.length) {
-    delete mochaArgs.require;
-  }
-}
-
-if (Object.keys(nodeArgs).length) {
+if (mochaArgs['node-option'] || Object.keys(nodeArgs).length || hasInspect) {
   const {spawn} = require('child_process');
   const mochaPath = require.resolve('../lib/cli/cli.js');
 
-  debug('final node args', nodeArgs);
+  const nodeArgv =
+    (mochaArgs['node-option'] && mochaArgs['node-option'].map(v => '--' + v)) ||
+    unparseNodeFlags(nodeArgs);
+
+  if (hasInspect) nodeArgv.unshift('inspect');
+  delete mochaArgs['node-option'];
+
+  debug('final node argv', nodeArgv);
 
   const args = [].concat(
-    unparseNodeFlags(nodeArgs),
+    nodeArgv,
     mochaPath,
     unparse(mochaArgs, {alias: aliases})
   );
@@ -147,5 +138,5 @@ if (Object.keys(nodeArgs).length) {
   });
 } else {
   debug('running Mocha in-process');
-  require('../lib/cli/cli').main(unparse(mochaArgs, {alias: aliases}));
+  require('../lib/cli/cli').main([], mochaArgs);
 }

package/lib/cli/cli.js

@@ -33,8 +33,9 @@ const {cwd} = require('../utils');
  * @public
  * @summary Mocha's main command-line entry-point.
  * @param {string[]} argv - Array of arguments to parse, or by default the lovely `process.argv.slice(2)`
+ * @param {object} [mochaArgs] - Object of already parsed Mocha arguments (by bin/mocha)
  */
-exports.main = (argv = process.argv.slice(2)) => {
+exports.main = (argv = process.argv.slice(2), mochaArgs) => {
   debug('entered main with raw args', argv);
   // ensure we can require() from current working directory
   if (typeof module.paths !== 'undefined') {
@@ -43,7 +44,7 @@ exports.main = (argv = process.argv.slice(2)) => {
 
   Error.stackTraceLimit = Infinity; // configurable via --stack-trace-limit?
 
-  var args = loadOptions(argv);
+  var args = mochaArgs || loadOptions(argv);
 
   yargs()
     .scriptName('mocha')

package/lib/cli/node-flags.js

@@ -49,7 +49,7 @@ exports.isNodeFlag = (flag, bareword = true) => {
     // and also any V8 flags with `--v8-` prefix
     (!isMochaFlag(flag) && nodeFlags && nodeFlags.has(flag)) ||
     debugFlags.has(flag) ||
-    /(?:preserve-symlinks(?:-main)?|harmony(?:[_-]|$)|(?:trace[_-].+$)|gc(?:[_-]global)?$|es[_-]staging$|use[_-]strict$|v8[_-](?!options).+?$)/.test(
+    /(?:preserve-symlinks(?:-main)?|harmony(?:[_-]|$)|(?:trace[_-].+$)|gc[_-]global$|es[_-]staging$|use[_-]strict$|v8[_-](?!options).+?$)/.test(
       flag
     )
   );
@@ -67,7 +67,6 @@ exports.impliesNoTimeouts = flag => debugFlags.has(flag);
 /**
  * All non-strictly-boolean arguments to node--those with values--must specify those values using `=`, e.g., `--inspect=0.0.0.0`.
  * Unparse these arguments using `yargs-unparser` (which would result in `--inspect 0.0.0.0`), then supply `=` where we have values.
- * Apparently --require in Node.js v8 does NOT want `=`.
  * There's probably an easier or more robust way to do this; fixes welcome
  * @param {Object} opts - Arguments object
  * @returns {string[]} Unparsed arguments using `=` to specify values
@@ -79,9 +78,7 @@ exports.unparseNodeFlags = opts => {
     ? args
         .join(' ')
         .split(/\b/)
-        .map((arg, index, args) =>
-          arg === ' ' && args[index - 1] !== 'require' ? '=' : arg
-        )
+        .map(arg => (arg === ' ' ? '=' : arg))
         .join('')
         .split(' ')
     : [];

package/lib/cli/run-option-metadata.js

@@ -18,6 +18,7 @@ const TYPES = (exports.types = {
     'file',
     'global',
     'ignore',
+    'node-option',
     'reporter-option',
     'require',
     'spec',
@@ -34,6 +35,7 @@ const TYPES = (exports.types = {
     'diff',
     'dry-run',
     'exit',
+    'fail-zero',
     'forbid-only',
     'forbid-pending',
     'full-trace',
@@ -79,6 +81,7 @@ exports.aliases = {
   invert: ['i'],
   jobs: ['j'],
   'no-colors': ['C'],
+  'node-option': ['n'],
   parallel: ['p'],
   reporter: ['R'],
   'reporter-option': ['reporter-options', 'O'],

package/lib/cli/run.js

@@ -98,6 +98,10 @@ exports.builder = yargs =>
         requiresArg: true,
         coerce: list
       },
+      'fail-zero': {
+        description: 'Fail test run if no test(s) encountered',
+        group: GROUPS.RULES
+      },
       fgrep: {
         conflicts: 'grep',
         description: 'Only run tests containing this string',
@@ -176,6 +180,10 @@ exports.builder = yargs =>
         group: GROUPS.OUTPUT,
         hidden: true
       },
+      'node-option': {
+        description: 'Node or V8 option (no leading "--")',
+        group: GROUPS.CONFIG
+      },
       package: {
         description: 'Path to package.json for config',
         group: GROUPS.CONFIG,

package/lib/mocha.js

@@ -164,6 +164,7 @@ exports.run = function(...args) {
  * @param {boolean} [options.delay] - Delay root suite execution?
  * @param {boolean} [options.diff] - Show diff on failure?
  * @param {boolean} [options.dryRun] - Report tests without running them?
+ * @param {boolean} [options.failZero] - Fail test run if zero tests?
  * @param {string} [options.fgrep] - Test filter given string.
  * @param {boolean} [options.forbidOnly] - Tests marked `only` fail the suite?
  * @param {boolean} [options.forbidPending] - Pending tests fail the suite?
@@ -223,6 +224,7 @@ function Mocha(options = {}) {
     'delay',
     'diff',
     'dryRun',
+    'failZero',
     'forbidOnly',
     'forbidPending',
     'fullTrace',
@@ -581,7 +583,7 @@ Mocha.prototype.fgrep = function(str) {
 Mocha.prototype.grep = function(re) {
   if (utils.isString(re)) {
     // extract args if it's regex-like, i.e: [string, pattern, flag]
-    var arg = re.match(/^\/(.*)\/(g|i|)$|.*/);
+    var arg = re.match(/^\/(.*)\/([gimy]{0,4})$|.*/);
     this.options.grep = new RegExp(arg[1] || arg[0], arg[2]);
   } else {
     this.options.grep = re;
@@ -778,20 +780,6 @@ Mocha.prototype.diff = function(diff) {
   return this;
 };
 
-/**
- * Enables or disables running tests in dry-run mode.
- *
- * @public
- * @see [CLI option](../#-dry-run)
- * @param {boolean} [dryRun=true] - Whether to activate dry-run mode.
- * @return {Mocha} this
- * @chainable
- */
-Mocha.prototype.dryRun = function(dryRun) {
-  this.options.dryRun = dryRun !== false;
-  return this;
-};
-
 /**
  * @summary
  * Sets timeout threshold value.
@@ -918,6 +906,34 @@ Mocha.prototype.delay = function delay() {
   return this;
 };
 
+/**
+ * Enables or disables running tests in dry-run mode.
+ *
+ * @public
+ * @see [CLI option](../#-dry-run)
+ * @param {boolean} [dryRun=true] - Whether to activate dry-run mode.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.dryRun = function(dryRun) {
+  this.options.dryRun = dryRun !== false;
+  return this;
+};
+
+/**
+ * Fails test run if no tests encountered with exit-code 1.
+ *
+ * @public
+ * @see [CLI option](../#-fail-zero)
+ * @param {boolean} [failZero=true] - Whether to fail test run.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.failZero = function(failZero) {
+  this.options.failZero = failZero !== false;
+  return this;
+};
+
 /**
  * Causes tests marked `only` to fail the suite.
  *
@@ -1023,9 +1039,10 @@ Mocha.prototype.run = function(fn) {
   var options = this.options;
   options.files = this.files;
   const runner = new this._runnerClass(suite, {
+    cleanReferencesAfterRun: this._cleanReferencesAfterRun,
     delay: options.delay,
     dryRun: options.dryRun,
-    cleanReferencesAfterRun: this._cleanReferencesAfterRun
+    failZero: options.failZero
   });
   createStatsCollector(runner);
   var reporter = new this._reporter(runner, options);

package/lib/reporters/base.js

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

package/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,7 +34,7 @@ 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;
@@ -38,6 +42,14 @@ function JSONReporter(runner, options) {
   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);
+    }
   });
 }
 

package/lib/runner.js

@@ -135,10 +135,11 @@ class Runner extends EventEmitter {
    * @public
    * @class
    * @param {Suite} suite - Root suite
-   * @param {Object|boolean} [opts] - Options. If `boolean` (deprecated), whether or not to delay execution of root suite until ready.
+   * @param {Object|boolean} [opts] - Options. If `boolean` (deprecated), whether to delay execution of root suite until ready.
+   * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
    * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
    * @param {boolean} [opts.dryRun] - Whether to report tests without running them.
-   * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
+   * @param {boolean} [options.failZero] - Whether to fail test run if zero tests encountered.
    */
   constructor(suite, opts) {
     super();
@@ -1044,6 +1045,8 @@ Runner.prototype.run = function(fn, opts = {}) {
   fn = fn || function() {};
 
   const end = () => {
+    if (!this.total && this._opts.failZero) this.failures = 1;
+
     debug('run(): root suite completed; emitting %s', constants.EVENT_RUN_END);
     this.emit(constants.EVENT_RUN_END);
   };