mocha 7.1.1 → 8.0.1

package/lib/cli/watch-run.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const debug = require('debug')('mocha:cli:watch');
 const path = require('path');
 const chokidar = require('chokidar');
 const Context = require('../context');
@@ -12,6 +13,64 @@ const collectFiles = require('./collect-files');
  * @private
  */
 
+/**
+ * Run Mocha in parallel "watch" mode
+ * @param {Mocha} mocha - Mocha instance
+ * @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
+ *   `chokidar.watch`.
+ * @param {string[]} opts.watchIgnore - List of paths and patterns to
+ *   exclude from watching. See `ignored` option of `chokidar`.
+ * @param {FileCollectionOptions} fileCollectParams - Parameters that control test
+ * @private
+ */
+exports.watchParallelRun = (
+  mocha,
+  {watchFiles, watchIgnore},
+  fileCollectParams
+) => {
+  debug('creating parallel watcher');
+  return createWatcher(mocha, {
+    watchFiles,
+    watchIgnore,
+    beforeRun({mocha}) {
+      // I don't know why we're cloning the root suite.
+      const rootSuite = mocha.suite.clone();
+
+      // this `require` is needed because the require cache has been cleared.  the dynamic
+      // exports set via the below call to `mocha.ui()` won't work properly if a
+      // test depends on this module (see `required-tokens.spec.js`).
+      const Mocha = require('../mocha');
+
+      // ... and now that we've gotten a new module, we need to use it again due
+      // to `mocha.ui()` call
+      const newMocha = new Mocha(mocha.options);
+      // don't know why this is needed
+      newMocha.suite = rootSuite;
+      // nor this
+      newMocha.suite.ctx = new Context();
+
+      // reset the list of files
+      newMocha.files = collectFiles(fileCollectParams);
+
+      // because we've swapped out the root suite (see the `run` inner function
+      // in `createRerunner`), we need to call `mocha.ui()` again to set up the context/globals.
+      newMocha.ui(newMocha.options.ui);
+
+      // in parallel mode, the main Mocha process doesn't actually load the
+      // files. this flag prevents `mocha.run()` from autoloading.
+      newMocha.lazyLoadFiles(true);
+      return newMocha;
+    },
+    afterRun({watcher}) {
+      blastCache(watcher);
+    },
+    fileCollectParams
+  });
+};
+
 /**
  * Run Mocha in "watch" mode
  * @param {Mocha} mocha - Mocha instance
@@ -22,27 +81,88 @@ const collectFiles = require('./collect-files');
  *   `chokidar.watch`.
  * @param {string[]} opts.watchIgnore - List of paths and patterns to
  *   exclude from watching. See `ignored` option of `chokidar`.
- * @param {Object} fileCollectParams - Parameters that control test
+ * @param {FileCollectionOptions} fileCollectParams - Parameters that control test
  *   file collection. See `lib/cli/collect-files.js`.
- * @param {string[]} fileCollectParams.extension - List of extensions
- *   to watch if `opts.watchFiles` is not given.
  * @private
  */
