mocha 8.1.1 → 8.2.1

package/lib/mocha.js

@@ -12,21 +12,24 @@ var builtinReporters = require('./reporters');
 var growl = require('./nodejs/growl');
 var utils = require('./utils');
 var mocharc = require('./mocharc.json');
-var errors = require('./errors');
 var Suite = require('./suite');
 var esmUtils = utils.supportsEsModules(true)
   ? require('./esm-utils')
   : undefined;
 var createStatsCollector = require('./stats-collector');
-var createInvalidReporterError = errors.createInvalidReporterError;
-var createInvalidInterfaceError = errors.createInvalidInterfaceError;
-var createMochaInstanceAlreadyDisposedError =
-  errors.createMochaInstanceAlreadyDisposedError;
-var createMochaInstanceAlreadyRunningError =
-  errors.createMochaInstanceAlreadyRunningError;
-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 {
+  warn,
+  createInvalidReporterError,
+  createInvalidInterfaceError,
+  createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError,
+  createUnsupportedError
+} = require('./errors');
+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
           );
         }
@@ -445,7 +449,12 @@ Mocha.prototype.loadFilesAsync = function() {
  * @param {string} file - Pathname of file to be unloaded.
  */
 Mocha.unloadFile = function(file) {
-  delete require.cache[require.resolve(file)];
+  if (utils.isBrowser()) {
+    throw createUnsupportedError(
+      'unloadFile() is only suported in a Node.js environment'
+    );
+  }
+  return require('./nodejs/file-unloader').unloadFile(file);
 };
 
 /**
@@ -807,7 +816,7 @@ Mocha.prototype.slow = function(msecs) {
  *
  * @public
  * @see [CLI option](../#-async-only-a)
- * @param {boolean} [asyncOnly=true] - Wether to force `done` callback or promise.
+ * @param {boolean} [asyncOnly=true] - Whether to force `done` callback or promise.
  * @return {Mocha} this
  * @chainable
  */
@@ -847,7 +856,7 @@ Mocha.prototype.allowUncaught = function(allowUncaught) {
  * Delays root suite execution.
  *
  * @description
- * Used to perform asynch operations before any suites are run.
+ * Used to perform async operations before any suites are run.
  *
  * @public
  * @see [delayed root suite](../#delayed-root-suite)
@@ -960,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
   });
@@ -991,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;
+  };
+
+  // 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.run(done, {files: this.files, options: options});
+  return runner;
 };
 
 /**
@@ -1014,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;
 };
 
@@ -1042,20 +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 errors.createUnsupportedError(
-      'parallel mode is only supported in Node.js'
-    );
+    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 &&
@@ -1064,7 +1095,7 @@ Mocha.prototype.parallelMode = function parallelMode(enable) {
     return this;
   }
   if (this._state !== mochaStates.INIT) {
-    throw errors.createUnsupportedError(
+    throw createUnsupportedError(
       'cannot change parallel mode after having called run()'
     );
   }
@@ -1097,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)
@@ -1108,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);
   }
 

package/lib/nodejs/file-unloader.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * This module should not be in the browser bundle, so it's here.
+ * @private
+ * @module
+ */
+
+/**
+ * Deletes a file from the `require` cache.
+ * @param {string} file - File
+ */
+exports.unloadFile = file => {
+  delete require.cache[require.resolve(file)];
+};