mocha 7.1.2 → 8.1.0

package/lib/cli/lookup-files.js

@@ -0,0 +1,145 @@
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var glob = require('glob');
+var {format} = require('util');
+var errors = require('../errors');
+var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;
+var createMissingArgumentError = errors.createMissingArgumentError;
+var {sQuote, dQuote} = require('../utils');
+
+/**
+ * Determines if pathname would be a "hidden" file (or directory) on UN*X.
+ *
+ * @description
+ * On UN*X, pathnames beginning with a full stop (aka dot) are hidden during
+ * typical usage. Dotfiles, plain-text configuration files, are prime examples.
+ *
+ * @see {@link http://xahlee.info/UnixResource_dir/writ/unix_origin_of_dot_filename.html|Origin of Dot File Names}
+ *
+ * @private
+ * @param {string} pathname - Pathname to check for match.
+ * @return {boolean} whether pathname would be considered a hidden file.
+ * @example
+ * isHiddenOnUnix('.profile'); // => true
+ */
+function isHiddenOnUnix(pathname) {
+  return path.basename(pathname)[0] === '.';
+}
+
+/**
+ * Determines if pathname has a matching file extension.
+ *
+ * @private
+ * @param {string} pathname - Pathname to check for match.
+ * @param {string[]} exts - List of file extensions (sans period).
+ * @return {boolean} whether file extension matches.
+ * @example
+ * hasMatchingExtname('foo.html', ['js', 'css']); // => false
+ */
+function hasMatchingExtname(pathname, exts) {
+  var suffix = path.extname(pathname).slice(1);
+  return exts.some(function(element) {
+    return suffix === element;
+  });
+}
+
+/**
+ * Lookup file names at the given `path`.
+ *
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
+ * @public
+ * @memberof Mocha.utils
+ * @param {string} filepath - Base path to start searching from.
+ * @param {string[]} [extensions=[]] - File extensions to look for.
+ * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
+ * @return {string[]} An array of paths.
+ * @throws {Error} if no files match pattern.
+ * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
+ */
+module.exports = function lookupFiles(filepath, extensions, recursive) {
+  extensions = extensions || [];
+  recursive = recursive || false;
+  var files = [];
+  var stat;
+
+  if (!fs.existsSync(filepath)) {
+    var pattern;
+    if (glob.hasMagic(filepath)) {
+      // Handle glob as is without extensions
+      pattern = filepath;
+    } else {
+      // glob pattern e.g. 'filepath+(.js|.ts)'
+      var strExtensions = extensions
+        .map(function(v) {
+          return '.' + v;
+        })
+        .join('|');
+      pattern = filepath + '+(' + strExtensions + ')';
+    }
+    files = glob.sync(pattern, {nodir: true});
+    if (!files.length) {
+      throw createNoFilesMatchPatternError(
+        'Cannot find any files matching pattern ' + dQuote(filepath),
+        filepath
+      );
+    }
+    return files;
+  }
+
+  // Handle file
+  try {
+    stat = fs.statSync(filepath);
+    if (stat.isFile()) {
+      return filepath;
+    }
+  } catch (err) {
+    // ignore error
+    return;
+  }
+
+  // Handle directory
+  fs.readdirSync(filepath).forEach(function(dirent) {
+    var pathname = path.join(filepath, dirent);
+    var stat;
+
+    try {
+      stat = fs.statSync(pathname);
+      if (stat.isDirectory()) {
+        if (recursive) {
+          files = files.concat(lookupFiles(pathname, extensions, recursive));
+        }
+        return;
+      }
+    } catch (err) {
+      // ignore error
+      return;
+    }
+    if (!extensions.length) {
+      throw createMissingArgumentError(
+        format(
+          'Argument %s required when argument %s is a directory',
+          sQuote('extensions'),
+          sQuote('filepath')
+        ),
+        'extensions',
+        'array'
+      );
+    }
+
+    if (
+      !stat.isFile() ||
+      !hasMatchingExtname(pathname, extensions) ||
+      isHiddenOnUnix(pathname)
+    ) {
+      return;
+    }
+    files.push(pathname);
+  });
+
+  return files;
+};

