mocha 7.2.0 → 8.1.1

package/lib/cli/options.js

@@ -2,7 +2,7 @@
 
 /**
  * Main entry point for handling filesystem-based configuration,
- * whether that's `mocha.opts` or a config file or `package.json` or whatever.
+ * whether that's a config file or `package.json` or whatever.
  * @module
  */
 
@@ -15,7 +15,6 @@ const mocharc = require('../mocharc.json');
 const {list} = require('./run-helpers');
 const {loadConfig, findConfig} = require('./config');
 const findUp = require('find-up');
-const {deprecate} = require('../utils');
 const debug = require('debug')('mocha:cli:options');
 const {isNodeFlag} = require('./node-flags');
 
@@ -55,16 +54,19 @@ const configuration = Object.assign({}, YARGS_PARSER_CONFIG, {
 
 /**
  * This is a really fancy way to:
- * - ensure unique values for `array`-type options
- * - use its array's last element for `boolean`/`number`/`string`- options given multiple times
+ * - `array`-type options: ensure unique values and evtl. split comma-delimited lists
+ * - `boolean`/`number`/`string`- options: use last element when given multiple times
  * This is passed as the `coerce` option to `yargs-parser`
  * @private
  * @ignore
  */
+const globOptions = ['spec', 'ignore'];
 const coerceOpts = Object.assign(
   types.array.reduce(
     (acc, arg) =>
-      Object.assign(acc, {[arg]: v => Array.from(new Set(list(v)))}),
+      Object.assign(acc, {
+        [arg]: v => Array.from(new Set(globOptions.includes(arg) ? v : list(v)))
+      }),
     {}
   ),
   types.boolean
@@ -143,71 +145,6 @@ const parse = (args = [], defaultValues = {}, ...configObjects) => {
   return result.argv;
 };
 
-/**
- * - Replaces comments with empty strings
- * - Replaces escaped spaces (e.g., 'xxx\ yyy') with HTML space
- * - Splits on whitespace, creating array of substrings
- * - Filters empty string elements from array
- * - Replaces any HTML space with space
- * @summary Parses options read from run-control file.
- * @private
- * @param {string} content - Content read from run-control file.
- * @returns {string[]} cmdline options (and associated arguments)
- * @ignore
- */
-const parseMochaOpts = content =>
-  content
-    .replace(/^#.*$/gm, '')
-    .replace(/\\\s/g, '%20')
-    .split(/\s/)
-    .filter(Boolean)
-    .map(value => value.replace(/%20/g, ' '));
-
-/**
- * Given filepath in `args.opts`, attempt to load and parse a `mocha.opts` file.
- * @param {Object} [args] - Arguments object
- * @param {string|boolean} [args.opts] - Filepath to mocha.opts; defaults to whatever's in `mocharc.opts`, or `false` to skip
- * @returns {external:yargsParser.Arguments|void} If read, object containing parsed arguments
- * @memberof module:lib/cli/options
- * @see {@link /#mochaopts|mocha.opts}
- * @public
- */
-const loadMochaOpts = (args = {}) => {
-  let result;
-  let filepath = args.opts;
-  // /dev/null is backwards compat
-  if (filepath === false || filepath === '/dev/null') {
-    return result;
-  }
-  filepath = filepath || mocharc.opts;
-  result = {};
-  let mochaOpts;
-  try {
-    mochaOpts = fs.readFileSync(filepath, 'utf8');
-    debug(`read ${filepath}`);
-  } catch (err) {
-    if (args.opts) {
-      throw new Error(`Unable to read ${filepath}: ${err}`);
-    }
-    // ignore otherwise.  we tried
-    debug(`No mocha.opts found at ${filepath}`);
-  }
-
-  // real args should override `mocha.opts` which should override defaults.
-  // if there's an exception to catch here, I'm not sure what it is.
-  // by attaching the `no-opts` arg, we avoid re-parsing of `mocha.opts`.
-  if (mochaOpts) {
-    deprecate(
-      'Configuration via mocha.opts is DEPRECATED and will be removed from a future version of Mocha. Use RC files or package.json instead.'
-    );
-    result = parse(parseMochaOpts(mochaOpts));
-    debug(`${filepath} parsed succesfully`);
-  }
-  return result;
-};
-
-module.exports.loadMochaOpts = loadMochaOpts;
-
 /**
  * Given path to config file in `args.config`, attempt to load & parse config file.
  * @param {Object} [args] - Arguments object
@@ -267,11 +204,10 @@ module.exports.loadPkgRc = loadPkgRc;
  * 1. Command-line args
  * 2. RC file (`.mocharc.c?js`, `.mocharc.ya?ml`, `mocharc.json`)
  * 3. `mocha` prop of `package.json`
- * 4. `mocha.opts`
- * 5. default configuration (`lib/mocharc.json`)
+ * 4. default configuration (`lib/mocharc.json`)
  *
  * If a {@link module:lib/cli/one-and-dones.ONE_AND_DONE_ARGS "one-and-done" option} is present in the `argv` array, no external config files will be read.
- * @summary Parses options read from `mocha.opts`, `.mocharc.*` and `package.json`.
+ * @summary Parses options read from `.mocharc.*` and `package.json`.
  * @param {string|string[]} [argv] - Arguments to parse
  * @public
  * @memberof module:lib/cli/options
@@ -279,7 +215,7 @@ module.exports.loadPkgRc = loadPkgRc;
  */
 const loadOptions = (argv = []) => {
   let args = parse(argv);
-  // short-circuit: look for a flag that would abort loading of mocha.opts
+  // short-circuit: look for a flag that would abort loading of options
   if (
     Array.from(ONE_AND_DONE_ARGS).reduce(
       (acc, arg) => acc || arg in args,
@@ -291,7 +227,6 @@ const loadOptions = (argv = []) => {
 
   const rcConfig = loadRc(args);
   const pkgConfig = loadPkgRc(args);
-  const optsConfig = loadMochaOpts(args);
 
   if (rcConfig) {
     args.config = false;
@@ -301,19 +236,8 @@ const loadOptions = (argv = []) => {
     args.package = false;
     args._ = args._.concat(pkgConfig._ || []);
   }
-  if (optsConfig) {
-    args.opts = false;
-    args._ = args._.concat(optsConfig._ || []);
-  }
 
-  args = parse(
-    args._,
-    mocharc,
-    args,
-    rcConfig || {},
-    pkgConfig || {},
-    optsConfig || {}
-  );
+  args = parse(args._, mocharc, args, rcConfig || {}, pkgConfig || {});
 
   // recombine positional arguments and "spec"
   if (args.spec) {

package/lib/cli/run-helpers.js

@@ -10,11 +10,12 @@
 const fs = require('fs');
 const path = require('path');
 const debug = require('debug')('mocha:cli:run:helpers');
-const watchRun = require('./watch-run');
+const {watchRun, watchParallelRun} = require('./watch-run');
 const collectFiles = require('./collect-files');
 const {type} = require('../utils');
 const {format} = require('util');
 const {createInvalidPluginError, createUnsupportedError} = require('../errors');
+const {requireOrImport} = require('../esm-utils');
 
 /**
  * Exits Mocha when tests + code under test has finished execution (default)
@@ -81,16 +82,21 @@ exports.list = str =>
  * @returns {Promise<MochaRootHookObject|MochaRootHookFunction>} Any root hooks
  * @private
  */
-exports.handleRequires = async (requires = []) =>
-  requires.reduce((acc, mod) => {
+exports.handleRequires = async (requires = []) => {
+  const acc = [];
+  for (const mod of requires) {
     let modpath = mod;
     // this is relative to cwd
     if (fs.existsSync(mod) || fs.existsSync(`${mod}.js`)) {
       modpath = path.resolve(mod);
       debug('resolved required file %s to %s', mod, modpath);
     }
-    const requiredModule = require(modpath);
-    if (type(requiredModule) === 'object' && requiredModule.mochaHooks) {
+    const requiredModule = await requireOrImport(modpath);
+    if (
+      requiredModule &&
+      typeof requiredModule === 'object' &&
+      requiredModule.mochaHooks
+    ) {
       const mochaHooksType = type(requiredModule.mochaHooks);
       if (/function$/.test(mochaHooksType) || mochaHooksType === 'object') {
         debug('found root hooks in required file %s', mod);
@@ -102,8 +108,9 @@ exports.handleRequires = async (requires = []) =>
       }
     }
     debug('loaded required module "%s"', mod);
-    return acc;
-  }, []);
+  }
+  return acc;
+};
 
 /**
  * Loads root hooks as exported via `mochaHooks` from required files.
@@ -151,24 +158,52 @@ const singleRun = async (mocha, {exit}, fileCollectParams) => {
 };
 
 /**
- * Actually run tests
+ * Collect files and run tests (using `BufferedRunner`).
+ *
+ * This is `async` for consistency.
+ *
  * @param {Mocha} mocha - Mocha instance
- * @param {Object} opts - Command line options
+ * @param {Options} options - Command line options
+ * @param {Object} fileCollectParams - Parameters that control test
+ *   file collection. See `lib/cli/collect-files.js`.
+ * @returns {Promise<BufferedRunner>}
+ * @ignore
  * @private
- * @returns {Promise}
+ */
+const parallelRun = async (mocha, options, fileCollectParams) => {
+  const files = collectFiles(fileCollectParams);
+  debug(
+    'executing %d test file(s) across %d concurrent jobs',
+    files.length,
+    options.jobs
+  );
+  mocha.files = files;
+
+  // note that we DO NOT load any files here; this is handled by the worker
+  return mocha.run(options.exit ? exitMocha : exitMochaLater);
+};
+
+/**
+ * Actually run tests.  Delegates to one of four different functions:
+ * - `singleRun`: run tests in serial & exit
+ * - `watchRun`: run tests in serial, rerunning as files change
+ * - `parallelRun`: run tests in parallel & exit
+ * - `watchParallelRun`: run tests in parallel, rerunning as files change
+ * @param {Mocha} mocha - Mocha instance
+ * @param {Options} opts - Command line options
+ * @private
+ * @returns {Promise<Runner>}
  */
 exports.runMocha = async (mocha, options) => {
   const {
     watch = false,
     extension = [],
-    exit = false,
     ignore = [],
     file = [],
+    parallel = false,
     recursive = false,
     sort = false,
-    spec = [],
-    watchFiles,
-    watchIgnore
+    spec = []
   } = options;
 
   const fileCollectParams = {
@@ -180,11 +215,14 @@ exports.runMocha = async (mocha, options) => {
     spec
   };
 
+  let run;
   if (watch) {
-    watchRun(mocha, {watchFiles, watchIgnore}, fileCollectParams);
+    run = parallel ? watchParallelRun : watchRun;
   } else {
-    await singleRun(mocha, {exit}, fileCollectParams);
+    run = parallel ? parallelRun : singleRun;
   }
+
+  return run(mocha, options, fileCollectParams);
 };
 
 /**

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

@@ -42,16 +42,16 @@ exports.types = {
     'list-interfaces',
     'list-reporters',
     'no-colors',
+    'parallel',
     'recursive',
     'sort',
     'watch'
   ],
-  number: ['retries'],
+  number: ['retries', 'jobs'],
   string: [
     'config',
     'fgrep',
     'grep',
-    'opts',
     'package',
     'reporter',
     'ui',
@@ -76,7 +76,9 @@ exports.aliases = {
   growl: ['G'],
   ignore: ['exclude'],
   invert: ['i'],
+  jobs: ['j'],
   'no-colors': ['C'],
+  parallel: ['p'],
   reporter: ['R'],
   'reporter-option': ['reporter-options', 'O'],
   require: ['r'],

package/lib/cli/run.js

@@ -7,6 +7,8 @@
  * @private
  */
 
+const symbols = require('log-symbols');
+const ansi = require('ansi-colors');
 const Mocha = require('../mocha');
 const {
   createUnsupportedError,
@@ -151,6 +153,13 @@ exports.builder = yargs =>
         description: 'Inverts --grep and --fgrep matches',
         group: GROUPS.FILTERS
       },
+      jobs: {
+        description:
+          'Number of concurrent jobs for --parallel; use 1 to run in serial',
+        defaultDescription: '(number of CPU cores - 1)',
+        requiresArg: true,
+        group: GROUPS.RULES
+      },
       'list-interfaces': {
         conflicts: Array.from(ONE_AND_DONE_ARGS),
         description: 'List built-in user interfaces & exit'
@@ -164,19 +173,16 @@ exports.builder = yargs =>
         group: GROUPS.OUTPUT,
         hidden: true
       },
-      opts: {
-        default: defaults.opts,
-        description: 'Path to `mocha.opts` (DEPRECATED)',
-        group: GROUPS.CONFIG,
-        normalize: true,
-        requiresArg: true
-      },
       package: {
         description: 'Path to package.json for config',
         group: GROUPS.CONFIG,
         normalize: true,
         requiresArg: true
       },
+      parallel: {
+        description: 'Run tests in parallel',
+        group: GROUPS.RULES
+      },
       recursive: {
         description: 'Look for tests in subdirectories',
         group: GROUPS.FILES
@@ -279,6 +285,40 @@ exports.builder = yargs =>
         );
       }
 
+      if (argv.parallel) {
+        // yargs.conflicts() can't deal with `--file foo.js --no-parallel`, either
+        if (argv.file) {
+          throw createUnsupportedError(
+            '--parallel runs test files in a non-deterministic order, and is mutually exclusive with --file'
+          );
+        }
+
+        // or this
+        if (argv.sort) {
+          throw createUnsupportedError(
+            '--parallel runs test files in a non-deterministic order, and is mutually exclusive with --sort'
+          );
+        }
+
+        if (argv.reporter === 'progress') {
+          throw createUnsupportedError(
+            '--reporter=progress is mutually exclusive with --parallel'
+          );
+        }
+
+        if (argv.reporter === 'markdown') {
+          throw createUnsupportedError(
+            '--reporter=markdown is mutually exclusive with --parallel'
+          );
+        }
+
+        if (argv.reporter === 'json-stream') {
+          throw createUnsupportedError(
+            '--reporter=json-stream is mutually exclusive with --parallel'
+          );
+        }
+      }
+
       if (argv.compilers) {
         throw createUnsupportedError(
           `--compilers is DEPRECATED and no longer supported.
@@ -295,14 +335,21 @@ exports.builder = yargs =>
 
       return true;
     })
-    .middleware(async argv => {
-      // load requires first, because it can impact "plugin" validation
-      const rawRootHooks = await handleRequires(argv.require);
-      validatePlugin(argv, 'reporter', Mocha.reporters);
-      validatePlugin(argv, 'ui', Mocha.interfaces);
+    .middleware(async (argv, yargs) => {
+      // currently a failing middleware does not work nicely with yargs' `fail()`.
+      try {
+        // load requires first, because it can impact "plugin" validation
+        const rawRootHooks = await handleRequires(argv.require);
+        validatePlugin(argv, 'reporter', Mocha.reporters);
+        validatePlugin(argv, 'ui', Mocha.interfaces);
 
-      if (rawRootHooks.length) {
-        argv.rootHooks = await loadRootHooks(rawRootHooks);
+        if (rawRootHooks && rawRootHooks.length) {
+          argv.rootHooks = await loadRootHooks(rawRootHooks);
+        }
+      } catch (err) {
+        // this could be a bad --require, bad reporter, ui, etc.
+        console.error(`\n${symbols.error} ${ansi.red('ERROR:')}`, err);
+        yargs.exit(1);
       }
     })
     .array(types.array)