mocha 8.1.2 → 8.3.0

package/CHANGELOG.md

@@ -1,9 +1,107 @@
+# 8.3.0 / 2021-02-11
+
+## :tada: Enhancements
+
+- [#4506](https://github.com/mochajs/mocha/issues/4506): Add error code for test timeout errors ([**@boneskull**](https://github.com/boneskull))
+- [#4112](https://github.com/mochajs/mocha/issues/4112): Add BigInt support to stringify util function ([**@JosejeSinohui**](https://github.com/JosejeSinohui))
+
+## :bug: Fixes
+
+- [#4557](https://github.com/mochajs/mocha/issues/4557): Add file location when SyntaxError happens in ESM ([**@giltayar**](https://github.com/giltayar))
+- [#4521](https://github.com/mochajs/mocha/issues/4521): Fix `require` error when bundling Mocha with Webpack ([**@devhazem**](https://github.com/devhazem))
+
+## :book: Documentation
+
+- [#4507](https://github.com/mochajs/mocha/issues/4507): Add support for typescript-style docstrings ([**@boneskull**](https://github.com/boneskull))
+- [#4503](https://github.com/mochajs/mocha/issues/4503): Add GH Actions workflow status badge ([**@outsideris**](https://github.com/outsideris))
+- [#4494](https://github.com/mochajs/mocha/issues/4494): Add example of generating tests dynamically with a closure ([**@maxwellgerber**](https://github.com/maxwellgerber))
+
+## :nut_and_bolt: Other
+
+- [#4556](https://github.com/mochajs/mocha/issues/4556): Upgrade all dependencies to latest stable ([**@AviVahl**](https://github.com/AviVahl))
+- [#4543](https://github.com/mochajs/mocha/issues/4543): Update dependencies yargs and yargs-parser ([**@juergba**](https://github.com/juergba))
+
+Also thanks to [**@outsideris**](https://github.com/outsideris) and [**@HyunSangHan**](https://github.com/HyunSangHan) for various fixes to our website and documentation.
+
+# 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 ([**@irrationelle**](https://github.com/irrationelle))
+- [#4401](https://github.com/mochajs/mocha/issues/4401): Fix missing global variable in browser ([**@irrationnelle**](https://github.com/irrationnelle))
 
 ## :lock: Security Fixes
 

package/LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2011-2020 OpenJS Foundation and contributors, https://openjsf.org
+Copyright (c) 2011-2021 OpenJS Foundation and contributors, https://openjsf.org
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -4,7 +4,18 @@
 
 <p align="center">☕️ Simple, flexible, fun JavaScript test framework for Node.js & The Browser ☕️</p>
 
-<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 align="center">
+<a href="https://github.com/mochajs/mocha/actions?query=workflow%3ATests+branch%3Amaster"><img src="https://github.com/mochajs/mocha/workflows/Tests/badge.svg?branch=master" alt="GitHub Actions 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>
@@ -100,6 +111,6 @@ Finally, come [chat with the maintainers](https://gitter.im/mochajs/contributors
 
 ## License
 
-Copyright 2011-2020 OpenJS Foundation and contributors. Licensed [MIT](https://github.com/mochajs/mocha/blob/master/LICENSE).
+Copyright 2011-2021 OpenJS Foundation and contributors. Licensed [MIT](https://github.com/mochajs/mocha/blob/master/LICENSE).
 
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_large)

package/bin/mocha

@@ -36,8 +36,6 @@ const disableTimeouts = value => {
   if (impliesNoTimeouts(value)) {
     debug('option %s disabled timeouts', value);
     mochaArgs.timeout = 0;
-    delete mochaArgs.timeouts;
-    delete mochaArgs.t;
   }
 };
 
@@ -93,7 +91,6 @@ if (mochaArgs.require && mochaArgs.require.includes('esm')) {
   if (!mochaArgs.require.length) {
     delete mochaArgs.require;
   }
-  delete mochaArgs.r;
 }
 
 if (Object.keys(nodeArgs).length) {

package/lib/browser/growl.js

@@ -125,7 +125,7 @@ function display(runner) {
     cross: '\u274C',
     tick: '\u2705'
   };
-  var logo = require('../../package').notifyLogo;
+  var logo = require('../../package.json').notifyLogo;
   var _message;
   var message;
   var title;

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/collect-files.js

@@ -6,6 +6,7 @@ const debug = require('debug')('mocha:cli:run:helpers');
 const minimatch = require('minimatch');
 const {NO_FILES_MATCH_PATTERN} = require('../errors').constants;
 const lookupFiles = require('./lookup-files');
+const {castArray} = require('../utils');
 
 /**
  * Exports a function that collects test files from CLI parameters.
@@ -21,45 +22,44 @@ const lookupFiles = require('./lookup-files');
  * @returns {string[]} List of files to test
  * @private
  */
-module.exports = ({ignore, extension, file, recursive, sort, spec} = {}) => {
-  let files = [];
+module.exports = ({
+  ignore,
+  extension,
+  file: fileArgs,
+  recursive,
+  sort,
+  spec
+} = {}) => {
   const unmatched = [];
-  spec.forEach(arg => {
-    let newFiles;
+  const specFiles = spec.reduce((specFiles, arg) => {
     try {
-      newFiles = lookupFiles(arg, extension, recursive);
+      const moreSpecFiles = castArray(lookupFiles(arg, extension, recursive))
+        .filter(filename =>
+          ignore.every(pattern => !minimatch(filename, pattern))
+        )
+        .map(filename => path.resolve(filename));
+      return [...specFiles, ...moreSpecFiles];
     } catch (err) {
       if (err.code === NO_FILES_MATCH_PATTERN) {
         unmatched.push({message: err.message, pattern: err.pattern});
-        return;
+        return specFiles;
       }
 
       throw err;
     }
-
-    if (typeof newFiles !== 'undefined') {
-      if (typeof newFiles === 'string') {
-        newFiles = [newFiles];
-      }
-      newFiles = newFiles.filter(fileName =>
-        ignore.every(pattern => !minimatch(fileName, pattern))
-      );
-    }
-
-    files = files.concat(newFiles);
-  });
-
-  const fileArgs = file.map(filepath => path.resolve(filepath));
-  files = files.map(filepath => path.resolve(filepath));
+  }, []);
 
   // ensure we don't sort the stuff from fileArgs; order is important!
   if (sort) {
-    files.sort();
+    specFiles.sort();
   }
 
   // add files given through --file to be ran first
-  files = fileArgs.concat(files);
-  debug('files (in order): ', files);
+  const files = [
+    ...fileArgs.map(filepath => path.resolve(filepath)),
+    ...specFiles
+  ];
+  debug('test files (in order): ', files);
 
   if (!files.length) {
     // give full message details when only 1 file is missing
@@ -70,7 +70,7 @@ module.exports = ({ignore, extension, file, recursive, sort, spec} = {}) => {
     console.error(ansi.red(noneFoundMsg));
     process.exit(1);
   } else {
-    // print messages as an warning
+    // print messages as a warning
     unmatched.forEach(warning => {
       console.warn(ansi.yellow(`Warning: ${warning.message}`));
     });

package/lib/cli/config.js

@@ -38,8 +38,7 @@ const isModuleNotFoundError = err =>
  * returns an object (but could throw)
  */
 const parsers = (exports.parsers = {
-  yaml: filepath =>
-    require('js-yaml').safeLoad(fs.readFileSync(filepath, 'utf8')),
+  yaml: filepath => require('js-yaml').load(fs.readFileSync(filepath, 'utf8')),
   js: filepath => {
     const cwdFilepath = path.resolve(filepath);
     try {

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/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');
@@ -37,7 +38,8 @@ const {isNodeFlag} = require('./node-flags');
 const YARGS_PARSER_CONFIG = {
   'combine-arrays': true,
   'short-option-groups': false,
-  'dot-notation': false
+  'dot-notation': false,
+  'strip-aliased': true
 };
 
 /**
@@ -150,7 +152,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 +169,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 +212,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);
       }
     }
   }