package/lib/cli/node-flags.js

@@ -6,7 +6,7 @@
  * @module
  */
 
-const nodeFlags = require('node-environment-flags');
+const nodeFlags = process.allowedNodeEnvironmentFlags;
 const unparse = require('yargs-unparser');
 
 /**
@@ -48,7 +48,7 @@ exports.isNodeFlag = (flag, bareword = true) => {
     // check actual node flags from `process.allowedNodeEnvironmentFlags`,
     // then historical support for various V8 and non-`NODE_OPTIONS` flags
     // and also any V8 flags with `--v8-` prefix
-    (nodeFlags.has(flag) ||
+    ((nodeFlags && nodeFlags.has(flag)) ||
       debugFlags.has(flag) ||
       /(?:preserve-symlinks(?:-main)?|harmony(?:[_-]|$)|(?:trace[_-].+$)|gc(?:[_-]global)?$|es[_-]staging$|use[_-]strict$|v8[_-](?!options).+?$)/.test(
         flag

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
@@ -244,16 +181,16 @@ const loadPkgRc = (args = {}) => {
     try {
       const pkg = JSON.parse(fs.readFileSync(filepath, 'utf8'));
       if (pkg.mocha) {
-        debug(`'mocha' prop of package.json parsed:`, pkg.mocha);
+        debug('`mocha` prop of package.json parsed: %O', pkg.mocha);
         result = pkg.mocha;
       } else {
-        debug(`no config found in ${filepath}`);
+        debug('no config found in %s', filepath);
       }
     } catch (err) {
       if (args.package) {
         throw new Error(`Unable to read/parse ${filepath}: ${err}`);
       }
-      debug(`failed to read default package.json at ${filepath}; ignoring`);
+      debug('failed to read default package.json at %s; ignoring', filepath);
     }
   }
   return result;
@@ -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,10 +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 cwd = (exports.cwd = process.cwd());
+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)
@@ -73,20 +75,66 @@ exports.list = str =>
   Array.isArray(str) ? exports.list(str.join(',')) : str.split(/ *, */);
 
 /**
- * `require()` the modules as required by `--require <require>`
+ * `require()` the modules as required by `--require <require>`.
+ *
+ * Returns array of `mochaHooks` exports, if any.
  * @param {string[]} requires - Modules to require
+ * @returns {Promise<MochaRootHookObject|MochaRootHookFunction>} Any root hooks
  * @private
  */