-module.exports = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
+exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
+  debug('creating serial watcher');
+  // list of all test files
+
+  return createWatcher(mocha, {
+    watchFiles,
+    watchIgnore,
+    beforeRun({mocha}) {
+      mocha.unloadFiles();
+
+      // I don't know why we're cloning the root suite.
+      const rootSuite = mocha.suite.clone();
+
+      // this `require` is needed because the require cache has been cleared.  the dynamic
+      // exports set via the below call to `mocha.ui()` won't work properly if a
+      // test depends on this module (see `required-tokens.spec.js`).
+      const Mocha = require('../mocha');
+
+      // ... and now that we've gotten a new module, we need to use it again due
+      // to `mocha.ui()` call
+      const newMocha = new Mocha(mocha.options);
+      // don't know why this is needed
+      newMocha.suite = rootSuite;
+      // nor this
+      newMocha.suite.ctx = new Context();
+
+      // reset the list of files
+      newMocha.files = collectFiles(fileCollectParams);
+
+      // because we've swapped out the root suite (see the `run` inner function
+      // in `createRerunner`), we need to call `mocha.ui()` again to set up the context/globals.
+      newMocha.ui(newMocha.options.ui);
+
+      return newMocha;
+    },
+    afterRun({watcher}) {
+      blastCache(watcher);
+    },
+    fileCollectParams
+  });
+};
+
+/**
+ * Bootstraps a chokidar watcher. Handles keyboard input & signals
+ * @param {Mocha} mocha - Mocha instance
+ * @param {Object} opts
+ * @param {BeforeWatchRun} [opts.beforeRun] - Function to call before
+ * `mocha.run()`
+ * @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
+ *   `chokidar.watch`.
+ * @param {string[]} [opts.watchIgnore] - List of paths and patterns to exclude
+ *   from watching. See `ignored` option of `chokidar`.
+ * @param {FileCollectionOptions} opts.fileCollectParams - List of extensions to watch if `opts.watchFiles` is not given.
+ * @returns {FSWatcher}
+ * @ignore
+ * @private
+ */
+const createWatcher = (
+  mocha,
+  {watchFiles, watchIgnore, beforeRun, afterRun, fileCollectParams}
+) => {
   if (!watchFiles) {
     watchFiles = fileCollectParams.extension.map(ext => `**/*.${ext}`);
   }
 
+  debug('ignoring files matching: %s', watchIgnore);
+
   const watcher = chokidar.watch(watchFiles, {
     ignored: watchIgnore,
     ignoreInitial: true
   });
 
-  const rerunner = createRerunner(mocha, () => {
-    getWatchedFiles(watcher).forEach(file => {
-      delete require.cache[file];
-    });
-    mocha.files = collectFiles(fileCollectParams);
+  const rerunner = createRerunner(mocha, watcher, {
+    beforeRun,
+    afterRun
   });
 
   watcher.on('ready', () => {
@@ -53,7 +173,6 @@ module.exports = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
     rerunner.scheduleRun();
   });
 
-  console.log();
   hideCursor();
   process.on('exit', () => {
     showCursor();
@@ -74,36 +193,43 @@ module.exports = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
       .toLowerCase();
     if (str === 'rs') rerunner.scheduleRun();
   });
+
+  return watcher;
 };
 
 /**
- * Create an object that allows you to rerun tests on the mocha
- * instance. `beforeRun` is called everytime before `mocha.run()` is
- * called.
+ * Create an object that allows you to rerun tests on the mocha instance.
  *
  * @param {Mocha} mocha - Mocha instance
- * @param {function} beforeRun - Called just before `mocha.run()`
+ * @param {FSWatcher} watcher - chokidar `FSWatcher` instance
+ * @param {Object} [opts] - Options!
+ * @param {BeforeWatchRun} [opts.beforeRun] - Function to call before `mocha.run()`
+ * @param {AfterWatchRun} [opts.afterRun] - Function to call after `mocha.run()`
+ * @returns {Rerunner}
+ * @ignore
+ * @private
  */
-const createRerunner = (mocha, beforeRun) => {
+const createRerunner = (mocha, watcher, {beforeRun, afterRun} = {}) => {
   // Set to a `Runner` when mocha is running. Set to `null` when mocha is not
   // running.
   let runner = null;
 
+  // true if a file has changed during a test run
   let rerunScheduled = false;
 
   const run = () => {
-    try {
-      beforeRun();
-      resetMocha(mocha);
-      runner = mocha.run(() => {
-        runner = null;
-        if (rerunScheduled) {
-          rerun();
-        }
-      });
-    } catch (e) {
-      console.log(e.stack);
-    }
+    mocha = beforeRun ? beforeRun({mocha, watcher}) : mocha;
+
+    runner = mocha.run(() => {
+      debug('finished watch run');
+      runner = null;
+      afterRun && afterRun({mocha, watcher});
+      if (rerunScheduled) {
+        rerun();
+      } else {
+        debug('waiting for changes...');
+      }
+    });
   };
 
   const scheduleRun = () => {
@@ -136,32 +262,18 @@ const createRerunner = (mocha, beforeRun) => {
  *
  * @param watcher - Instance of a chokidar watcher
  * @return {string[]} - List of absolute paths
+ * @ignore
+ * @private
  */
 const getWatchedFiles = watcher => {
   const watchedDirs = watcher.getWatched();
-  let watchedFiles = [];
-  Object.keys(watchedDirs).forEach(dir => {
-    watchedFiles = watchedFiles.concat(
-      watchedDirs[dir].map(file => path.join(dir, file))
-    );
-  });
-  return watchedFiles;
-};
-
-/**
- * Reset the internal state of the mocha instance so that tests can be rerun.
- *
- * @param {Mocha} mocha - Mocha instance
- * @private
- */
-const resetMocha = mocha => {
-  mocha.unloadFiles();
-  mocha.suite = mocha.suite.clone();
-  mocha.suite.ctx = new Context();
-  // Registers a callback on `mocha.suite` that wires new context to the DSL
-  // (e.g. `describe`) that is exposed as globals when the test files are
-  // reloaded.
-  mocha.ui(mocha.options.ui);
+  return Object.keys(watchedDirs).reduce(
+    (acc, dir) => [
+      ...acc,
+      ...watchedDirs[dir].map(file => path.join(dir, file))
+    ],
+    []
+  );
 };
 
 /**
@@ -189,3 +301,43 @@ const showCursor = () => {
 const eraseLine = () => {
   process.stdout.write('\u001b[2K');
 };
+
+/**
+ * Blast all of the watched files out of `require.cache`
+ * @param {FSWatcher} watcher - chokidar FSWatcher
+ * @ignore
+ * @private
+ */
+const blastCache = watcher => {
+  const files = getWatchedFiles(watcher);
+  files.forEach(file => {
+    delete require.cache[file];
+  });
+  debug('deleted %d file(s) from the require cache', files.length);
+};
+
+/**
+ * Callback to be run before `mocha.run()` is called.
+ * Optionally, it can return a new `Mocha` instance.
+ * @callback BeforeWatchRun
+ * @private
+ * @param {{mocha: Mocha, watcher: FSWatcher}} options
+ * @returns {Mocha}
+ */
+
+/**
+ * Callback to be run after `mocha.run()` completes.  Typically used to clear
+ * require cache.
+ * @callback AfterWatchRun
+ * @private
+ * @param {{mocha: Mocha, watcher: FSWatcher}} options
+ * @returns {void}
+ */
+
+/**
+ * Object containing run control methods
+ * @typedef {Object} Rerunner
+ * @private
+ * @property {Function} run - Calls `mocha.run()`
+ * @property {Function} scheduleRun - Schedules another call to `run`
+ */

package/lib/context.js

@@ -45,21 +45,6 @@ Context.prototype.timeout = function(ms) {
   return this;
 };
 
-/**
- * Set test timeout `enabled`.
- *
- * @private
- * @param {boolean} enabled
- * @return {Context} self
- */
-Context.prototype.enableTimeouts = function(enabled) {
-  if (!arguments.length) {
-    return this.runnable().enableTimeouts();
-  }
-  this.runnable().enableTimeouts(enabled);
-  return this;
-};
-
 /**
  * Set or get test slowness threshold `ms`.
  *

package/lib/errors.js

@@ -1,10 +1,78 @@
 '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',
+
+  /**
+   * Use of `only()` w/ `--forbid-only` results in this error.
+   */
+  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY'
+};
 
 /**
  * Creates an error object to be thrown when no files to be tested could be found using specified pattern.
@@ -16,7 +84,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 +99,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 +114,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 +128,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 +156,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 +175,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 +191,130 @@ 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;
+}
+
+/**
+ * Creates an error object to be thrown when `.only()` is used with
+ * `--forbid-only`.
+ * @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;
+}
+
 module.exports = {
   createInvalidArgumentTypeError: createInvalidArgumentTypeError,
   createInvalidArgumentValueError: createInvalidArgumentValueError,
@@ -137,5 +323,12 @@ module.exports = {
   createInvalidReporterError: createInvalidReporterError,
   createMissingArgumentError: createMissingArgumentError,
   createNoFilesMatchPatternError: createNoFilesMatchPatternError,
-  createUnsupportedError: createUnsupportedError
+  createUnsupportedError: createUnsupportedError,
+  createInvalidPluginError: createInvalidPluginError,
+  createMochaInstanceAlreadyDisposedError: createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError: createMochaInstanceAlreadyRunningError,
+  createFatalError: createFatalError,
+  createMultipleDoneError: createMultipleDoneError,
+  createForbiddenExclusivityError: createForbiddenExclusivityError,
+  constants: constants
 };

package/lib/esm-utils.js

@@ -1,11 +1,16 @@
-const url = require('url');
 const path = require('path');
+const url = require('url');
 
-const requireOrImport = async file => {
-  file = path.resolve(file);
+const formattedImport = async file => {
+  if (path.isAbsolute(file)) {
+    return import(url.pathToFileURL(file));
+  }
+  return import(file);
+};
 
+exports.requireOrImport = async file => {
   if (path.extname(file) === '.mjs') {
-    return import(url.pathToFileURL(file));
+    return formattedImport(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.
@@ -15,7 +20,7 @@ const requireOrImport = async file => {
     return require(file);
   } catch (err) {
     if (err.code === 'ERR_REQUIRE_ESM') {
-      return import(url.pathToFileURL(file));
+      return formattedImport(file);
     } else {
       throw err;
     }
@@ -25,7 +30,7 @@ const requireOrImport = async file => {
 exports.loadFilesAsync = async (files, preLoadFunc, postLoadFunc) => {
   for (const file of files) {
     preLoadFunc(file);
-    const result = await requireOrImport(file);
+    const result = await exports.requireOrImport(path.resolve(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`.
  *
@@ -44,3 +52,27 @@ Hook.prototype.error = function(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 {
+    $$isPending: this.isPending(),
+    $$titlePath: this.titlePath(),
+    ctx: {
+      currentTest: {
+        title: this.ctx && this.ctx.currentTest && this.ctx.currentTest.title
+      }
+    },
+    parent: {
+      root: this.parent.root,
+      title: this.parent.title
+    },
+    title: this.title,
+    type: this.type
+  };
+};