mocha 9.1.2

package/lib/cli/node-flags.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Some settings and code related to Mocha's handling of Node.js/V8 flags.
+ * @private
+ * @module
+ */
+
+const nodeFlags = process.allowedNodeEnvironmentFlags;
+const {isMochaFlag} = require('./run-option-metadata');
+const unparse = require('yargs-unparser');
+
+/**
+ * These flags are considered "debug" flags.
+ * @see {@link impliesNoTimeouts}
+ * @private
+ */
+const debugFlags = new Set(['inspect', 'inspect-brk']);
+
+/**
+ * Mocha has historical support for various `node` and V8 flags which might not
+ * appear in `process.allowedNodeEnvironmentFlags`.
+ * These include:
+ *   - `--preserve-symlinks`
+ *   - `--harmony-*`
+ *   - `--gc-global`
+ *   - `--trace-*`
+ *   - `--es-staging`
+ *   - `--use-strict`
+ *   - `--v8-*` (but *not* `--v8-options`)
+ * @summary Whether or not to pass a flag along to the `node` executable.
+ * @param {string} flag - Flag to test
+ * @param {boolean} [bareword=true] - If `false`, we expect `flag` to have one or two leading dashes.
+ * @returns {boolean} If the flag is considered a "Node" flag.
+ * @private
+ */
+exports.isNodeFlag = (flag, bareword = true) => {
+  if (!bareword) {
+    // check if the flag begins with dashes; if not, not a node flag.
+    if (!/^--?/.test(flag)) {
+      return false;
+    }
+    // strip the leading dashes to match against subsequent checks
+    flag = flag.replace(/^--?/, '');
+  }
+  return (
+    // 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
+    (!isMochaFlag(flag) && nodeFlags && nodeFlags.has(flag)) ||
+    debugFlags.has(flag) ||
+    /(?:preserve-symlinks(?:-main)?|harmony(?:[_-]|$)|(?:trace[_-].+$)|gc[_-]global$|es[_-]staging$|use[_-]strict$|v8[_-](?!options).+?$)/.test(
+      flag
+    )
+  );
+};
+
+/**
+ * Returns `true` if the flag is a "debug-like" flag.  These require timeouts
+ * to be suppressed, or pausing the debugger on breakpoints will cause test failures.
+ * @param {string} flag - Flag to test
+ * @returns {boolean}
+ * @private
+ */
+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.
+ * 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
+ * @private
+ */
+exports.unparseNodeFlags = opts => {
+  var args = unparse(opts);
+  return args.length
+    ? args
+        .join(' ')
+        .split(/\b/)
+        .map(arg => (arg === ' ' ? '=' : arg))
+        .join('')
+        .split(' ')
+    : [];
+};

package/lib/cli/one-and-dones.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Contains "command" code for "one-and-dones"--options passed
+ * to Mocha which cause it to just dump some info and exit.
+ * See {@link module:lib/cli/one-and-dones.ONE_AND_DONE_ARGS ONE_AND_DONE_ARGS} for more info.
+ * @module
+ * @private
+ */
+
+const Mocha = require('../mocha');
+
+/**
+ * Dumps a sorted list of the enumerable, lower-case keys of some object
+ * to `STDOUT`.
+ * @param {Object} obj - Object, ostensibly having some enumerable keys
+ * @ignore
+ * @private
+ */
+const showKeys = obj => {
+  console.log();
+  const keys = Object.keys(obj);
+  const maxKeyLength = keys.reduce((max, key) => Math.max(max, key.length), 0);
+  keys
+    .filter(
+      key => /^[a-z]/.test(key) && !obj[key].browserOnly && !obj[key].abstract
+    )
+    .sort()
+    .forEach(key => {
+      const description = obj[key].description;
+      console.log(
+        `    ${key.padEnd(maxKeyLength + 1)}${
+          description ? `- ${description}` : ''
+        }`
+      );
+    });
+  console.log();
+};
+
+/**
+ * Handlers for one-and-done options
+ * @namespace
+ * @private
+ */
+exports.ONE_AND_DONES = {
+  /**
+   * Dump list of built-in interfaces
+   * @private
+   */
+  'list-interfaces': () => {
+    showKeys(Mocha.interfaces);
+  },
+  /**
+   * Dump list of built-in reporters
+   * @private
+   */
+  'list-reporters': () => {
+    showKeys(Mocha.reporters);
+  }
+};
+
+/**
+ * A Set of all one-and-done options
+ * @type Set<string>
+ * @private
+ */
+exports.ONE_AND_DONE_ARGS = new Set(
+  ['help', 'h', 'version', 'V'].concat(Object.keys(exports.ONE_AND_DONES))
+);

