mocha 8.1.3 → 8.2.0

package/lib/errors.js

@@ -1,12 +1,57 @@
 '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
  */
 
+/**
+ * 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 {
+    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 throw exceptions (or otherwise errors), it attempts to assign a
  * `code` property to the `Error` object, for easier handling.  These are the
@@ -71,7 +116,17 @@ var constants = {
   /**
    * Use of `only()` w/ `--forbid-only` results in this error.
    */
-  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
+   */
+  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
+   */
+  INVALID_PLUGIN_DEFINITION: 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION'
 };
 
 /**
@@ -221,7 +276,7 @@ function createFatalError(message, value) {
  * @public
  * @returns {Error}
  */
-function createInvalidPluginError(message, pluginType, pluginId) {
+function createInvalidLegacyPluginError(message, pluginType, pluginId) {
   switch (pluginType) {
     case 'reporter':
       return createInvalidReporterError(message, pluginId);
@@ -232,6 +287,21 @@ 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
+ * @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.
@@ -315,20 +385,59 @@ function createForbiddenExclusivityError(mocha) {
   return err;
 }
 
+/**
+ * Creates an error object to be thrown when a plugin definition is invalid
+ * @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
+ * @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;
+}
+
 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,
+  createUnsupportedError,
+  deprecate,
+  warn
 };

package/lib/hook.js

@@ -1,7 +1,8 @@
 'use strict';
 
 var Runnable = require('./runnable');
-var inherits = require('./utils').inherits;
+const {inherits, constants} = require('./utils');
+const {MOCHA_ID_PROP_NAME} = constants;
 
 /**
  * Expose `Hook`.
@@ -63,16 +64,20 @@ Hook.prototype.serialize = function serialize() {
   return {
     $$isPending: this.isPending(),
     $$titlePath: this.titlePath(),
-    ctx: {
-      currentTest: {
-        title: this.ctx && this.ctx.currentTest && this.ctx.currentTest.title
-      }
-    },
+    ctx:
+      this.ctx && this.ctx.currentTest
+        ? {
+            currentTest: {
+              title: this.ctx.currentTest.title,
+              [MOCHA_ID_PROP_NAME]: this.ctx.currentTest.id
+            }
+          }
+        : {},
     parent: {
-      root: this.parent.root,
-      title: this.parent.title
+      [MOCHA_ID_PROP_NAME]: this.parent.id
     },
     title: this.title,
-    type: this.type
+    type: this.type,
+    [MOCHA_ID_PROP_NAME]: this.id
   };
 };

package/lib/mocha.js

@@ -18,15 +18,18 @@ var esmUtils = utils.supportsEsModules(true)
   : undefined;
 var createStatsCollector = require('./stats-collector');
 const {
-  createUnsupportedError,
-  createInvalidInterfaceError,
+  warn,
   createInvalidReporterError,
+  createInvalidInterfaceError,
   createMochaInstanceAlreadyDisposedError,
-  createMochaInstanceAlreadyRunningError
+  createMochaInstanceAlreadyRunningError,
+  createUnsupportedError
 } = require('./errors');
-var EVENT_FILE_PRE_REQUIRE = Suite.constants.EVENT_FILE_PRE_REQUIRE;
-var EVENT_FILE_POST_REQUIRE = Suite.constants.EVENT_FILE_POST_REQUIRE;
-var EVENT_FILE_REQUIRE = Suite.constants.EVENT_FILE_REQUIRE;
+const {
+  EVENT_FILE_PRE_REQUIRE,
+  EVENT_FILE_POST_REQUIRE,
+  EVENT_FILE_REQUIRE
+} = Suite.constants;
 var sQuote = utils.sQuote;
 var debug = require('debug')('mocha:mocha');
 
@@ -128,8 +131,8 @@ exports.Test = require('./test');
  * suite with
  * @param {boolean} [options.isWorker] - Should be `true` if `Mocha` process is running in a worker process.
  */
-function Mocha(options) {
-  options = utils.assign({}, mocharc, options || {});
+function Mocha(options = {}) {
+  options = {...mocharc, ...options};
   this.files = [];
   this.options = options;
   // root suite
@@ -205,6 +208,11 @@ function Mocha(options) {
    */
   this.isWorker = Boolean(options.isWorker);
 
+  this.globalSetup(options.globalSetup)
+    .globalTeardown(options.globalTeardown)
+    .enableGlobalSetup(options.enableGlobalSetup)
+    .enableGlobalTeardown(options.enableGlobalTeardown);
+
   if (
     options.parallel &&
     (typeof options.jobs === 'undefined' || options.jobs > 1)
@@ -277,25 +285,21 @@ Mocha.prototype.reporter = function(reporterName, reporterOptions) {
       try {
         reporter = require(reporterName);
       } catch (err) {
-        if (
-          err.code === 'MODULE_NOT_FOUND' ||
-          err.message.indexOf('Cannot find module') >= 0
-        ) {
+        if (err.code === 'MODULE_NOT_FOUND') {
           // Try to load reporters from a path (absolute or relative)
           try {
             reporter = require(path.resolve(utils.cwd(), reporterName));
           } catch (_err) {
-            _err.code === 'MODULE_NOT_FOUND' ||
-            _err.message.indexOf('Cannot find module') >= 0
-              ? utils.warn(sQuote(reporterName) + ' reporter not found')
-              : utils.warn(
+            _err.code === 'MODULE_NOT_FOUND'
+              ? warn(sQuote(reporterName) + ' reporter not found')
+              : warn(
                   sQuote(reporterName) +
                     ' reporter blew up with error:\n' +
                     err.stack
                 );
           }
         } else {
-          utils.warn(
+          warn(
             sQuote(reporterName) + ' reporter blew up with error:\n' + err.stack
           );
         }
@@ -965,11 +969,10 @@ Mocha.prototype.run = function(fn) {
   if (this.files.length && !this._lazyLoadFiles) {
     this.loadFiles();
   }
-  var self = this;
   var suite = this.suite;
   var options = this.options;
   options.files = this.files;
-  var runner = new this._runnerClass(suite, {
+  const runner = new this._runnerClass(suite, {
     delay: options.delay,
     cleanReferencesAfterRun: this._cleanReferencesAfterRun
   });
@@ -996,22 +999,42 @@ Mocha.prototype.run = function(fn) {
   exports.reporters.Base.inlineDiffs = options.inlineDiffs;
   exports.reporters.Base.hideDiff = !options.diff;
 
-  function done(failures) {
-    self._previousRunner = runner;
-    if (self._cleanReferencesAfterRun) {
-      self._state = mochaStates.REFERENCES_CLEANED;
-    } else {
-      self._state = mochaStates.INIT;
-    }
+  const done = failures => {
+    this._previousRunner = runner;
+    this._state = this._cleanReferencesAfterRun
+      ? mochaStates.REFERENCES_CLEANED
+      : mochaStates.INIT;
     fn = fn || utils.noop;
-    if (reporter.done) {
+    if (typeof reporter.done === 'function') {
       reporter.done(failures, fn);
     } else {
       fn(failures);
     }
-  }
+  };
+
+  const runAsync = async runner => {
+    const context =
+      this.options.enableGlobalSetup && this.hasGlobalSetupFixtures()
+        ? await this.runGlobalSetup(runner)
+        : {};
+    const failureCount = await runner.runAsync({
+      files: this.files,
+      options
+    });
+    if (this.options.enableGlobalTeardown && this.hasGlobalTeardownFixtures()) {
+      await this.runGlobalTeardown(runner, {context});
+    }
+    return failureCount;
+  };
 
-  return runner.run(done, {files: this.files, options: options});
+  // no "catch" here is intentional. errors coming out of
+  // Runner#run are considered uncaught/unhandled and caught
+  // by the `process` event listeners.
+  // also: returning anything other than `runner` would be a breaking
+  // change
+  runAsync(runner).then(done);
+
+  return runner;
 };
 
 /**
@@ -1019,26 +1042,28 @@ Mocha.prototype.run = function(fn) {
  * @param {MochaRootHookObject} [hooks] - Hooks to assign to root suite
  * @chainable
  */
-Mocha.prototype.rootHooks = function rootHooks(hooks) {
-  if (utils.type(hooks) === 'object') {
-    var beforeAll = [].concat(hooks.beforeAll || []);
-    var beforeEach = [].concat(hooks.beforeEach || []);
-    var afterAll = [].concat(hooks.afterAll || []);
-    var afterEach = [].concat(hooks.afterEach || []);
-    var rootSuite = this.suite;
-    beforeAll.forEach(function(hook) {
-      rootSuite.beforeAll(hook);
-    });
-    beforeEach.forEach(function(hook) {
-      rootSuite.beforeEach(hook);
-    });
-    afterAll.forEach(function(hook) {
-      rootSuite.afterAll(hook);
-    });
-    afterEach.forEach(function(hook) {
-      rootSuite.afterEach(hook);
-    });
-  }
+Mocha.prototype.rootHooks = function rootHooks({
+  beforeAll = [],
+  beforeEach = [],
+  afterAll = [],
+  afterEach = []
+} = {}) {
+  beforeAll = utils.castArray(beforeAll);
+  beforeEach = utils.castArray(beforeEach);
+  afterAll = utils.castArray(afterAll);
+  afterEach = utils.castArray(afterEach);
+  beforeAll.forEach(hook => {
+    this.suite.beforeAll(hook);
+  });
+  beforeEach.forEach(hook => {
+    this.suite.beforeEach(hook);
+  });
+  afterAll.forEach(hook => {
+    this.suite.afterAll(hook);
+  });
+  afterEach.forEach(hook => {
+    this.suite.afterEach(hook);
+  });
   return this;
 };
 
@@ -1047,18 +1072,21 @@ Mocha.prototype.rootHooks = function rootHooks(hooks) {
  *
  * Must be run before calling {@link Mocha#run}. Changes the `Runner` class to
  * use; also enables lazy file loading if not already done so.
+ *
+ * Warning: when passed `false` and lazy loading has been enabled _via any means_ (including calling `parallelMode(true)`), this method will _not_ disable lazy loading. Lazy loading is a prerequisite for parallel
+ * mode, but parallel mode is _not_ a prerequisite for lazy loading!
  * @param {boolean} [enable] - If `true`, enable; otherwise disable.
  * @throws If run in browser
- * @throws If Mocha not in "INIT" state
+ * @throws If Mocha not in `INIT` state
  * @returns {Mocha}
  * @chainable
  * @public
  */
-Mocha.prototype.parallelMode = function parallelMode(enable) {
+Mocha.prototype.parallelMode = function parallelMode(enable = true) {
   if (utils.isBrowser()) {
     throw createUnsupportedError('parallel mode is only supported in Node.js');
   }
-  var parallel = enable === true;
+  const parallel = Boolean(enable);
   if (
     parallel === this.options.parallel &&
     this._lazyLoadFiles &&
@@ -1100,8 +1128,144 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
 };
 
 /**
- * An alternative way to define root hooks that works with parallel runs.
+ * Configures one or more global setup fixtures.
+ *
+ * If given no parameters, _unsets_ any previously-set fixtures.
+ * @chainable
+ * @public
+ * @param {MochaGlobalFixture|MochaGlobalFixture[]} [setupFns] - Global setup fixture(s)
+ * @returns {Mocha}
+ */
+Mocha.prototype.globalSetup = function globalSetup(setupFns = []) {
+  setupFns = utils.castArray(setupFns);
+  this.options.globalSetup = setupFns;
+  debug('configured %d global setup functions', setupFns.length);
+  return this;
+};
+
+/**
+ * Configures one or more global teardown fixtures.
+ *
+ * If given no parameters, _unsets_ any previously-set fixtures.
+ * @chainable
+ * @public
+ * @param {MochaGlobalFixture|MochaGlobalFixture[]} [teardownFns] - Global teardown fixture(s)
+ * @returns {Mocha}
+ */
+Mocha.prototype.globalTeardown = function globalTeardown(teardownFns = []) {
+  teardownFns = utils.castArray(teardownFns);
+  this.options.globalTeardown = teardownFns;
+  debug('configured %d global teardown functions', teardownFns.length);
+  return this;
+};
+
+/**
+ * Run any global setup fixtures sequentially, if any.
+ *
+ * This is _automatically called_ by {@link Mocha#run} _unless_ the `runGlobalSetup` option is `false`; see {@link Mocha#enableGlobalSetup}.
+ *
+ * The context object this function resolves with should be consumed by {@link Mocha#runGlobalTeardown}.
+ * @param {object} [context] - Context object if already have one
+ * @public
+ * @returns {Promise<object>} Context object
+ */
+Mocha.prototype.runGlobalSetup = async function runGlobalSetup(context = {}) {
+  const {globalSetup} = this.options;
+  if (globalSetup && globalSetup.length) {
+    debug('run(): global setup starting');
+    await this._runGlobalFixtures(globalSetup, context);
+    debug('run(): global setup complete');
+  }
+  return context;
+};
+
+/**
+ * Run any global teardown fixtures sequentially, if any.
+ *
+ * This is _automatically called_ by {@link Mocha#run} _unless_ the `runGlobalTeardown` option is `false`; see {@link Mocha#enableGlobalTeardown}.
+ *
+ * Should be called with context object returned by {@link Mocha#runGlobalSetup}, if applicable.
+ * @param {object} [context] - Context object if already have one
+ * @public
+ * @returns {Promise<object>} Context object
+ */
+Mocha.prototype.runGlobalTeardown = async function runGlobalTeardown(
+  context = {}
+) {
+  const {globalTeardown} = this.options;
+  if (globalTeardown && globalTeardown.length) {
+    debug('run(): global teardown starting');
+    await this._runGlobalFixtures(globalTeardown, context);
+  }
+  debug('run(): global teardown complete');
+  return context;
+};
+
+/**
+ * Run global fixtures sequentially with context `context`
  * @private
+ * @param {MochaGlobalFixture[]} [fixtureFns] - Fixtures to run
+ * @param {object} [context] - context object
+ * @returns {Promise<object>} context object
+ */
+Mocha.prototype._runGlobalFixtures = async function _runGlobalFixtures(
+  fixtureFns = [],
+  context = {}
+) {
+  for await (const fixtureFn of fixtureFns) {
+    await fixtureFn.call(context);
+  }
+  return context;
+};
+
+/**
+ * Toggle execution of any global setup fixture(s)
+ *
+ * @chainable
+ * @public
+ * @param {boolean } [enabled=true] - If `false`, do not run global setup fixture
+ * @returns {Mocha}
+ */
+Mocha.prototype.enableGlobalSetup = function enableGlobalSetup(enabled = true) {
+  this.options.enableGlobalSetup = Boolean(enabled);
+  return this;
+};
+
+/**
+ * Toggle execution of any global teardown fixture(s)
+ *
+ * @chainable
+ * @public
+ * @param {boolean } [enabled=true] - If `false`, do not run global teardown fixture
+ * @returns {Mocha}
+ */
+Mocha.prototype.enableGlobalTeardown = function enableGlobalTeardown(
+  enabled = true
+) {
+  this.options.enableGlobalTeardown = Boolean(enabled);
+  return this;
+};
+
+/**
+ * Returns `true` if one or more global setup fixtures have been supplied.
+ * @public
+ * @returns {boolean}
+ */
+Mocha.prototype.hasGlobalSetupFixtures = function hasGlobalSetupFixtures() {
+  return Boolean(this.options.globalSetup.length);
+};
+
+/**
+ * Returns `true` if one or more global teardown fixtures have been supplied.
+ * @public
+ * @returns {boolean}
+ */
+Mocha.prototype.hasGlobalTeardownFixtures = function hasGlobalTeardownFixtures() {
+  return Boolean(this.options.globalTeardown.length);
+};
+
+/**
+ * An alternative way to define root hooks that works with parallel runs.
  * @typedef {Object} MochaRootHookObject
  * @property {Function|Function[]} [beforeAll] - "Before all" hook(s)
  * @property {Function|Function[]} [beforeEach] - "Before each" hook(s)
@@ -1111,7 +1275,40 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
 
 /**
  * An function that returns a {@link MochaRootHookObject}, either sync or async.
- * @private
- * @callback MochaRootHookFunction
+   @callback MochaRootHookFunction
  * @returns {MochaRootHookObject|Promise<MochaRootHookObject>}
  */
+
+/**
+ * A function that's invoked _once_ which is either sync or async.
+ * Can be a "teardown" or "setup".  These will all share the same context.
+ * @callback MochaGlobalFixture
+ * @returns {void|Promise<void>}
+ */
+
+/**
+ * An object making up all necessary parts of a plugin loader and aggregator
+ * @typedef {Object} PluginDefinition
+ * @property {string} exportName - Named export to use
+ * @property {string} [optionName] - Option name for Mocha constructor (use `exportName` if omitted)
+ * @property {PluginValidator} [validate] - Validator function
+ * @property {PluginFinalizer} [finalize] - Finalizer/aggregator function
+ */
+
+/**
+ * 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}
+ * @returns {void}
+ */
+
+/**
+ * A function to finalize plugins impls of a particular ilk
+ * @callback PluginFinalizer
+ * @param {Array<*>} impls - User-supplied implementations
+ * @returns {Promise<*>|*}
+ */

package/lib/nodejs/buffered-worker-pool.js

@@ -75,9 +75,7 @@ class BufferedWorkerPool {
       process.execArgv.join(' ')
     );
 
-    this.options = Object.assign({}, WORKER_POOL_DEFAULT_OPTS, opts, {
-      maxWorkers
-    });
+    this.options = {...WORKER_POOL_DEFAULT_OPTS, opts, maxWorkers};
     this._pool = workerpool.pool(WORKER_PATH, this.options);
   }