mocha 8.2.1 → 8.4.0

package/lib/errors.js

@@ -17,6 +17,7 @@ const emitWarning = (msg, type) => {
   if (process.emitWarning) {
     process.emitWarning(msg, type);
   } else {
+    /* istanbul ignore next */
     process.nextTick(function() {
       console.warn(type + ': ' + msg);
     });
@@ -53,88 +54,136 @@ const warn = msg => {
 };
 
 /**
- * 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`.
+ * 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',
 
   /**
    * 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
    */
-  INVALID_PLUGIN_DEFINITION: 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION'
+  TIMEOUT: 'ERR_MOCHA_TIMEOUT',
+
+  /**
+   * Input file is not able to be parsed
+   * @constant
+   * @default
+   */
+  UNPARSABLE_FILE: 'ERR_MOCHA_UNPARSABLE_FILE'
 };
 
+/**
+ * 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
@@ -165,6 +214,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
@@ -180,6 +230,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
  */
@@ -193,6 +244,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.
@@ -206,6 +258,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.
@@ -224,6 +277,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.
@@ -243,6 +297,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
  */
@@ -258,6 +313,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
  */
@@ -276,6 +332,7 @@ function createFatalError(message, value) {
  * @param {string} [pluginId] - Name/path of plugin, if any
  * @throws When `pluginType` is not known
  * @public
+ * @static
  * @returns {Error}
  */
 function createInvalidLegacyPluginError(message, pluginType, pluginId) {
@@ -297,6 +354,7 @@ function createInvalidLegacyPluginError(message, pluginType, pluginId) {
  * @param {string} [pluginId] - Name/path of plugin, if any
  * @throws When `pluginType` is not known
  * @public
+ * @static
  * @returns {Error}
  */
 function createInvalidPluginError(...args) {
@@ -309,6 +367,7 @@ function createInvalidPluginError(...args) {
  * @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,
@@ -325,6 +384,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);
@@ -333,13 +394,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;
@@ -373,6 +435,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}
@@ -389,6 +452,7 @@ function createForbiddenExclusivityError(mocha) {
 
 /**
  * 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
@@ -403,6 +467,7 @@ function createInvalidPluginDefinitionError(msg, pluginDef) {
 
 /**
  * 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
@@ -421,9 +486,40 @@ function createInvalidPluginImplementationError(
   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;
+}
+
+/**
+ * Creates an error object to be thrown when file is unparsable
+ * @public
+ * @static
+ * @param {string} message - Error message to be displayed.
+ * @param {string} filename - File name
+ * @returns {Error} Error with code {@link constants.UNPARSABLE_FILE}
+ */
+function createUnparsableFileError(message, filename) {
+  var err = new Error(message);
+  err.code = constants.UNPARSABLE_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}
@@ -449,8 +545,19 @@ module.exports = {
   createMochaInstanceAlreadyRunningError,
   createMultipleDoneError,
   createNoFilesMatchPatternError,
+  createTimeoutError,
+  createUnparsableFileError,
   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);
 };

package/lib/interfaces/bdd.js

@@ -105,13 +105,6 @@ module.exports = function bddInterface(suite) {
     context.xit = context.xspecify = context.it.skip = function(title) {
       return context.it(title);
     };
-
-    /**
-     * Number of attempts to retry.
-     */
-    context.it.retries = function(n) {
-      context.retries(n);
-    };
   });
 };
 

package/lib/interfaces/common.js

@@ -187,15 +187,6 @@ module.exports = function(suites, context, mocha) {
        */
       skip: function(title) {
         context.test(title);
-      },
-
-      /**
-       * Number of retry attempts
-       *
-       * @param {number} n
-       */
-      retries: function(n) {
-        context.retries(n);
       }
     }
   };

package/lib/interfaces/qunit.js

@@ -92,7 +92,6 @@ module.exports = function qUnitInterface(suite) {
     };
 
     context.test.skip = common.test.skip;
-    context.test.retries = common.test.retries;
   });
 };
 

package/lib/interfaces/tdd.js

@@ -99,7 +99,6 @@ module.exports = function(suite) {
     };
 
     context.test.skip = common.test.skip;
-    context.test.retries = common.test.retries;
   });
 };
 

package/lib/mocha.js

@@ -96,6 +96,61 @@ exports.Suite = Suite;
 exports.Hook = require('./hook');
 exports.Test = require('./test');
 