-exports.handleRequires = (requires = []) => {
-  requires.forEach(mod => {
+exports.handleRequires = async (requires = []) => {
+  const acc = [];
+  for (const mod of requires) {
     let modpath = mod;
-    if (fs.existsSync(mod, {cwd}) || fs.existsSync(`${mod}.js`, {cwd})) {
+    // this is relative to cwd
+    if (fs.existsSync(mod) || fs.existsSync(`${mod}.js`)) {
       modpath = path.resolve(mod);
-      debug(`resolved ${mod} to ${modpath}`);
+      debug('resolved required file %s to %s', mod, modpath);
     }
-    require(modpath);
-    debug(`loaded require "${mod}"`);
-  });
+    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);
+        acc.push(requiredModule.mochaHooks);
+      } else {
+        throw createUnsupportedError(
+          'mochaHooks must be an object or a function returning (or fulfilling with) an object'
+        );
+      }
+    }
+    debug('loaded required module "%s"', mod);
+  }
+  return acc;
+};
+
+/**
+ * Loads root hooks as exported via `mochaHooks` from required files.
+ * These can be sync/async functions returning objects, or just objects.
+ * Flattens to a single object.
+ * @param {Array<MochaRootHookObject|MochaRootHookFunction>} rootHooks - Array of root hooks
+ * @private
+ * @returns {MochaRootHookObject}
+ */
+exports.loadRootHooks = async rootHooks => {
+  const rootHookObjects = await Promise.all(
+    rootHooks.map(async hook => (/function$/.test(type(hook)) ? hook() : hook))
+  );
+
+  return rootHookObjects.reduce(
+    (acc, hook) => {
+      acc.beforeAll = acc.beforeAll.concat(hook.beforeAll || []);
+      acc.beforeEach = acc.beforeEach.concat(hook.beforeEach || []);
+      acc.afterAll = acc.afterAll.concat(hook.afterAll || []);
+      acc.afterEach = acc.afterEach.concat(hook.afterEach || []);
+      return acc;
+    },
+    {beforeAll: [], beforeEach: [], afterAll: [], afterEach: []}
+  );
 };
 
 /**
@@ -101,32 +149,61 @@ exports.handleRequires = (requires = []) => {
  */
 const singleRun = async (mocha, {exit}, fileCollectParams) => {
   const files = collectFiles(fileCollectParams);
-  debug('running tests with files', files);
+  debug('single run with %d file(s)', files.length);
   mocha.files = files;
 
+  // handles ESM modules
   await mocha.loadFilesAsync();
   return mocha.run(exit ? exitMocha : exitMochaLater);
 };
 
 /**
- * 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 = {
@@ -138,43 +215,63 @@ 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);
 };
 
 /**
- * Used for `--reporter` and `--ui`.  Ensures there's only one, and asserts
- * that it actually exists.
- * @todo XXX This must get run after requires are processed, as it'll prevent
- * interfaces from loading.
+ * Used for `--reporter` and `--ui`.  Ensures there's only one, and asserts that
+ * it actually exists. This must be run _after_ requires are processed (see
+ * {@link handleRequires}), as it'll prevent interfaces from loading otherwise.
  * @param {Object} opts - Options object
- * @param {string} key - Resolvable module name or path
- * @param {Object} [map] - An object perhaps having key `key`
+ * @param {"reporter"|"interface"} pluginType - Type of plugin.
+ * @param {Object} [map] - An object perhaps having key `key`. Used as a cache
+ * of sorts; `Mocha.reporters` is one, where each key corresponds to a reporter
+ * name
  * @private
  */
-exports.validatePlugin = (opts, key, map = {}) => {
-  if (Array.isArray(opts[key])) {
-    throw new TypeError(`"--${key} <${key}>" can only be specified once`);
+exports.validatePlugin = (opts, pluginType, map = {}) => {
+  /**
+   * This should be a unique identifier; either a string (present in `map`),
+   * or a resolvable (via `require.resolve`) module ID/path.
+   * @type {string}
+   */
+  const pluginId = opts[pluginType];
+
+  if (Array.isArray(pluginId)) {
+    throw createInvalidPluginError(
+      `"--${pluginType}" can only be specified once`,
+      pluginType
+    );
   }
 
-  const unknownError = () => new Error(`Unknown "${key}": ${opts[key]}`);
+  const unknownError = err =>
+    createInvalidPluginError(
+      format('Could not load %s "%s":\n\n %O', pluginType, pluginId, err),
+      pluginType,
+      pluginId
+    );
 
-  if (!map[opts[key]]) {
+  // if this exists, then it's already loaded, so nothing more to do.
+  if (!map[pluginId]) {
     try {
-      opts[key] = require(opts[key]);
+      opts[pluginType] = require(pluginId);
     } catch (err) {
       if (err.code === 'MODULE_NOT_FOUND') {
         // Try to load reporters from a path (absolute or relative)
         try {
-          opts[key] = require(path.resolve(process.cwd(), opts[key]));
+          opts[pluginType] = require(path.resolve(pluginId));
         } catch (err) {
-          throw unknownError();
+          throw unknownError(err);
         }
       } else {
-        throw unknownError();
+        throw unknownError(err);
       }
     }
   }

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'],