package/lib/cli/options.js

@@ -0,0 +1,261 @@
+'use strict';
+
+/**
+ * Main entry point for handling filesystem-based configuration,
+ * whether that's a config file or `package.json` or whatever.
+ * @module lib/cli/options
+ * @private
+ */
+
+const fs = require('fs');
+const ansi = require('ansi-colors');
+const yargsParser = require('yargs-parser');
+const {types, aliases} = require('./run-option-metadata');
+const {ONE_AND_DONE_ARGS} = require('./one-and-dones');
+const mocharc = require('../mocharc.json');
+const {list} = require('./run-helpers');
+const {loadConfig, findConfig} = require('./config');
+const findUp = require('find-up');
+const debug = require('debug')('mocha:cli:options');
+const {isNodeFlag} = require('./node-flags');
+const {createUnparsableFileError} = require('../errors');
+
+/**
+ * The `yargs-parser` namespace
+ * @external yargsParser
+ * @see {@link https://npm.im/yargs-parser}
+ */
+
+/**
+ * An object returned by a configured `yargs-parser` representing arguments
+ * @memberof external:yargsParser
+ * @interface Arguments
+ */
+
+/**
+ * Base yargs parser configuration
+ * @private
+ */
+const YARGS_PARSER_CONFIG = {
+  'combine-arrays': true,
+  'short-option-groups': false,
+  'dot-notation': false,
+  'strip-aliased': true
+};
+
+/**
+ * This is the config pulled from the `yargs` property of Mocha's
+ * `package.json`, but it also disables camel case expansion as to
+ * avoid outputting non-canonical keynames, as we need to do some
+ * lookups.
+ * @private
+ * @ignore
+ */
+const configuration = Object.assign({}, YARGS_PARSER_CONFIG, {
+  'camel-case-expansion': false
+});
+
+/**
+ * This is a really fancy way to:
+ * - `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(globOptions.includes(arg) ? v : list(v)))
+      }),
+    {}
+  ),
+  types.boolean
+    .concat(types.string, types.number)
+    .reduce(
+      (acc, arg) =>
+        Object.assign(acc, {[arg]: v => (Array.isArray(v) ? v.pop() : v)}),
+      {}
+    )
+);
+
+/**
+ * We do not have a case when multiple arguments are ever allowed after a flag
+ * (e.g., `--foo bar baz quux`), so we fix the number of arguments to 1 across
+ * the board of non-boolean options.
+ * This is passed as the `narg` option to `yargs-parser`
+ * @private
+ * @ignore
+ */
+const nargOpts = types.array
+  .concat(types.string, types.number)
+  .reduce((acc, arg) => Object.assign(acc, {[arg]: 1}), {});
+
+/**
+ * Wrapper around `yargs-parser` which applies our settings
+ * @param {string|string[]} args - Arguments to parse
+ * @param {Object} defaultValues - Default values of mocharc.json
+ * @param  {...Object} configObjects - `configObjects` for yargs-parser
+ * @private
+ * @ignore
+ */
+const parse = (args = [], defaultValues = {}, ...configObjects) => {
+  // save node-specific args for special handling.
+  // 1. when these args have a "=" they should be considered to have values
+  // 2. if they don't, they just boolean flags
+  // 3. to avoid explicitly defining the set of them, we tell yargs-parser they
+  //    are ALL boolean flags.
+  // 4. we can then reapply the values after yargs-parser is done.
+  const nodeArgs = (Array.isArray(args) ? args : args.split(' ')).reduce(
+    (acc, arg) => {
+      const pair = arg.split('=');
+      let flag = pair[0];
+      if (isNodeFlag(flag, false)) {
+        flag = flag.replace(/^--?/, '');
+        return arg.includes('=')
+          ? acc.concat([[flag, pair[1]]])
+          : acc.concat([[flag, true]]);
+      }
+      return acc;
+    },
+    []
+  );
+
+  const result = yargsParser.detailed(args, {
+    configuration,
+    configObjects,
+    default: defaultValues,
+    coerce: coerceOpts,
+    narg: nargOpts,
+    alias: aliases,
+    string: types.string,
+    array: types.array,
+    number: types.number,
+    boolean: types.boolean.concat(nodeArgs.map(pair => pair[0]))
+  });
+  if (result.error) {
+    console.error(ansi.red(`Error: ${result.error.message}`));
+    process.exit(1);
+  }
+
+  // reapply "=" arg values from above
+  nodeArgs.forEach(([key, value]) => {
+    result.argv[key] = value;
+  });
+
+  return result.argv;
+};
+
+/**
+ * Given path to config file in `args.config`, attempt to load & parse config file.
+ * @param {Object} [args] - Arguments object
+ * @param {string|boolean} [args.config] - Path to config file or `false` to skip
+ * @public
+ * @alias module:lib/cli.loadRc
+ * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.config` is `false`
+ */
+const loadRc = (args = {}) => {
+  if (args.config !== false) {
+    const config = args.config || findConfig();
+    return config ? loadConfig(config) : {};
+  }
+};
+
+module.exports.loadRc = loadRc;
+
+/**
+ * Given path to `package.json` in `args.package`, attempt to load config from `mocha` prop.
+ * @param {Object} [args] - Arguments object
+ * @param {string|boolean} [args.config] - Path to `package.json` or `false` to skip
+ * @public
+ * @alias module:lib/cli.loadPkgRc
+ * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.package` is `false`
+ */
+const loadPkgRc = (args = {}) => {
+  let result;
+  if (args.package === false) {
+    return result;
+  }
+  result = {};
+  const filepath = args.package || findUp.sync(mocharc.package);
+  if (filepath) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(filepath, 'utf8'));
+      if (pkg.mocha) {
+        debug('`mocha` prop of package.json parsed: %O', pkg.mocha);
+        result = pkg.mocha;
+      } else {
+        debug('no config found in %s', filepath);
+      }
+    } catch (err) {
+      if (args.package) {
+        throw createUnparsableFileError(
+          `Unable to read/parse ${filepath}: ${err}`,
+          filepath
+        );
+      }
+      debug('failed to read default package.json at %s; ignoring', filepath);
+    }
+  }
+  return result;
+};
+
+module.exports.loadPkgRc = loadPkgRc;
+
+/**
+ * Priority list:
+ *
+ * 1. Command-line args
+ * 2. RC file (`.mocharc.c?js`, `.mocharc.ya?ml`, `mocharc.json`)
+ * 3. `mocha` prop of `package.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 `.mocharc.*` and `package.json`.
+ * @param {string|string[]} [argv] - Arguments to parse
+ * @public
+ * @alias module:lib/cli.loadOptions
+ * @returns {external:yargsParser.Arguments} Parsed args from everything
+ */
+const loadOptions = (argv = []) => {
+  let args = parse(argv);
+  // 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,
+      false
+    )
+  ) {
+    return args;
+  }
+
+  const rcConfig = loadRc(args);
+  const pkgConfig = loadPkgRc(args);
+
+  if (rcConfig) {
+    args.config = false;
+    args._ = args._.concat(rcConfig._ || []);
+  }
+  if (pkgConfig) {
+    args.package = false;
+    args._ = args._.concat(pkgConfig._ || []);
+  }
+
+  args = parse(args._, mocharc, args, rcConfig || {}, pkgConfig || {});
+
+  // recombine positional arguments and "spec"
+  if (args.spec) {
+    args._ = args._.concat(args.spec);
+    delete args.spec;
+  }
+
+  // make unique
+  args._ = Array.from(new Set(args._));
+
+  return args;
+};
+
+module.exports.loadOptions = loadOptions;
+module.exports.YARGS_PARSER_CONFIG = YARGS_PARSER_CONFIG;

