mocha 7.0.1 → 7.2.0

package/lib/errors.js

@@ -1,10 +1,73 @@
 'use strict';
+
+var format = require('util').format;
+
 /**
+ * Factory functions to create throwable error objects
  * @module Errors
  */
+
 /**
- * Factory functions to create throwable error objects
+ * 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`.
  */
+var constants = {
+  /**
+   * An unrecoverable error.
+   */
+  FATAL: 'ERR_MOCHA_FATAL',
+
+  /**
+   * The type of an argument to a function call is invalid
+   */
+  INVALID_ARG_TYPE: 'ERR_MOCHA_INVALID_ARG_TYPE',
+
+  /**
+   * The value of an argument to a function call is invalid
+   */
+  INVALID_ARG_VALUE: 'ERR_MOCHA_INVALID_ARG_VALUE',
+
+  /**
+   * Something was thrown, but it wasn't an `Error`
+   */
+  INVALID_EXCEPTION: 'ERR_MOCHA_INVALID_EXCEPTION',
+
+  /**
+   * An interface (e.g., `Mocha.interfaces`) is unknown or invalid
+   */
+  INVALID_INTERFACE: 'ERR_MOCHA_INVALID_INTERFACE',
+
+  /**
+   * A reporter (.e.g, `Mocha.reporters`) is unknown or invalid
+   */
+  INVALID_REPORTER: 'ERR_MOCHA_INVALID_REPORTER',
+
+  /**
+   * `done()` was called twice in a `Test` or `Hook` callback
+   */
+  MULTIPLE_DONE: 'ERR_MOCHA_MULTIPLE_DONE',
+
+  /**
+   * No files matched the pattern provided by the user
+   */
+  NO_FILES_MATCH_PATTERN: 'ERR_MOCHA_NO_FILES_MATCH_PATTERN',
+
+  /**
+   * Known, but unsupported behavior of some kind
+   */
+  UNSUPPORTED: 'ERR_MOCHA_UNSUPPORTED',
+
+  /**
+   * Invalid state transition occuring in `Mocha` instance
+   */
+  INSTANCE_ALREADY_RUNNING: 'ERR_MOCHA_INSTANCE_ALREADY_RUNNING',
+
+  /**
+   * Invalid state transition occuring in `Mocha` instance
+   */
+  INSTANCE_ALREADY_DISPOSED: 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED'
+};
 
 /**
  * Creates an error object to be thrown when no files to be tested could be found using specified pattern.
@@ -16,7 +79,7 @@
  */
 function createNoFilesMatchPatternError(message, pattern) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_NO_FILES_MATCH_PATTERN';
+  err.code = constants.NO_FILES_MATCH_PATTERN;
   err.pattern = pattern;
   return err;
 }
