mocha 8.1.1 → 8.2.1

package/CHANGELOG.md

@@ -1,3 +1,91 @@
+# 8.2.1 / 2020-11-02
+
+Fixed stuff.
+
+## :bug: Fixes
+
+- [#4489](https://github.com/mochajs/mocha/issues/4489): Fix problematic handling of otherwise-unhandled `Promise` rejections and erroneous "`done()` called twice" errors ([**@boneskull**](https://github.com/boneskull))
+- [#4496](https://github.com/mochajs/mocha/issues/4496): Avoid `MaxListenersExceededWarning` in watch mode ([**@boneskull**](https://github.com/boneskull))
+
+Also thanks to [**@akeating**](https://github.com/akeating) for a documentation fix!
+
+# 8.2.0 / 2020-10-16
+
+The major feature added in v8.2.0 is addition of support for [_global fixtures_](https://mochajs.org/#global-fixtures).
+
+While Mocha has always had the ability to run setup and teardown via a hook (e.g., a `before()` at the top level of a test file) when running tests in serial, Mocha v8.0.0 added support for parallel runs. Parallel runs are _incompatible_ with this strategy; e.g., a top-level `before()` would only run for the file in which it was defined.
+
+With [global fixtures](https://mochajs.org/#global-fixtures), Mocha can now perform user-defined setup and teardown _regardless_ of mode, and these fixtures are guaranteed to run _once and only once_. This holds for parallel mode, serial mode, and even "watch" mode (the teardown will run once you hit Ctrl-C, just before Mocha finally exits). Tasks such as starting and stopping servers are well-suited to global fixtures, but not sharing resources--global fixtures do _not_ share context with your test files (but they do share context with each other).
+
+Here's a short example of usage:
+
+```js
+// fixtures.js
+
+// can be async or not
+exports.mochaGlobalSetup = async function() {
+  this.server = await startSomeServer({port: process.env.TEST_PORT});
+  console.log(`server running on port ${this.server.port}`);
+};
+
+exports.mochaGlobalTeardown = async function() {
+  // the context (`this`) is shared, but not with the test files
+  await this.server.stop();
+  console.log(`server on port ${this.server.port} stopped`);
+};
+
+// this file can contain root hook plugins as well!
+// exports.mochaHooks = { ... }
+```
+
+Fixtures are loaded with `--require`, e.g., `mocha --require fixtures.js`.
+
+For detailed information, please see the [documentation](https://mochajs.org/#global-fixtures) and this handy-dandy [flowchart](https://mochajs.org/#test-fixture-decision-tree-wizard-thing) to help understand the differences between hooks, root hook plugins, and global fixtures (and when you should use each).
+
+## :tada: Enhancements
+
+- [#4308](https://github.com/mochajs/mocha/issues/4308): Support run-once [global setup & teardown fixtures](https://mochajs.org/#global-fixtures) ([**@boneskull**](https://github.com/boneskull))
+- [#4442](https://github.com/mochajs/mocha/issues/4442): Multi-part extensions (e.g., `test.js`) now usable with `--extension` option ([**@jordanstephens**](https://github.com/jordanstephens))
+- [#4472](https://github.com/mochajs/mocha/issues/4472): Leading dots (e.g., `.js`, `.test.js`) now usable with `--extension` option ([**@boneskull**](https://github.com/boneskull))
+- [#4434](https://github.com/mochajs/mocha/issues/4434): Output of `json` reporter now contains `speed` ("fast"/"medium"/"slow") property ([**@wwhurin**](https://github.com/wwhurin))
+- [#4464](https://github.com/mochajs/mocha/issues/4464): Errors thrown by serializer in parallel mode now have error codes ([**@evaline-ju**](https://github.com/evaline-ju))
+
+_For implementors of custom reporters:_
+
+- [#4409](https://github.com/mochajs/mocha/issues/4409): Parallel mode and custom reporter improvements ([**@boneskull**](https://github.com/boneskull)):
+  - Support custom worker-process-only reporters (`Runner.prototype.workerReporter()`); reporters should subclass `ParallelBufferedReporter` in `mocha/lib/nodejs/reporters/parallel-buffered`
+  - Allow opt-in of object reference matching for "sufficiently advanced" custom reporters (`Runner.prototype.linkPartialObjects()`); use if strict object equality is needed when consuming `Runner` event data
+  - Enable detection of parallel mode (`Runner.prototype.isParallelMode()`)
+
+## :bug: Fixes
+
+- [#4476](https://github.com/mochajs/mocha/issues/4476): Workaround for profoundly bizarre issue affecting `npm` v6.x causing some of Mocha's deps to be installed when `mocha` is present in a package's `devDependencies` and `npm install --production` is run the package's working copy ([**@boneskull**](https://github.com/boneskull))
+- [#4465](https://github.com/mochajs/mocha/issues/4465): Worker processes guaranteed (as opposed to "very likely") to exit before Mocha does; fixes a problem when using `nyc` with Mocha in parallel mode ([**@boneskull**](https://github.com/boneskull))
+- [#4419](https://github.com/mochajs/mocha/issues/4419): Restore `lookupFiles()` in `mocha/lib/utils`, which was broken/missing in Mocha v8.1.0; it now prints a deprecation warning (use `const {lookupFiles} = require('mocha/lib/cli')` instead) ([**@boneskull**](https://github.com/boneskull))
+
+Thanks to [**@AviVahl**](https://github.com/AviVahl), [**@donghoon-song**](https://github.com/donghoon-song), [**@ValeriaVG**](https://github.com/ValeriaVG), [**@znarf**](https://github.com/znarf), [**@sujin-park**](https://github.com/sujin-park), and [**@majecty**](https://github.com/majecty) for other helpful contributions!
+
+# 8.1.3 / 2020-08-28
+
+## :bug: Fixes
+
+- [#4425](https://github.com/mochajs/mocha/issues/4425): Restore `Mocha.utils.lookupFiles()` and Webpack compatibility (both broken since v8.1.0); `Mocha.utils.lookupFiles()` is now **deprecated** and will be removed in the next major revision of Mocha; use `require('mocha/lib/cli').lookupFiles` instead ([**@boneskull**](https://github.com/boneskull))
+
+# 8.1.2 / 2020-08-25
+
+## :bug: Fixes
+
+- [#4418](https://github.com/mochajs/mocha/issues/4418): Fix command-line flag incompatibility in forthcoming Node.js v14.9.0 ([**@boneskull**](https://github.com/boneskull))
+- [#4401](https://github.com/mochajs/mocha/issues/4401): Fix missing global variable in browser ([**@irrationnelle**](https://github.com/irrationnelle))
+
+## :lock: Security Fixes
+
+- [#4396](https://github.com/mochajs/mocha/issues/4396): Update many dependencies ([**@GChuf**](https://github.com/GChuf))
+
+## :book: Documentation
+
+- Various fixes by [**@sujin-park**](https://github.com/sujin-park), [**@wwhurin**](https://github.com/wwhurin) & [**@Donghoon759**](https://github.com/Donghoon759)
+
 # 8.1.1 / 2020-08-04
 
 ## :bug: Fixes

package/README.md

@@ -7,6 +7,8 @@
 <p align="center"><a href="http://travis-ci.org/mochajs/mocha"><img src="https://api.travis-ci.org/mochajs/mocha.svg?branch=master" alt="Build Status"></a>  <a href="https://coveralls.io/github/mochajs/mocha"><img src="https://coveralls.io/repos/github/mochajs/mocha/badge.svg" alt="Coverage Status"></a>  <a href="https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=shield" alt="FOSSA Status"></a>  <a href="https://gitter.im/mochajs/mocha?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Gitter"></a>  <a href="https://github.com/mochajs/mocha#backers"><img src="https://opencollective.com/mochajs/backers/badge.svg" alt="OpenCollective"></a>  <a href="https://github.com/mochajs/mocha#sponsors"><img src="https://opencollective.com/mochajs/sponsors/badge.svg" alt="OpenCollective"></a>
 </p>
 
+<p align="center"><a href="https://www.npmjs.com/package/mocha"><img src="https://img.shields.io/npm/v/mocha.svg" alt="NPM Version"></a>  <a href="https://github.com/mochajs/mocha"><img src="https://img.shields.io/node/v/mocha.svg" alt="Node Version"></a></p>
+
 <p align="center"><br><img alt="Mocha Browser Support h/t SauceLabs" src="https://saucelabs.com/browser-matrix/mochajs.svg" width="354"></p>
 
 ## Links

package/browser-entry.js

@@ -210,8 +210,8 @@ Mocha.process = process;
  * Expose mocha.
  */
 
-mocha.Mocha = Mocha;
-mocha.mocha = mocha;
+global.Mocha = Mocha;
+global.mocha = mocha;
 
 // this allows test/acceptance/required-tokens.js to pass; thus,
 // you can now do `const describe = require('mocha').describe` in a

package/lib/cli/cli.js

@@ -3,19 +3,24 @@
 'use strict';
 
 /**
- * This is where we finally parse and handle arguments passed to the `mocha` executable.
- * Option parsing is handled by {@link https://npm.im/yargs yargs}.
- * If executed via `node`, this module will run {@linkcode module:lib/cli/cli.main main()}.
- *
- * @private
- * @module
+ * Contains CLI entry point and public API for programmatic usage in Node.js.
+ * - Option parsing is handled by {@link https://npm.im/yargs yargs}.
+ * - If executed via `node`, this module will run {@linkcode module:lib/cli.main main()}.
+ * @public
+ * @module lib/cli
  */
 
 const debug = require('debug')('mocha:cli:cli');
 const symbols = require('log-symbols');
 const yargs = require('yargs/yargs');
 const path = require('path');
-const {loadOptions, YARGS_PARSER_CONFIG} = require('./options');
+const {
+  loadRc,
+  loadPkgRc,
+  loadOptions,
+  YARGS_PARSER_CONFIG
+} = require('./options');
+const lookupFiles = require('./lookup-files');
 const commands = require('./commands');
 const ansi = require('ansi-colors');
 const {repository, homepage, version, gitter} = require('../../package.json');
@@ -25,7 +30,8 @@ const {cwd} = require('../utils');
  * - Accepts an `Array` of arguments
  * - Modifies {@link https://nodejs.org/api/modules.html#modules_module_paths Node.js' search path} for easy loading of consumer modules
  * - Sets {@linkcode https://nodejs.org/api/errors.html#errors_error_stacktracelimit Error.stackTraceLimit} to `Infinity`
- * @summary Mocha's main entry point from the command-line.
+ * @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)`
  */
 exports.main = (argv = process.argv.slice(2)) => {
@@ -71,6 +77,11 @@ exports.main = (argv = process.argv.slice(2)) => {
     .parse(args._);
 };
 
+exports.lookupFiles = lookupFiles;
+exports.loadOptions = loadOptions;
+exports.loadPkgRc = loadPkgRc;
+exports.loadRc = loadRc;
+
 // allow direct execution
 if (require.main === module) {
   exports.main();

package/lib/cli/index.js

@@ -1,9 +1,3 @@
 'use strict';
 
-/**
- * Just exports {@link module:lib/cli/cli} for convenience.
- * @private
- * @module lib/cli
- * @exports module:lib/cli/cli
- */
 module.exports = require('./cli');

package/lib/cli/lookup-files.js

@@ -1,4 +1,9 @@
 'use strict';
+/**
+ * Contains `lookupFiles`, which takes some globs/dirs/options and returns a list of files.
+ * @module
+ * @private
+ */
 
 var fs = require('fs');
 var path = require('path');
@@ -8,6 +13,7 @@ var errors = require('../errors');
 var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;
 var createMissingArgumentError = errors.createMissingArgumentError;
 var {sQuote, dQuote} = require('../utils');
+const debug = require('debug')('mocha:cli:lookup-files');
 
 /**
  * Determines if pathname would be a "hidden" file (or directory) on UN*X.
@@ -24,26 +30,26 @@ var {sQuote, dQuote} = require('../utils');
  * @example
  * isHiddenOnUnix('.profile'); // => true
  */
-function isHiddenOnUnix(pathname) {
-  return path.basename(pathname)[0] === '.';
-}
+const isHiddenOnUnix = pathname => path.basename(pathname).startsWith('.');
 
 /**
  * Determines if pathname has a matching file extension.
  *
+ * Supports multi-part extensions.
+ *
  * @private
  * @param {string} pathname - Pathname to check for match.
- * @param {string[]} exts - List of file extensions (sans period).
- * @return {boolean} whether file extension matches.
+ * @param {string[]} exts - List of file extensions, w/-or-w/o leading period
+ * @return {boolean} `true` if file extension matches.
  * @example
- * hasMatchingExtname('foo.html', ['js', 'css']); // => false
+ * hasMatchingExtname('foo.html', ['js', 'css']); // false
+ * hasMatchingExtname('foo.js', ['.js']); // true
+ * hasMatchingExtname('foo.js', ['js']); // ture
  */
-function hasMatchingExtname(pathname, exts) {
-  var suffix = path.extname(pathname).slice(1);
-  return exts.some(function(element) {
-    return suffix === element;
-  });
-}
+const hasMatchingExtname = (pathname, exts = []) =>
+  exts
+    .map(ext => (ext.startsWith('.') ? ext : `.${ext}`))
+    .some(ext => pathname.endsWith(ext));
 
 /**
  * Lookup file names at the given `path`.
@@ -53,7 +59,7 @@ function hasMatchingExtname(pathname, exts) {
  * **Make no assumption that the names will be sorted in any fashion.**
  *
  * @public
- * @memberof Mocha.utils
+ * @alias module:lib/cli.lookupFiles
  * @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.
@@ -61,27 +67,28 @@ function hasMatchingExtname(pathname, exts) {
  * @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;
+module.exports = function lookupFiles(
+  filepath,
+  extensions = [],
+  recursive = false
+) {
+  const files = [];
+  let stat;
 
   if (!fs.existsSync(filepath)) {
-    var pattern;
+    let 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;
-        })
+      const strExtensions = extensions
+        .map(ext => (ext.startsWith('.') ? ext : `.${ext}`))
         .join('|');
-      pattern = filepath + '+(' + strExtensions + ')';
+      pattern = `${filepath}+(${strExtensions})`;
+      debug('looking for files using glob pattern: %s', pattern);
     }
-    files = glob.sync(pattern, {nodir: true});
+    files.push(...glob.sync(pattern, {nodir: true}));
     if (!files.length) {
       throw createNoFilesMatchPatternError(
         'Cannot find any files matching pattern ' + dQuote(filepath),
@@ -103,20 +110,19 @@ module.exports = function lookupFiles(filepath, extensions, recursive) {
   }
 
   // Handle directory
-  fs.readdirSync(filepath).forEach(function(dirent) {
-    var pathname = path.join(filepath, dirent);
-    var stat;
+  fs.readdirSync(filepath).forEach(dirent => {
+    const pathname = path.join(filepath, dirent);
+    let stat;
 
     try {
       stat = fs.statSync(pathname);
       if (stat.isDirectory()) {
         if (recursive) {
-          files = files.concat(lookupFiles(pathname, extensions, recursive));
+          files.push(...lookupFiles(pathname, extensions, recursive));
         }
         return;
       }
-    } catch (err) {
-      // ignore error
+    } catch (ignored) {
       return;
     }
     if (!extensions.length) {

package/lib/cli/node-flags.js

@@ -7,6 +7,7 @@
  */
 
 const nodeFlags = process.allowedNodeEnvironmentFlags;
+const {isMochaFlag} = require('./run-option-metadata');
 const unparse = require('yargs-unparser');
 
 /**
@@ -43,16 +44,14 @@ exports.isNodeFlag = (flag, bareword = true) => {
     flag = flag.replace(/^--?/, '');
   }
   return (
-    // treat --require/-r as Mocha flag even though it's also a node flag
-    !(flag === 'require' || flag === 'r') &&
     // 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 && nodeFlags.has(flag)) ||
-      debugFlags.has(flag) ||
-      /(?:preserve-symlinks(?:-main)?|harmony(?:[_-]|$)|(?:trace[_-].+$)|gc(?:[_-]global)?$|es[_-]staging$|use[_-]strict$|v8[_-](?!options).+?$)/.test(
-        flag
-      ))
+    (!isMochaFlag(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

@@ -3,7 +3,8 @@
 /**
  * Main entry point for handling filesystem-based configuration,
  * whether that's a config file or `package.json` or whatever.
- * @module
+ * @module lib/cli/options
+ * @private
  */
 
 const fs = require('fs');
@@ -150,7 +151,7 @@ const parse = (args = [], defaultValues = {}, ...configObjects) => {
  * @param {Object} [args] - Arguments object
  * @param {string|boolean} [args.config] - Path to config file or `false` to skip
  * @public
- * @memberof module:lib/cli/options
+ * @alias module:lib/cli.loadRc
  * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.config` is `false`
  */
 const loadRc = (args = {}) => {
@@ -167,7 +168,7 @@ module.exports.loadRc = loadRc;
  * @param {Object} [args] - Arguments object
  * @param {string|boolean} [args.config] - Path to `package.json` or `false` to skip
  * @public
- * @memberof module:lib/cli/options
+ * @alias module:lib/cli.loadPkgRc
  * @returns {external:yargsParser.Arguments|void} Parsed config, or nothing if `args.package` is `false`
  */
 const loadPkgRc = (args = {}) => {
@@ -210,7 +211,7 @@ module.exports.loadPkgRc = loadPkgRc;
  * @summary Parses options read from `.mocharc.*` and `package.json`.
  * @param {string|string[]} [argv] - Arguments to parse
  * @public
- * @memberof module:lib/cli/options
+ * @alias module:lib/cli.loadOptions
  * @returns {external:yargsParser.Arguments} Parsed args from everything
  */
 const loadOptions = (argv = []) => {

package/lib/cli/run-helpers.js

@@ -12,10 +12,10 @@ const path = require('path');
 const debug = require('debug')('mocha:cli:run:helpers');
 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 {createInvalidLegacyPluginError} = require('../errors');
 const {requireOrImport} = require('../esm-utils');
+const PluginLoader = require('../plugin-loader');
 
 /**
  * Exits Mocha when tests + code under test has finished execution (default)
@@ -79,12 +79,12 @@ exports.list = str =>
  *
  * Returns array of `mochaHooks` exports, if any.
  * @param {string[]} requires - Modules to require
- * @returns {Promise<MochaRootHookObject|MochaRootHookFunction>} Any root hooks
+ * @returns {Promise<object>} Plugin implementations
  * @private
  */
-exports.handleRequires = async (requires = []) => {
-  const acc = [];
-  for (const mod of requires) {
+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`)) {
@@ -92,49 +92,18 @@ exports.handleRequires = async (requires = []) => {
       debug('resolved required file %s to %s', mod, modpath);
     }
     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'
-        );
+    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);
   }
-  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: []}
-  );
+  const plugins = await pluginLoader.finalize();
+  if (Object.keys(plugins).length) {
+    debug('finalized plugin implementations: %O', plugins);
+  }
+  return plugins;
 };
 
 /**
@@ -172,11 +141,7 @@ const singleRun = async (mocha, {exit}, fileCollectParams) => {
  */
 const parallelRun = async (mocha, options, fileCollectParams) => {
   const files = collectFiles(fileCollectParams);
-  debug(
-    'executing %d test file(s) across %d concurrent jobs',
-    files.length,
-    options.jobs
-  );
+  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
@@ -236,7 +201,7 @@ exports.runMocha = async (mocha, options) => {
  * name
  * @private
  */
-exports.validatePlugin = (opts, pluginType, map = {}) => {
+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.
@@ -245,14 +210,14 @@ exports.validatePlugin = (opts, pluginType, map = {}) => {
   const pluginId = opts[pluginType];
 
   if (Array.isArray(pluginId)) {
-    throw createInvalidPluginError(
+    throw createInvalidLegacyPluginError(
       `"--${pluginType}" can only be specified once`,
       pluginType
     );
   }
 
-  const unknownError = err =>
-    createInvalidPluginError(
+  const createUnknownError = err =>
+    createInvalidLegacyPluginError(
       format('Could not load %s "%s":\n\n %O', pluginType, pluginId, err),
       pluginType,
       pluginId
@@ -268,10 +233,10 @@ exports.validatePlugin = (opts, pluginType, map = {}) => {
         try {
           opts[pluginType] = require(path.resolve(pluginId));
         } catch (err) {
-          throw unknownError(err);
+          throw createUnknownError(err);
         }
       } else {
-        throw unknownError(err);
+        throw createUnknownError(err);
       }
     }
   }

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

@@ -12,7 +12,7 @@
  * @type {{string:string[]}}
  * @private
  */
-exports.types = {
+const TYPES = (exports.types = {
   array: [
     'extension',
     'file',
@@ -58,7 +58,7 @@ exports.types = {
     'slow',
     'timeout'
   ]
-};
+});
 
 /**
  * Option aliases keyed by canonical option name.
@@ -88,3 +88,26 @@ exports.aliases = {
   ui: ['u'],
   watch: ['w']
 };
+
+const ALL_MOCHA_FLAGS = Object.keys(TYPES).reduce((acc, key) => {
+  // gets all flags from each of the fields in `types`, adds those,
+  // then adds aliases of each flag (if any)
+  TYPES[key].forEach(flag => {
+    acc.add(flag);
+    const aliases = exports.aliases[flag] || [];
+    aliases.forEach(alias => {
+      acc.add(alias);
+    });
+  });
+  return acc;
+}, new Set());
+
+/**
+ * Returns `true` if the provided `flag` is known to Mocha.
+ * @param {string} flag - Flag to check
+ * @returns {boolean} If `true`, this is a Mocha flag
+ * @private
+ */
+exports.isMochaFlag = flag => {
+  return ALL_MOCHA_FLAGS.has(flag.replace(/^--?/, ''));
+};

package/lib/cli/run.js

@@ -19,8 +19,7 @@ const {
 const {
   list,
   handleRequires,
-  validatePlugin,
-  loadRootHooks,
+  validateLegacyPlugin,
   runMocha
 } = require('./run-helpers');
 const {ONE_AND_DONES, ONE_AND_DONE_ARGS} = require('./one-and-dones');
@@ -339,13 +338,10 @@ exports.builder = 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 && rawRootHooks.length) {
-          argv.rootHooks = await loadRootHooks(rawRootHooks);
-        }
+        const plugins = await handleRequires(argv.require);
+        validateLegacyPlugin(argv, 'reporter', Mocha.reporters);
+        validateLegacyPlugin(argv, 'ui', Mocha.interfaces);
+        Object.assign(argv, plugins);
       } catch (err) {
         // this could be a bad --require, bad reporter, ui, etc.
         console.error(`\n${symbols.error} ${ansi.red('ERROR:')}`, err);