package/lib/cli/run-helpers.js

@@ -0,0 +1,243 @@
+'use strict';
+
+/**
+ * Helper scripts for the `run` command
+ * @see module:lib/cli/run
+ * @module
+ * @private
+ */
+
+const fs = require('fs');
+const path = require('path');
+const debug = require('debug')('mocha:cli:run:helpers');
+const {watchRun, watchParallelRun} = require('./watch-run');
+const collectFiles = require('./collect-files');
+const {format} = require('util');
+const {createInvalidLegacyPluginError} = require('../errors');
+const {requireOrImport} = require('../nodejs/esm-utils');
+const PluginLoader = require('../plugin-loader');
+
+/**
+ * Exits Mocha when tests + code under test has finished execution (default)
+ * @param {number} code - Exit code; typically # of failures
+ * @ignore
+ * @private
+ */
+const exitMochaLater = code => {
+  process.on('exit', () => {
+    process.exitCode = Math.min(code, 255);
+  });
+};
+
+/**
+ * Exits Mocha when Mocha itself has finished execution, regardless of
+ * what the tests or code under test is doing.
+ * @param {number} code - Exit code; typically # of failures
+ * @ignore
+ * @private
+ */
+const exitMocha = code => {
+  const clampedCode = Math.min(code, 255);
+  let draining = 0;
+
+  // Eagerly set the process's exit code in case stream.write doesn't
+  // execute its callback before the process terminates.
+  process.exitCode = clampedCode;
+
+  // flush output for Node.js Windows pipe bug
+  // https://github.com/joyent/node/issues/6247 is just one bug example
+  // https://github.com/visionmedia/mocha/issues/333 has a good discussion
+  const done = () => {
+    if (!draining--) {
+      process.exit(clampedCode);
+    }
+  };
+
+  const streams = [process.stdout, process.stderr];
+
+  streams.forEach(stream => {
+    // submit empty write request and wait for completion
+    draining += 1;
+    stream.write('', done);
+  });
+
+  done();
+};
+
+/**
+ * Coerce a comma-delimited string (or array thereof) into a flattened array of
+ * strings
+ * @param {string|string[]} str - Value to coerce
+ * @returns {string[]} Array of strings
+ * @private
+ */
+exports.list = str =>
+  Array.isArray(str) ? exports.list(str.join(',')) : str.split(/ *, */);
+
+/**
+ * `require()` the modules as required by `--require <require>`.
+ *
+ * Returns array of `mochaHooks` exports, if any.
+ * @param {string[]} requires - Modules to require
+ * @returns {Promise<object>} Plugin implementations
+ * @private
+ */
+exports.handleRequires = async (requires = [], {ignoredPlugins = []} = {}) => {
+  const pluginLoader = PluginLoader.create({ignore: ignoredPlugins});
+  for await (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 = await requireOrImport(modpath);
+    if (requiredModule && typeof requiredModule === 'object') {
+      if (pluginLoader.load(requiredModule)) {
+        debug('found one or more plugin implementations in %s', modpath);
+      }
+    }
+    debug('loaded required module "%s"', mod);
+  }
+  const plugins = await pluginLoader.finalize();
+  if (Object.keys(plugins).length) {
+    debug('finalized plugin implementations: %O', plugins);
+  }
+  return plugins;
+};
+
+/**
+ * Collect and load test files, then run mocha instance.
+ * @param {Mocha} mocha - Mocha instance
+ * @param {Options} [opts] - Command line options
+ * @param {boolean} [opts.exit] - Whether or not to force-exit after tests are complete
+ * @param {Object} fileCollectParams - Parameters that control test
+ *   file collection. See `lib/cli/collect-files.js`.
+ * @returns {Promise<Runner>}
+ * @private
+ */
+const singleRun = async (mocha, {exit}, fileCollectParams) => {
+  const files = collectFiles(fileCollectParams);
+  debug('single run with %d file(s)', files.length);
+  mocha.files = files;
+
+  // handles ESM modules
+  await mocha.loadFilesAsync();
+  return mocha.run(exit ? exitMocha : exitMochaLater);
+};
+
+/**
+ * Collect files and run tests (using `BufferedRunner`).
+ *
+ * This is `async` for consistency.
+ *
+ * @param {Mocha} mocha - Mocha instance
+ * @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
+ */
+const parallelRun = async (mocha, options, fileCollectParams) => {
+  const files = collectFiles(fileCollectParams);
+  debug('executing %d test file(s) in parallel mode', files.length);
+  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 = [],
+    ignore = [],
+    file = [],
+    parallel = false,
+    recursive = false,
+    sort = false,
+    spec = []
+  } = options;
+
+  const fileCollectParams = {
+    ignore,
+    extension,
+    file,
+    recursive,
+    sort,
+    spec
+  };
+
+  let run;
+  if (watch) {
+    run = parallel ? watchParallelRun : watchRun;
+  } else {
+    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. 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 {"reporter"|"ui"} pluginType - Type of plugin.
+ * @param {Object} [map] - Used as a cache of sorts;
+ * `Mocha.reporters` where each key corresponds to a reporter name,
+ * `Mocha.interfaces` where each key corresponds to an interface name.
+ * @private
+ */
+exports.validateLegacyPlugin = (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 createInvalidLegacyPluginError(
+      `"--${pluginType}" can only be specified once`,
+      pluginType
+    );
+  }
+
+  const createUnknownError = err =>
+    createInvalidLegacyPluginError(
+      format('Could not load %s "%s":\n\n %O', pluginType, pluginId, err),
+      pluginType,
+      pluginId
+    );
+
+  // if this exists, then it's already loaded, so nothing more to do.
+  if (!map[pluginId]) {
+    try {
+      map[pluginId] = require(pluginId);
+    } catch (err) {
+      if (err.code === 'MODULE_NOT_FOUND') {
+        // Try to load reporters from a path (absolute or relative)
+        try {
+          map[pluginId] = require(path.resolve(pluginId));
+        } catch (err) {
+          throw createUnknownError(err);
+        }
+      } else {
+        throw createUnknownError(err);
+      }
+    }
+  }
+};