@@ -31,7 +94,7 @@ function createNoFilesMatchPatternError(message, pattern) {
  */
 function createInvalidReporterError(message, reporter) {
   var err = new TypeError(message);
-  err.code = 'ERR_MOCHA_INVALID_REPORTER';
+  err.code = constants.INVALID_REPORTER;
   err.reporter = reporter;
   return err;
 }
@@ -46,7 +109,7 @@ function createInvalidReporterError(message, reporter) {
  */
 function createInvalidInterfaceError(message, ui) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_INVALID_INTERFACE';
+  err.code = constants.INVALID_INTERFACE;
   err.interface = ui;
   return err;
 }
@@ -60,7 +123,7 @@ function createInvalidInterfaceError(message, ui) {
  */
 function createUnsupportedError(message) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_UNSUPPORTED';
+  err.code = constants.UNSUPPORTED;
   return err;
 }
 
@@ -88,7 +151,7 @@ function createMissingArgumentError(message, argument, expected) {
  */
 function createInvalidArgumentTypeError(message, argument, expected) {
   var err = new TypeError(message);
-  err.code = 'ERR_MOCHA_INVALID_ARG_TYPE';
+  err.code = constants.INVALID_ARG_TYPE;
   err.argument = argument;
   err.expected = expected;
   err.actual = typeof argument;
@@ -107,7 +170,7 @@ function createInvalidArgumentTypeError(message, argument, expected) {
  */
 function createInvalidArgumentValueError(message, argument, value, reason) {
   var err = new TypeError(message);
-  err.code = 'ERR_MOCHA_INVALID_ARG_VALUE';
+  err.code = constants.INVALID_ARG_VALUE;
   err.argument = argument;
   err.value = value;
   err.reason = typeof reason !== 'undefined' ? reason : 'is invalid';
@@ -123,12 +186,113 @@ function createInvalidArgumentValueError(message, argument, value, reason) {
  */
 function createInvalidExceptionError(message, value) {
   var err = new Error(message);
-  err.code = 'ERR_MOCHA_INVALID_EXCEPTION';
+  err.code = constants.INVALID_EXCEPTION;
+  err.valueType = typeof value;
+  err.value = value;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when an unrecoverable error occurs.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @returns {Error} instance detailing the error condition
+ */
+function createFatalError(message, value) {
+  var err = new Error(message);
+  err.code = constants.FATAL;
   err.valueType = typeof value;
   err.value = value;
   return err;
 }
 
+/**
+ * Dynamically creates a plugin-type-specific error based on plugin type
+ * @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
+ * @returns {Error}
+ */
+function createInvalidPluginError(message, pluginType, pluginId) {
+  switch (pluginType) {
+    case 'reporter':
+      return createInvalidReporterError(message, pluginId);
+    case 'interface':
+      return createInvalidInterfaceError(message, pluginId);
+    default:
+      throw new Error('unknown pluginType "' + pluginType + '"');
+  }
+}
+
+/**
+ * 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
+ */
+function createMochaInstanceAlreadyDisposedError(
+  message,
+  cleanReferencesAfterRun,
+  instance
+) {
+  var err = new Error(message);
+  err.code = constants.INSTANCE_ALREADY_DISPOSED;
+  err.cleanReferencesAfterRun = cleanReferencesAfterRun;
+  err.instance = instance;
+  return err;
+}
+
+/**
+ * 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.
+ */
+function createMochaInstanceAlreadyRunningError(message, instance) {
+  var err = new Error(message);
+  err.code = constants.INSTANCE_ALREADY_RUNNING;
+  err.instance = 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
+ */
+function createMultipleDoneError(runnable, originalErr) {
+  var title;
+  try {
+    title = format('<%s>', runnable.fullTitle());
+    if (runnable.parent.root) {
+      title += ' (of root suite)';
+    }
+  } catch (ignored) {
+    title = format('<%s> (of unknown suite)', runnable.title);
+  }
+  var message = format(
+    'done() called multiple times in %s %s',
+    runnable.type ? runnable.type : 'unknown runnable',
+    title
+  );
+  if (runnable.file) {
+    message += format(' of file %s', runnable.file);
+  }
+  if (originalErr) {
+    message += format('; in addition, done() received error: %s', originalErr);
+  }
+
+  var err = new Error(message);
+  err.code = constants.MULTIPLE_DONE;
+  err.valueType = typeof originalErr;
+  err.value = originalErr;
+  return err;
+}
+
 module.exports = {
   createInvalidArgumentTypeError: createInvalidArgumentTypeError,
   createInvalidArgumentValueError: createInvalidArgumentValueError,
@@ -137,5 +301,11 @@ module.exports = {
   createInvalidReporterError: createInvalidReporterError,
   createMissingArgumentError: createMissingArgumentError,
   createNoFilesMatchPatternError: createNoFilesMatchPatternError,
-  createUnsupportedError: createUnsupportedError
+  createUnsupportedError: createUnsupportedError,
+  createInvalidPluginError: createInvalidPluginError,
+  createMochaInstanceAlreadyDisposedError: createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError: createMochaInstanceAlreadyRunningError,
+  createFatalError: createFatalError,
+  createMultipleDoneError: createMultipleDoneError,
+  constants: constants
 };

package/lib/esm-utils.js

@@ -0,0 +1,31 @@
+const url = require('url');
+const path = require('path');
+
+const requireOrImport = async file => {
+  file = path.resolve(file);
+
+  if (path.extname(file) === '.mjs') {
+    return import(url.pathToFileURL(file));
+  }
+  // This is currently the only known way of figuring out whether a file is CJS or ESM.
+  // If Node.js or the community establish a better procedure for that, we can fix this code.
+  // Another option here would be to always use `import()`, as this also supports CJS, but I would be
+  // wary of using it for _all_ existing test files, till ESM is fully stable.
+  try {
+    return require(file);
+  } catch (err) {
+    if (err.code === 'ERR_REQUIRE_ESM') {
+      return import(url.pathToFileURL(file));
+    } else {
+      throw err;
+    }
+  }
+};
+
+exports.loadFilesAsync = async (files, preLoadFunc, postLoadFunc) => {
+  for (const file of files) {
+    preLoadFunc(file);
+    const result = await requireOrImport(file);
+    postLoadFunc(file, result);
+  }
+};

package/lib/hook.js

@@ -27,6 +27,14 @@ function Hook(title, fn) {
  */
 inherits(Hook, Runnable);
 
+/**
+ * Resets the state for a next run.
+ */
+Hook.prototype.reset = function() {
+  Runnable.prototype.reset.call(this);
+  delete this._error;
+};
+
 /**
  * Get or set the test `err`.
  *

package/lib/interfaces/common.js

@@ -3,6 +3,7 @@
 var Suite = require('../suite');
 var errors = require('../errors');
 var createMissingArgumentError = errors.createMissingArgumentError;
+var createUnsupportedError = errors.createUnsupportedError;
 
 /**
  * Functions common to more than one interface.
@@ -126,14 +127,14 @@ module.exports = function(suites, context, mocha) {
         suites.unshift(suite);
         if (opts.isOnly) {
           if (mocha.options.forbidOnly && shouldBeTested(suite)) {
-            throw new Error('`.only` forbidden');
+            throw createUnsupportedError('`.only` forbidden');
           }
 
           suite.parent.appendOnlySuite(suite);
         }
         if (suite.pending) {
           if (mocha.options.forbidPending && shouldBeTested(suite)) {
-            throw new Error('Pending test forbidden');
+            throw createUnsupportedError('Pending test forbidden');
           }
         }
         if (typeof opts.fn === 'function') {
@@ -165,7 +166,9 @@ module.exports = function(suites, context, mocha) {
        * @returns {*}
        */
       only: function(mocha, test) {
-        test.parent.appendOnlyTest(test);
+        if (mocha.options.forbidOnly)
+          throw createUnsupportedError('`.only` forbidden');
+        test.markOnly();
         return test;
       },