mocha 9.1.2

package/lib/errors.js

@@ -0,0 +1,563 @@
+'use strict';
+
+const {format} = require('util');
+
+/**
+ * Contains error codes, factory functions to create throwable error objects,
+ * and warning/deprecation functions.
+ * @module
+ */
+
+/**
+ * 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',
+
+  /**
+   * 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',
+
+  /**
+   * 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
+ */
+function createNoFilesMatchPatternError(message, pattern) {
+  var err = new Error(message);
+  err.code = constants.NO_FILES_MATCH_PATTERN;
+  err.pattern = pattern;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when the reporter specified in the options was not found.
+ *
+ * @public
+ * @param {string} message - Error message to be displayed.
+ * @param {string} reporter - User-specified reporter value.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidReporterError(message, reporter) {
+  var err = new TypeError(message);
+  err.code = constants.INVALID_REPORTER;
+  err.reporter = reporter;
+  return err;
+}
+
+/**
+ * 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
+ */
+function createInvalidInterfaceError(message, ui) {
+  var err = new Error(message);
+  err.code = constants.INVALID_INTERFACE;
+  err.interface = ui;
+  return err;
+}
+
+/**
+ * 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
+ */
+function createUnsupportedError(message) {
+  var err = new Error(message);
+  err.code = constants.UNSUPPORTED;
+  return err;
+}
+
+/**
+ * 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.
+ * @returns {Error} instance detailing the error condition
+ */
+function createMissingArgumentError(message, argument, expected) {
+  return createInvalidArgumentTypeError(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.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidArgumentTypeError(message, argument, expected) {
+  var err = new TypeError(message);
+  err.code = constants.INVALID_ARG_TYPE;
+  err.argument = argument;
+  err.expected = expected;
+  err.actual = typeof argument;
+  return err;
+}
+
+/**
+ * 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.
+ * @param {string} [reason] - Why value is invalid.
+ * @returns {Error} instance detailing the error condition
+ */
+function createInvalidArgumentValueError(message, argument, value, reason) {
+  var err = new TypeError(message);
+  err.code = constants.INVALID_ARG_VALUE;
+  err.argument = argument;
+  err.value = value;
+  err.reason = typeof reason !== 'undefined' ? reason : 'is invalid';
+  return err;
+}
+
+/**
+ * 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
+ */
+function createInvalidExceptionError(message, value) {
+  var err = new Error(message);
+  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
+ * @static
+ * @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"|"ui"} 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 createInvalidLegacyPluginError(message, pluginType, pluginId) {
+  switch (pluginType) {
+    case 'reporter':
+      return createInvalidReporterError(message, pluginId);
+    case 'ui':
+      return createInvalidInterfaceError(message, pluginId);
+    default:
+      throw new Error('unknown pluginType "' + pluginType + '"');
+  }
+}
+
+/**
+ * **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,
+  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.
+ * @static
+ * @public
+ */
+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
+ * @static
+ */
+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;
+}
+
+/**
+ * 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}
+ */
+function createForbiddenExclusivityError(mocha) {
+  var err = new Error(
+    mocha.isWorker
+      ? '`.only` is not supported in parallel mode'
+      : '`.only` forbidden by --forbid-only'
+  );
+  err.code = constants.FORBIDDEN_EXCLUSIVITY;
+  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;
+}
+
+/**
+ * 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}
+ */
+const isMochaError = err =>
+  Boolean(err && typeof err === 'object' && MOCHA_ERRORS.has(err.code));
+
+module.exports = {
+  constants,
+  createFatalError,
+  createForbiddenExclusivityError,
+  createInvalidArgumentTypeError,
+  createInvalidArgumentValueError,
+  createInvalidExceptionError,
+  createInvalidInterfaceError,
+  createInvalidLegacyPluginError,
+  createInvalidPluginDefinitionError,
+  createInvalidPluginError,
+  createInvalidPluginImplementationError,
+  createInvalidReporterError,
+  createMissingArgumentError,
+  createMochaInstanceAlreadyDisposedError,
+  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/hook.js

@@ -0,0 +1,89 @@
+'use strict';
+
+var Runnable = require('./runnable');
+const {inherits, constants} = require('./utils');
+const {MOCHA_ID_PROP_NAME} = constants;
+
+/**
+ * Expose `Hook`.
+ */
+
+module.exports = Hook;
+
+/**
+ * Initialize a new `Hook` with the given `title` and callback `fn`
+ *
+ * @class
+ * @extends Runnable
+ * @param {String} title
+ * @param {Function} fn
+ */
+function Hook(title, fn) {
+  Runnable.call(this, title, fn);
+  this.type = 'hook';
+}
+
+/**
+ * Inherit from `Runnable.prototype`.
+ */
+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`.
+ *
+ * @memberof Hook
+ * @public
+ * @param {Error} err
+ * @return {Error}
+ */
+Hook.prototype.error = function(err) {
+  if (!arguments.length) {
+    err = this._error;
+    this._error = null;
+    return err;
+  }
+
+  this._error = err;
+};
+
+/**
+ * Returns an object suitable for IPC.
+ * Functions are represented by keys beginning with `$$`.
+ * @private
+ * @returns {Object}
+ */
+Hook.prototype.serialize = function serialize() {
+  return {
+    $$currentRetry: this.currentRetry(),
+    $$fullTitle: this.fullTitle(),
+    $$isPending: Boolean(this.isPending()),
+    $$titlePath: this.titlePath(),
+    ctx:
+      this.ctx && this.ctx.currentTest
+        ? {
+            currentTest: {
+              title: this.ctx.currentTest.title,
+              [MOCHA_ID_PROP_NAME]: this.ctx.currentTest.id
+            }
+          }
+        : {},
+    duration: this.duration,
+    file: this.file,
+    parent: {
+      $$fullTitle: this.parent.fullTitle(),
+      [MOCHA_ID_PROP_NAME]: this.parent.id
+    },
+    state: this.state,
+    title: this.title,
+    type: this.type,
+    [MOCHA_ID_PROP_NAME]: this.id
+  };
+};