mocha 7.1.1 → 8.0.1

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

package/lib/cli/run.js

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