+let currentContext;
+exports.afterEach = function(...args) {
+  return (currentContext.afterEach || currentContext.teardown).apply(
+    this,
+    args
+  );
+};
+exports.after = function(...args) {
+  return (currentContext.after || currentContext.suiteTeardown).apply(
+    this,
+    args
+  );
+};
+exports.beforeEach = function(...args) {
+  return (currentContext.beforeEach || currentContext.setup).apply(this, args);
+};
+exports.before = function(...args) {
+  return (currentContext.before || currentContext.suiteSetup).apply(this, args);
+};
+exports.describe = function(...args) {
+  return (currentContext.describe || currentContext.suite).apply(this, args);
+};
+exports.describe.only = function(...args) {
+  return (currentContext.describe || currentContext.suite).only.apply(
+    this,
+    args
+  );
+};
+exports.describe.skip = function(...args) {
+  return (currentContext.describe || currentContext.suite).skip.apply(
+    this,
+    args
+  );
+};
+exports.it = function(...args) {
+  return (currentContext.it || currentContext.test).apply(this, args);
+};
+exports.it.only = function(...args) {
+  return (currentContext.it || currentContext.test).only.apply(this, args);
+};
+exports.it.skip = function(...args) {
+  return (currentContext.it || currentContext.test).skip.apply(this, args);
+};
+exports.xdescribe = exports.describe.skip;
+exports.xit = exports.it.skip;
+exports.setup = exports.beforeEach;
+exports.suiteSetup = exports.before;
+exports.suiteTeardown = exports.after;
+exports.suite = exports.describe;
+exports.teardown = exports.afterEach;
+exports.test = exports.it;
+exports.run = function(...args) {
+  return currentContext.run.apply(this, args);
+};
+
 /**
  * Constructs a new Mocha instance with `options`.
  *
@@ -125,10 +180,10 @@ exports.Test = require('./test');
  * @param {number} [options.slow] - Slow threshold value.
  * @param {number|string} [options.timeout] - Timeout threshold value.
  * @param {string} [options.ui] - Interface name.
- * @param {boolean} [options.parallel] - Run jobs in parallel
- * @param {number} [options.jobs] - Max number of worker processes for parallel runs
- * @param {MochaRootHookObject} [options.rootHooks] - Hooks to bootstrap the root
- * suite with
+ * @param {boolean} [options.parallel] - Run jobs in parallel.
+ * @param {number} [options.jobs] - Max number of worker processes for parallel runs.
+ * @param {MochaRootHookObject} [options.rootHooks] - Hooks to bootstrap the root suite with.
+ * @param {string[]} [options.require] - Pathname of `rootHooks` plugin for parallel runs.
  * @param {boolean} [options.isWorker] - Should be `true` if `Mocha` process is running in a worker process.
  */
 function Mocha(options = {}) {
@@ -351,20 +406,7 @@ Mocha.prototype.ui = function(ui) {
   bindInterface(this.suite);
 
   this.suite.on(EVENT_FILE_PRE_REQUIRE, function(context) {
-    exports.afterEach = context.afterEach || context.teardown;
-    exports.after = context.after || context.suiteTeardown;
-    exports.beforeEach = context.beforeEach || context.setup;
-    exports.before = context.before || context.suiteSetup;
-    exports.describe = context.describe || context.suite;
-    exports.it = context.it || context.test;
-    exports.xit = context.xit || (context.test && context.test.skip);
-    exports.setup = context.setup || context.beforeEach;
-    exports.suiteSetup = context.suiteSetup || context.before;
-    exports.suiteTeardown = context.suiteTeardown || context.after;
-    exports.suite = context.suite || context.describe;
-    exports.teardown = context.teardown || context.afterEach;
-    exports.test = context.test || context.it;
-    exports.run = context.run;
+    currentContext = context;
   });
 
   return this;
@@ -1299,7 +1341,7 @@ Mocha.prototype.hasGlobalTeardownFixtures = function hasGlobalTeardownFixtures()
  * A (sync) function to assert a user-supplied plugin implementation is valid.
  *
  * Defined in a {@link PluginDefinition}.
- 
+
  * @callback PluginValidator
  * @param {*} value - Value to check
  * @this {PluginDefinition}

package/lib/runnable.js

@@ -5,9 +5,11 @@ var Pending = require('./pending');
 var debug = require('debug')('mocha:runnable');
 var milliseconds = require('ms');
 var utils = require('./utils');
-var errors = require('./errors');
-var createInvalidExceptionError = errors.createInvalidExceptionError;
-var createMultipleDoneError = errors.createMultipleDoneError;
+const {
+  createInvalidExceptionError,
+  createMultipleDoneError,
+  createTimeoutError
+} = require('./errors');
 
 /**
  * Save timer references to avoid Sinon interfering (see GH-237).
@@ -422,14 +424,11 @@ Runnable.prototype.run = function(fn) {
  * @private
  */
 Runnable.prototype._timeoutError = function(ms) {
-  var msg =
-    'Timeout of ' +
-    ms +
-    'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.';
+  let msg = `Timeout of ${ms}ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.`;
   if (this.file) {
     msg += ' (' + this.file + ')';
   }
-  return new Error(msg);
+  return createTimeoutError(msg, ms, this.file);
 };
 
 var constants = utils.defineConstants(

package/lib/utils.js

@@ -298,6 +298,9 @@ function jsonStringify(object, spaces, depth) {
             ? '-0'
             : val.toString();
         break;
+      case 'bigint':
+        val = val.toString() + 'n';
+        break;
       case 'date':
         var sDate = isNaN(val.getTime()) ? val.toString() : val.toISOString();
         val = '[Date: ' + sDate + ']';