mocha 8.0.1 → 8.1.3

package/lib/cli/watch-run.js

@@ -19,7 +19,7 @@ const collectFiles = require('./collect-files');
  * @param {Object} opts - Options
  * @param {string[]} [opts.watchFiles] - List of paths and patterns to
  *   watch. If not provided all files with an extension included in
- *   `fileColletionParams.extension` are watched. See first argument of
+ *   `fileCollectionParams.extension` are watched. See first argument of
  *   `chokidar.watch`.
  * @param {string[]} opts.watchIgnore - List of paths and patterns to
  *   exclude from watching. See `ignored` option of `chokidar`.
@@ -59,6 +59,10 @@ exports.watchParallelRun = (
       // in `createRerunner`), we need to call `mocha.ui()` again to set up the context/globals.
       newMocha.ui(newMocha.options.ui);
 
+      // we need to call `newMocha.rootHooks` to set up rootHooks for the new
+      // suite
+      newMocha.rootHooks(newMocha.options.rootHooks);
+
       // in parallel mode, the main Mocha process doesn't actually load the
       // files. this flag prevents `mocha.run()` from autoloading.
       newMocha.lazyLoadFiles(true);
@@ -77,7 +81,7 @@ exports.watchParallelRun = (
  * @param {Object} opts - Options
  * @param {string[]} [opts.watchFiles] - List of paths and patterns to
  *   watch. If not provided all files with an extension included in
- *   `fileColletionParams.extension` are watched. See first argument of
+ *   `fileCollectionParams.extension` are watched. See first argument of
  *   `chokidar.watch`.
  * @param {string[]} opts.watchIgnore - List of paths and patterns to
  *   exclude from watching. See `ignored` option of `chokidar`.
@@ -118,6 +122,10 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
       // in `createRerunner`), we need to call `mocha.ui()` again to set up the context/globals.
       newMocha.ui(newMocha.options.ui);
 
+      // we need to call `newMocha.rootHooks` to set up rootHooks for the new
+      // suite
+      newMocha.rootHooks(newMocha.options.rootHooks);
+
       return newMocha;
     },
     afterRun({watcher}) {
@@ -136,7 +144,7 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
  * @param {AfterWatchRun} [opts.afterRun] - Function to call after `mocha.run()`
  * @param {string[]} [opts.watchFiles] - List of paths and patterns to watch. If
  *   not provided all files with an extension included in
- *   `fileColletionParams.extension` are watched. See first argument of
+ *   `fileCollectionParams.extension` are watched. See first argument of
  *   `chokidar.watch`.
  * @param {string[]} [opts.watchIgnore] - List of paths and patterns to exclude
  *   from watching. See `ignored` option of `chokidar`.

package/lib/errors.js

@@ -59,12 +59,12 @@ var constants = {
   UNSUPPORTED: 'ERR_MOCHA_UNSUPPORTED',
 
   /**
-   * Invalid state transition occuring in `Mocha` instance
+   * Invalid state transition occurring in `Mocha` instance
    */
   INSTANCE_ALREADY_RUNNING: 'ERR_MOCHA_INSTANCE_ALREADY_RUNNING',
 
   /**
-   * Invalid state transition occuring in `Mocha` instance
+   * Invalid state transition occurring in `Mocha` instance
    */
   INSTANCE_ALREADY_DISPOSED: 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED',
 

package/lib/interfaces/common.js

@@ -1,5 +1,9 @@
 'use strict';
 
+/**
+ @module interfaces/common
+*/
+
 var Suite = require('../suite');
 var errors = require('../errors');
 var createMissingArgumentError = errors.createMissingArgumentError;
@@ -9,6 +13,7 @@ var createForbiddenExclusivityError = errors.createForbiddenExclusivityError;
 /**
  * Functions common to more than one interface.
  *
+ * @private
  * @param {Suite[]} suites
  * @param {Context} context
  * @param {Mocha} mocha

package/lib/mocha.js

@@ -12,18 +12,18 @@ 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;
+const {
+  createUnsupportedError,
+  createInvalidInterfaceError,
+  createInvalidReporterError,
+  createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError
+} = 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;
@@ -35,23 +35,28 @@ exports = module.exports = Mocha;
 /**
  * A Mocha instance is a finite state machine.
  * These are the states it can be in.
+ * @private
  */
 var mochaStates = utils.defineConstants({
   /**
    * Initial state of the mocha instance
+   * @private
    */
   INIT: 'init',
   /**
    * Mocha instance is running tests
+   * @private
    */
   RUNNING: 'running',
   /**
    * Mocha instance is done running tests and references to test functions and hooks are cleaned.
    * You can reset this state by unloading the test files.
+   * @private
    */
   REFERENCES_CLEANED: 'referencesCleaned',
   /**
    * Mocha instance is disposed and can no longer be used.
+   * @private
    */
   DISPOSED: 'disposed'
 });
@@ -67,6 +72,7 @@ if (!utils.isBrowser() && typeof module.paths !== 'undefined') {
 
 /**
  * Expose internals.
+ * @private
  */
 
 exports.utils = utils;
@@ -246,7 +252,7 @@ Mocha.prototype.addFile = function(file) {
  * @public
  * @see [CLI option](../#-reporter-name-r-name)
  * @see [Reporters](../#reporters)
- * @param {String|Function} reporter - Reporter name or constructor.
+ * @param {String|Function} reporterName - Reporter name or constructor.
  * @param {Object} [reporterOptions] - Options used to configure the reporter.
  * @returns {Mocha} this
  * @chainable
@@ -439,7 +445,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);
 };
 
 /**
@@ -769,8 +780,8 @@ Mocha.prototype.timeout = function(msecs) {
  * // Allow any failed test to retry one more time
  * mocha.retries(1);
  */
-Mocha.prototype.retries = function(n) {
-  this.suite.retries(n);
+Mocha.prototype.retries = function(retry) {
+  this.suite.retries(retry);
   return this;
 };
 
@@ -801,7 +812,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
  */
@@ -841,7 +852,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)
@@ -921,6 +932,7 @@ Object.defineProperty(Mocha.prototype, 'version', {
 /**
  * Callback to be invoked when test execution is complete.
  *
+ * @private
  * @callback DoneCB
  * @param {number} failures - Number of failures that occurred.
  */
@@ -1044,9 +1056,7 @@ Mocha.prototype.rootHooks = function rootHooks(hooks) {
  */
 Mocha.prototype.parallelMode = function parallelMode(enable) {
   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;
   if (
@@ -1057,7 +1067,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()'
     );
   }
@@ -1091,6 +1101,7 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
 
 /**
  * An alternative way to define root hooks that works with parallel runs.
+ * @private
  * @typedef {Object} MochaRootHookObject
  * @property {Function|Function[]} [beforeAll] - "Before all" hook(s)
  * @property {Function|Function[]} [beforeEach] - "Before each" hook(s)
@@ -1100,6 +1111,7 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
 
 /**
  * An function that returns a {@link MochaRootHookObject}, either sync or async.
+ * @private
  * @callback MochaRootHookFunction
  * @returns {MochaRootHookObject|Promise<MochaRootHookObject>}
  */

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)];
+};

package/lib/nodejs/parallel-buffered-runner.js

@@ -281,12 +281,14 @@ module.exports = ParallelBufferedRunner;
 
 /**
  * Listener function intended to be bound to `Process.SIGINT` event
+ * @private
  * @callback SigIntListener
  * @returns {Promise<void>}
  */
 
 /**
  * A function accepting a test file path and returning the results of a test run
+ * @private
  * @callback FileRunner
  * @param {string} filename - File to run
  * @returns {Promise<SerializedWorkerResult>}

package/lib/nodejs/serializer.js

@@ -56,7 +56,7 @@ class SerializableWorkerResult {
   /**
    * Instantiates a new {@link SerializableWorkerResult}.
    * @param {...any} args - Args to constructor
-   * @returns {SerilizableWorkerResult}
+   * @returns {SerializableWorkerResult}
    */
   static create(...args) {
     return new SerializableWorkerResult(...args);
@@ -387,6 +387,7 @@ exports.SerializableWorkerResult = SerializableWorkerResult;
 /**
  * The result of calling `SerializableEvent.serialize`, as received
  * by the deserializer.
+ * @private
  * @typedef {Object} SerializedEvent
  * @property {object?} data - Optional serialized data
  * @property {object?} error - Optional serialized `Error`
@@ -395,6 +396,7 @@ exports.SerializableWorkerResult = SerializableWorkerResult;
 /**
  * The result of calling `SerializableWorkerResult.serialize` as received
  * by the deserializer.
+ * @private
  * @typedef {Object} SerializedWorkerResult
  * @property {number} failureCount - Number of failures
  * @property {SerializedEvent[]} events - Serialized events

package/lib/pending.js

@@ -1,5 +1,9 @@
 'use strict';
 
+/**
+ @module Pending
+*/
+
 module.exports = Pending;
 
 /**

package/lib/reporters/base.js

@@ -6,15 +6,24 @@
  * Module dependencies.
  */
 
-var tty = require('tty');
 var diff = require('diff');
 var milliseconds = require('ms');
 var utils = require('../utils');
-var supportsColor = utils.isBrowser() ? null : require('supports-color');
+var supportsColor = require('supports-color');
 var constants = require('../runner').constants;
 var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
 var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
 
+const isBrowser = utils.isBrowser();
+
+function getBrowserWindowSize() {
+  if ('innerHeight' in global) {
+    return [global.innerHeight, global.innerWidth];
+  }
+  // In a Web Worker, the DOM Window is not available.
+  return [640, 480];
+}
+
 /**
  * Expose `Base`.
  */
@@ -25,7 +34,7 @@ exports = module.exports = Base;
  * Check if both stdio streams are associated with a tty.
  */
 
-var isatty = process.stdout.isTTY && process.stderr.isTTY;
+var isatty = isBrowser || (process.stdout.isTTY && process.stderr.isTTY);
 
 /**
  * Save log references to avoid tests interfering (see GH-3604).
@@ -37,7 +46,7 @@ var consoleLog = console.log;
  */
 
 exports.useColors =
-  !utils.isBrowser() &&
+  !isBrowser &&
   (supportsColor.stdout || process.env.MOCHA_COLORS !== undefined);
 
 /**
@@ -69,7 +78,9 @@ exports.colors = {
   light: 90,
   'diff gutter': 90,
   'diff added': 32,
-  'diff removed': 31
+  'diff removed': 31,
+  'diff added inline': '30;42',
+  'diff removed inline': '30;41'
 };
 
 /**
@@ -118,9 +129,11 @@ exports.window = {
 };
 
 if (isatty) {
-  exports.window.width = process.stdout.getWindowSize
-    ? process.stdout.getWindowSize(1)[0]
-    : tty.getWindowSize()[1];
+  if (isBrowser) {
+    exports.window.width = getBrowserWindowSize()[1];
+  } else {
+    exports.window.width = process.stdout.getWindowSize(1)[0];
+  }
 }
 
 /**
@@ -406,9 +419,9 @@ function inlineDiff(actual, expected) {
   // legend
   msg =
     '\n' +
-    color('diff removed', 'actual') +
+    color('diff removed inline', 'actual') +
     ' ' +
-    color('diff added', 'expected') +
+    color('diff added inline', 'expected') +
     '\n\n' +
     msg +
     '\n';
@@ -474,10 +487,10 @@ function errorDiff(actual, expected) {
     .diffWordsWithSpace(actual, expected)
     .map(function(str) {
       if (str.added) {
-        return colorLines('diff added', str.value);
+        return colorLines('diff added inline', str.value);
       }
       if (str.removed) {
-        return colorLines('diff removed', str.value);
+        return colorLines('diff removed inline', str.value);
       }
       return str.value;
     })

package/lib/runnable.js

@@ -11,6 +11,7 @@ var createMultipleDoneError = errors.createMultipleDoneError;
 
 /**
  * Save timer references to avoid Sinon interfering (see GH-237).
+ * @private
  */
 var Date = global.Date;
 var setTimeout = global.setTimeout;

package/lib/runner.js

@@ -2,6 +2,7 @@
 
 /**
  * Module dependencies.
+ * @private
  */
 var util = require('util');
 var EventEmitter = require('events').EventEmitter;
@@ -31,6 +32,7 @@ var createFatalError = errors.createFatalError;
 
 /**
  * Non-enumerable globals.
+ * @private
  * @readonly
  */
 var globals = [
@@ -204,7 +206,7 @@ Runner.prototype._addEventListener = function(target, eventName, listener) {
 /**
  * Replacement for `target.removeListener(eventName, listener)` that also updates the bookkeeping.
  * @param {EventEmitter} target - The `EventEmitter`
- * @param {string} eventName - The event anme
+ * @param {string} eventName - The event name
  * @param {function} listener - Listener function
  * @private
  */
@@ -358,6 +360,19 @@ Runner.prototype.checkGlobals = function(test) {
 /**
  * Fail the given `test`.
  *
+ * If `test` is a hook, failures work in the following pattern:
+ * - If bail, run corresponding `after each` and `after` hooks,
+ *   then exit
+ * - Failed `before` hook skips all tests in a suite and subsuites,
+ *   but jumps to corresponding `after` hook
+ * - Failed `before each` hook skips remaining tests in a
+ *   suite and jumps to corresponding `after each` hook,
+ *   which is run only once
+ * - Failed `after` hook does not alter execution order
+ * - Failed `after each` hook skips remaining tests in a
+ *   suite and subsuites, but executes other `after each`
+ *   hooks
+ *
  * @private
  * @param {Runnable} test
  * @param {Error} err
@@ -396,44 +411,6 @@ Runner.prototype.fail = function(test, err, force) {
   this.emit(constants.EVENT_TEST_FAIL, test, err);
 };
 
-/**
- * Fail the given `hook` with `err`.
- *
- * Hook failures work in the following pattern:
- * - If bail, run corresponding `after each` and `after` hooks,
- *   then exit
- * - Failed `before` hook skips all tests in a suite and subsuites,
- *   but jumps to corresponding `after` hook
- * - Failed `before each` hook skips remaining tests in a
- *   suite and jumps to corresponding `after each` hook,
- *   which is run only once
- * - Failed `after` hook does not alter execution order
- * - Failed `after each` hook skips remaining tests in a
- *   suite and subsuites, but executes other `after each`
- *   hooks
- *
- * @private
- * @param {Hook} hook
- * @param {Error} err
- */
-Runner.prototype.failHook = function(hook, err) {
-  hook.originalTitle = hook.originalTitle || hook.title;
-  if (hook.ctx && hook.ctx.currentTest) {
-    hook.title =
-      hook.originalTitle + ' for ' + dQuote(hook.ctx.currentTest.title);
-  } else {
-    var parentTitle;
-    if (hook.parent.title) {
-      parentTitle = hook.parent.title;
-    } else {
-      parentTitle = hook.parent.root ? '{root}' : '';
-    }
-    hook.title = hook.originalTitle + ' in ' + dQuote(parentTitle);
-  }
-
-  this.fail(hook, err);
-};
-
 /**
  * Run hook `name` callbacks and then invoke `fn()`.
  *
@@ -462,13 +439,15 @@ Runner.prototype.hook = function(name, fn) {
       hook.ctx.currentTest = self.test;
     }
 
+    setHookTitle(hook);
+
     hook.allowUncaught = self.allowUncaught;
 
     self.emit(constants.EVENT_HOOK_BEGIN, hook);
 
     if (!hook.listeners('error').length) {
       self._addEventListener(hook, 'error', function(err) {
-        self.failHook(hook, err);
+        self.fail(hook, err);
       });
     }
 
@@ -502,18 +481,35 @@ Runner.prototype.hook = function(name, fn) {
         } else {
           hook.pending = false;
           var errForbid = createUnsupportedError('`this.skip` forbidden');
-          self.failHook(hook, errForbid);
+          self.fail(hook, errForbid);
           return fn(errForbid);
         }
       } else if (err) {
-        self.failHook(hook, err);
+        self.fail(hook, err);
         // stop executing hooks, notify callee of hook err
         return fn(err);
       }
       self.emit(constants.EVENT_HOOK_END, hook);
       delete hook.ctx.currentTest;
+      setHookTitle(hook);
       next(++i);
     });
+
+    function setHookTitle(hook) {
+      hook.originalTitle = hook.originalTitle || hook.title;
+      if (hook.ctx && hook.ctx.currentTest) {
+        hook.title =
+          hook.originalTitle + ' for ' + dQuote(hook.ctx.currentTest.title);
+      } else {
+        var parentTitle;
+        if (hook.parent.title) {
+          parentTitle = hook.parent.title;
+        } else {
+          parentTitle = hook.parent.root ? '{root}' : '';
+        }
+        hook.title = hook.originalTitle + ' in ' + dQuote(parentTitle);
+      }
+    }
   }
 
   Runner.immediately(function() {

package/lib/suite.js

@@ -2,6 +2,7 @@
 
 /**
  * Module dependencies.
+ * @private
  */
 var EventEmitter = require('events').EventEmitter;
 var Hook = require('./hook');