mocha 8.1.2 → 8.3.0

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);

package/lib/cli/watch-run.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const logSymbols = require('log-symbols');
 const debug = require('debug')('mocha:cli:watch');
 const path = require('path');
 const chokidar = require('chokidar');
@@ -32,6 +33,7 @@ exports.watchParallelRun = (
   fileCollectParams
 ) => {
   debug('creating parallel watcher');
+
   return createWatcher(mocha, {
     watchFiles,
     watchIgnore,
@@ -39,6 +41,9 @@ exports.watchParallelRun = (
       // I don't know why we're cloning the root suite.
       const rootSuite = mocha.suite.clone();
 
+      // ensure we aren't leaking event listeners
+      mocha.dispose();
+
       // this `require` is needed because the require cache has been cleared.  the dynamic
       // exports set via the below call to `mocha.ui()` won't work properly if a
       // test depends on this module (see `required-tokens.spec.js`).
@@ -68,9 +73,6 @@ exports.watchParallelRun = (
       newMocha.lazyLoadFiles(true);
       return newMocha;
     },
-    afterRun({watcher}) {
-      blastCache(watcher);
-    },
     fileCollectParams
   });
 };
@@ -91,7 +93,6 @@ exports.watchParallelRun = (
  */
 exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
   debug('creating serial watcher');
-  // list of all test files
 
   return createWatcher(mocha, {
     watchFiles,
@@ -102,6 +103,9 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
       // I don't know why we're cloning the root suite.
       const rootSuite = mocha.suite.clone();
 
+      // ensure we aren't leaking event listeners
+      mocha.dispose();
+
       // this `require` is needed because the require cache has been cleared.  the dynamic
       // exports set via the below call to `mocha.ui()` won't work properly if a
       // test depends on this module (see `required-tokens.spec.js`).
@@ -128,9 +132,6 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
 
       return newMocha;
     },
-    afterRun({watcher}) {
-      blastCache(watcher);
-    },
     fileCollectParams
   });
 };
@@ -141,7 +142,6 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
  * @param {Object} opts
  * @param {BeforeWatchRun} [opts.beforeRun] - Function to call before
  * `mocha.run()`
- * @param {AfterWatchRun} [opts.afterRun] - Function to call after `mocha.run()`
  * @param {string[]} [opts.watchFiles] - List of paths and patterns to watch. If
  *   not provided all files with an extension included in
  *   `fileCollectionParams.extension` are watched. See first argument of
@@ -155,13 +155,17 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
  */
 const createWatcher = (
   mocha,
-  {watchFiles, watchIgnore, beforeRun, afterRun, fileCollectParams}
+  {watchFiles, watchIgnore, beforeRun, fileCollectParams}
 ) => {
   if (!watchFiles) {
     watchFiles = fileCollectParams.extension.map(ext => `**/*.${ext}`);
   }
 
   debug('ignoring files matching: %s', watchIgnore);
+  let globalFixtureContext;
+
+  // we handle global fixtures manually
+  mocha.enableGlobalSetup(false).enableGlobalTeardown(false);
 
   const watcher = chokidar.watch(watchFiles, {
     ignored: watchIgnore,
@@ -169,11 +173,14 @@ const createWatcher = (
   });
 
   const rerunner = createRerunner(mocha, watcher, {
-    beforeRun,
-    afterRun
+    beforeRun
   });
 
-  watcher.on('ready', () => {
+  watcher.on('ready', async () => {
+    if (!globalFixtureContext) {
+      debug('triggering global setup');
+      globalFixtureContext = await mocha.runGlobalSetup();
+    }
     rerunner.run();
   });
 
@@ -185,10 +192,39 @@ const createWatcher = (
   process.on('exit', () => {
     showCursor();
   });
-  process.on('SIGINT', () => {
+
+  // this is for testing.
+  // win32 cannot gracefully shutdown via a signal from a parent
+  // process; a `SIGINT` from a parent will cause the process
+  // to immediately exit.  during normal course of operation, a user
+  // will type Ctrl-C and the listener will be invoked, but this
+  // is not possible in automated testing.
+  // there may be another way to solve this, but it too will be a hack.
+  // for our watch tests on win32 we must _fork_ mocha with an IPC channel
+  if (process.connected) {
+    process.on('message', msg => {
+      if (msg === 'SIGINT') {
+        process.emit('SIGINT');
+      }
+    });
+  }
+
+  let exiting = false;
+  process.on('SIGINT', async () => {
     showCursor();
-    console.log('\n');
-    process.exit(128 + 2);
+    console.error(`${logSymbols.warning} [mocha] cleaning up, please wait...`);
+    if (!exiting) {
+      exiting = true;
+      if (mocha.hasGlobalTeardownFixtures()) {
+        debug('running global teardown');
+        try {
+          await mocha.runGlobalTeardown(globalFixtureContext);
+        } catch (err) {
+          console.error(err);
+        }
+      }
+      process.exit(130);
+    }
   });
 
   // Keyboard shortcut for restarting when "rs\n" is typed (ala Nodemon)
@@ -212,12 +248,11 @@ const createWatcher = (
  * @param {FSWatcher} watcher - chokidar `FSWatcher` instance
  * @param {Object} [opts] - Options!
  * @param {BeforeWatchRun} [opts.beforeRun] - Function to call before `mocha.run()`
- * @param {AfterWatchRun} [opts.afterRun] - Function to call after `mocha.run()`
  * @returns {Rerunner}
  * @ignore
  * @private
  */
-const createRerunner = (mocha, watcher, {beforeRun, afterRun} = {}) => {
+const createRerunner = (mocha, watcher, {beforeRun} = {}) => {
   // Set to a `Runner` when mocha is running. Set to `null` when mocha is not
   // running.
   let runner = null;
@@ -226,16 +261,15 @@ const createRerunner = (mocha, watcher, {beforeRun, afterRun} = {}) => {
   let rerunScheduled = false;
 
   const run = () => {
-    mocha = beforeRun ? beforeRun({mocha, watcher}) : mocha;
-
+    mocha = beforeRun ? beforeRun({mocha, watcher}) || mocha : mocha;
     runner = mocha.run(() => {
       debug('finished watch run');
       runner = null;
-      afterRun && afterRun({mocha, watcher});
+      blastCache(watcher);
       if (rerunScheduled) {
         rerun();
       } else {
-        debug('waiting for changes...');
+        console.error(`${logSymbols.info} [mocha] waiting for changes...`);
       }
     });
   };
@@ -333,15 +367,6 @@ const blastCache = watcher => {
  * @returns {Mocha}
  */
 
-/**
- * Callback to be run after `mocha.run()` completes.  Typically used to clear
- * require cache.
- * @callback AfterWatchRun
- * @private
- * @param {{mocha: Mocha, watcher: FSWatcher}} options
- * @returns {void}
- */
-
 /**
  * Object containing run control methods
  * @typedef {Object} Rerunner

package/lib/errors.js

@@ -1,83 +1,182 @@
 'use strict';
 
-var format = require('util').format;
+const {format} = require('util');
 
 /**
- * Factory functions to create throwable error objects
- * @module Errors
+ * Contains error codes, factory functions to create throwable error objects,
+ * and warning/deprecation functions.
+ * @module
  */
 
 /**
- * When Mocha throw exceptions (or otherwise errors), it attempts to assign a
- * `code` property to the `Error` object, for easier handling.  These are the
- * potential values of `code`.
+ * process.emitWarning or a polyfill
+ * @see https://nodejs.org/api/process.html#process_process_emitwarning_warning_options
+ * @ignore
+ */
+const emitWarning = (msg, type) => {
+  if (process.emitWarning) {
+    process.emitWarning(msg, type);
+  } else {
+    /* istanbul ignore next */
+    process.nextTick(function() {
+      console.warn(type + ': ' + msg);
+    });
+  }
+};
+
+/**
+ * Show a deprecation warning. Each distinct message is only displayed once.
+ * Ignores empty messages.
+ *
+ * @param {string} [msg] - Warning to print
+ * @private
+ */
+const deprecate = msg => {
+  msg = String(msg);
+  if (msg && !deprecate.cache[msg]) {
+    deprecate.cache[msg] = true;
+    emitWarning(msg, 'DeprecationWarning');
+  }
+};
+deprecate.cache = {};
+
+/**
+ * Show a generic warning.
+ * Ignores empty messages.
+ *
+ * @param {string} [msg] - Warning to print
+ * @private
+ */
+const warn = msg => {
+  if (msg) {
+    emitWarning(msg);
+  }
+};
+
+/**
+ * When Mocha throws exceptions (or rejects `Promise`s), it attempts to assign a `code` property to the `Error` object, for easier handling. These are the potential values of `code`.
+ * @public
+ * @namespace
+ * @memberof module:lib/errors
  */
 var constants = {
   /**
    * An unrecoverable error.
+   * @constant
+   * @default
    */
   FATAL: 'ERR_MOCHA_FATAL',
 
   /**
    * The type of an argument to a function call is invalid
+   * @constant
+   * @default
    */
   INVALID_ARG_TYPE: 'ERR_MOCHA_INVALID_ARG_TYPE',
 
   /**
    * The value of an argument to a function call is invalid
+   * @constant
+   * @default
    */
   INVALID_ARG_VALUE: 'ERR_MOCHA_INVALID_ARG_VALUE',
 
   /**
    * Something was thrown, but it wasn't an `Error`
+   * @constant
+   * @default
    */
   INVALID_EXCEPTION: 'ERR_MOCHA_INVALID_EXCEPTION',
 
   /**
    * An interface (e.g., `Mocha.interfaces`) is unknown or invalid
+   * @constant
+   * @default
    */
   INVALID_INTERFACE: 'ERR_MOCHA_INVALID_INTERFACE',
 
   /**
    * A reporter (.e.g, `Mocha.reporters`) is unknown or invalid
+   * @constant
+   * @default
    */
   INVALID_REPORTER: 'ERR_MOCHA_INVALID_REPORTER',
 
   /**
    * `done()` was called twice in a `Test` or `Hook` callback
+   * @constant
+   * @default
    */
   MULTIPLE_DONE: 'ERR_MOCHA_MULTIPLE_DONE',
 
   /**
    * No files matched the pattern provided by the user
+   * @constant
+   * @default
    */
   NO_FILES_MATCH_PATTERN: 'ERR_MOCHA_NO_FILES_MATCH_PATTERN',
 
   /**
    * Known, but unsupported behavior of some kind
+   * @constant
+   * @default
    */
   UNSUPPORTED: 'ERR_MOCHA_UNSUPPORTED',
 
   /**
    * Invalid state transition occurring in `Mocha` instance
+   * @constant
+   * @default
    */
   INSTANCE_ALREADY_RUNNING: 'ERR_MOCHA_INSTANCE_ALREADY_RUNNING',
 
   /**
    * Invalid state transition occurring in `Mocha` instance
+   * @constant
+   * @default
    */
   INSTANCE_ALREADY_DISPOSED: 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED',
 
   /**
    * Use of `only()` w/ `--forbid-only` results in this error.
+   * @constant
+   * @default
    */
-  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY'
+  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY',
+
+  /**
+   * To be thrown when a user-defined plugin implementation (e.g., `mochaHooks`) is invalid
+   * @constant
+   * @default
+   */
+  INVALID_PLUGIN_IMPLEMENTATION: 'ERR_MOCHA_INVALID_PLUGIN_IMPLEMENTATION',
+
+  /**
+   * To be thrown when a builtin or third-party plugin definition (the _definition_ of `mochaHooks`) is invalid
+   * @constant
+   * @default
+   */
+  INVALID_PLUGIN_DEFINITION: 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION',
+
+  /**
+   * When a runnable exceeds its allowed run time.
+   * @constant
+   * @default
+   */
+  TIMEOUT: 'ERR_MOCHA_TIMEOUT'
 };
 
+/**
+ * A set containing all string values of all Mocha error constants, for use by {@link isMochaError}.
+ * @private
+ */
+const MOCHA_ERRORS = new Set(Object.values(constants));
+
 /**
  * Creates an error object to be thrown when no files to be tested could be found using specified pattern.
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @param {string} pattern - User-specified argument value.
  * @returns {Error} instance detailing the error condition
@@ -108,6 +207,7 @@ function createInvalidReporterError(message, reporter) {
  * Creates an error object to be thrown when the interface specified in the options was not found.
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @param {string} ui - User-specified interface value.
  * @returns {Error} instance detailing the error condition
@@ -123,6 +223,7 @@ function createInvalidInterfaceError(message, ui) {
  * Creates an error object to be thrown when a behavior, option, or parameter is unsupported.
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @returns {Error} instance detailing the error condition
  */
@@ -136,6 +237,7 @@ function createUnsupportedError(message) {
  * Creates an error object to be thrown when an argument is missing.
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @param {string} argument - Argument name.
  * @param {string} expected - Expected argument datatype.
@@ -149,6 +251,7 @@ function createMissingArgumentError(message, argument, expected) {
  * Creates an error object to be thrown when an argument did not use the supported type
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @param {string} argument - Argument name.
  * @param {string} expected - Expected argument datatype.
@@ -167,6 +270,7 @@ function createInvalidArgumentTypeError(message, argument, expected) {
  * Creates an error object to be thrown when an argument did not use the supported value
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @param {string} argument - Argument name.
  * @param {string} value - Argument value.
@@ -186,6 +290,7 @@ function createInvalidArgumentValueError(message, argument, value, reason) {
  * Creates an error object to be thrown when an exception was caught, but the `Error` is falsy or undefined.
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @returns {Error} instance detailing the error condition
  */
@@ -201,6 +306,7 @@ function createInvalidExceptionError(message, value) {
  * Creates an error object to be thrown when an unrecoverable error occurs.
  *
  * @public
+ * @static
  * @param {string} message - Error message to be displayed.
  * @returns {Error} instance detailing the error condition
  */
@@ -219,9 +325,10 @@ function createFatalError(message, value) {
  * @param {string} [pluginId] - Name/path of plugin, if any
  * @throws When `pluginType` is not known
  * @public
+ * @static
  * @returns {Error}
  */
-function createInvalidPluginError(message, pluginType, pluginId) {
+function createInvalidLegacyPluginError(message, pluginType, pluginId) {
   switch (pluginType) {
     case 'reporter':
       return createInvalidReporterError(message, pluginId);
@@ -232,11 +339,28 @@ function createInvalidPluginError(message, pluginType, pluginId) {
   }
 }
 
+/**
+ * **DEPRECATED**.  Use {@link createInvalidLegacyPluginError} instead  Dynamically creates a plugin-type-specific error based on plugin type
+ * @deprecated
+ * @param {string} message - Error message
+ * @param {"reporter"|"interface"} pluginType - Plugin type. Future: expand as needed
+ * @param {string} [pluginId] - Name/path of plugin, if any
+ * @throws When `pluginType` is not known
+ * @public
+ * @static
+ * @returns {Error}
+ */
+function createInvalidPluginError(...args) {
+  deprecate('Use createInvalidLegacyPluginError() instead');
+  return createInvalidLegacyPluginError(...args);
+}
+
 /**
  * Creates an error object to be thrown when a mocha object's `run` method is executed while it is already disposed.
  * @param {string} message The error message to be displayed.
  * @param {boolean} cleanReferencesAfterRun the value of `cleanReferencesAfterRun`
  * @param {Mocha} instance the mocha instance that throw this error
+ * @static
  */
 function createMochaInstanceAlreadyDisposedError(
   message,
@@ -253,6 +377,8 @@ function createMochaInstanceAlreadyDisposedError(
 /**
  * Creates an error object to be thrown when a mocha object's `run` method is called while a test run is in progress.
  * @param {string} message The error message to be displayed.
+ * @static
+ * @public
  */
 function createMochaInstanceAlreadyRunningError(message, instance) {
   var err = new Error(message);
@@ -261,13 +387,14 @@ function createMochaInstanceAlreadyRunningError(message, instance) {
   return err;
 }
 
-/*
+/**
  * Creates an error object to be thrown when done() is called multiple times in a test
  *
  * @public
  * @param {Runnable} runnable - Original runnable
  * @param {Error} [originalErr] - Original error, if any
  * @returns {Error} instance detailing the error condition
+ * @static
  */
 function createMultipleDoneError(runnable, originalErr) {
   var title;
@@ -301,6 +428,7 @@ function createMultipleDoneError(runnable, originalErr) {
 /**
  * Creates an error object to be thrown when `.only()` is used with
  * `--forbid-only`.
+ * @static
  * @public
  * @param {Mocha} mocha - Mocha instance
  * @returns {Error} Error with code {@link constants.FORBIDDEN_EXCLUSIVITY}
@@ -315,20 +443,99 @@ function createForbiddenExclusivityError(mocha) {
   return err;
 }
 
+/**
+ * Creates an error object to be thrown when a plugin definition is invalid
+ * @static
+ * @param {string} msg - Error message
+ * @param {PluginDefinition} [pluginDef] - Problematic plugin definition
+ * @public
+ * @returns {Error} Error with code {@link constants.INVALID_PLUGIN_DEFINITION}
+ */
+function createInvalidPluginDefinitionError(msg, pluginDef) {
+  const err = new Error(msg);
+  err.code = constants.INVALID_PLUGIN_DEFINITION;
+  err.pluginDef = pluginDef;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when a plugin implementation (user code) is invalid
+ * @static
+ * @param {string} msg - Error message
+ * @param {Object} [opts] - Plugin definition and user-supplied implementation
+ * @param {PluginDefinition} [opts.pluginDef] - Plugin Definition
+ * @param {*} [opts.pluginImpl] - Plugin Implementation (user-supplied)
+ * @public
+ * @returns {Error} Error with code {@link constants.INVALID_PLUGIN_DEFINITION}
+ */
+function createInvalidPluginImplementationError(
+  msg,
+  {pluginDef, pluginImpl} = {}
+) {
+  const err = new Error(msg);
+  err.code = constants.INVALID_PLUGIN_IMPLEMENTATION;
+  err.pluginDef = pluginDef;
+  err.pluginImpl = pluginImpl;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when a runnable exceeds its allowed run time.
+ * @static
+ * @param {string} msg - Error message
+ * @param {number} [timeout] - Timeout in ms
+ * @param {string} [file] - File, if given
+ * @returns {MochaTimeoutError}
+ */
+function createTimeoutError(msg, timeout, file) {
+  const err = new Error(msg);
+  err.code = constants.TIMEOUT;
+  err.timeout = timeout;
+  err.file = file;
+  return err;
+}
+
+/**
+ * Returns `true` if an error came out of Mocha.
+ * _Can suffer from false negatives, but not false positives._
+ * @static
+ * @public
+ * @param {*} err - Error, or anything
+ * @returns {boolean}
+ */
+const isMochaError = err =>
+  Boolean(err && typeof err === 'object' && MOCHA_ERRORS.has(err.code));
+
 module.exports = {
-  createInvalidArgumentTypeError: createInvalidArgumentTypeError,
-  createInvalidArgumentValueError: createInvalidArgumentValueError,
-  createInvalidExceptionError: createInvalidExceptionError,
-  createInvalidInterfaceError: createInvalidInterfaceError,
-  createInvalidReporterError: createInvalidReporterError,
-  createMissingArgumentError: createMissingArgumentError,
-  createNoFilesMatchPatternError: createNoFilesMatchPatternError,
-  createUnsupportedError: createUnsupportedError,
-  createInvalidPluginError: createInvalidPluginError,
-  createMochaInstanceAlreadyDisposedError: createMochaInstanceAlreadyDisposedError,
-  createMochaInstanceAlreadyRunningError: createMochaInstanceAlreadyRunningError,
-  createFatalError: createFatalError,
-  createMultipleDoneError: createMultipleDoneError,
-  createForbiddenExclusivityError: createForbiddenExclusivityError,
-  constants: constants
+  constants,
+  createFatalError,
+  createForbiddenExclusivityError,
+  createInvalidArgumentTypeError,
+  createInvalidArgumentValueError,
+  createInvalidExceptionError,
+  createInvalidInterfaceError,
+  createInvalidLegacyPluginError,
+  createInvalidPluginDefinitionError,
+  createInvalidPluginError,
+  createInvalidPluginImplementationError,
+  createInvalidReporterError,
+  createMissingArgumentError,
+  createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError,
+  createMultipleDoneError,
+  createNoFilesMatchPatternError,
+  createTimeoutError,
+  createUnsupportedError,
+  deprecate,
+  isMochaError,
+  warn
 };
+
+/**
+ * The error thrown when a Runnable times out
+ * @memberof module:lib/errors
+ * @typedef {Error} MochaTimeoutError
+ * @property {constants.TIMEOUT} code - Error code
+ * @property {number?} timeout Timeout in ms
+ * @property {string?} file Filepath, if given
+ */

package/lib/esm-utils.js

@@ -3,7 +3,29 @@ const url = require('url');
 
 const formattedImport = async file => {
   if (path.isAbsolute(file)) {
-    return import(url.pathToFileURL(file));
+    try {
+      return await import(url.pathToFileURL(file));
+    } catch (err) {
+      // This is a hack created because ESM in Node.js (at least in Node v15.5.1) does not emit
+      // the location of the syntax error in the error thrown.
+      // This is problematic because the user can't see what file has the problem,
+      // so we add the file location to the error.
+      // This `if` should be removed once Node.js fixes the problem.
+      if (
+        err instanceof SyntaxError &&
+        err.message &&
+        err.stack &&
+        !err.stack.includes(file)
+      ) {
+        const newErrorWithFilename = new SyntaxError(err.message);
+        newErrorWithFilename.stack = err.stack.replace(
+          /^SyntaxError/,
+          `SyntaxError[ @${file} ]`
+        );
+        throw newErrorWithFilename;
+      }
+      throw err;
+    }
   }
   return import(file);
 };