mocha 7.2.0 → 8.1.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,37 +13,164 @@ 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
+ *   `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`.
+ * @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);
+
+      // 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);
+      return newMocha;
+    },
+    afterRun({watcher}) {
+      blastCache(watcher);
+    },
+    fileCollectParams
+  });
+};
+
 /**
  * Run Mocha in "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
+ *   `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`.
- * @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);
+
+      // we need to call `newMocha.rootHooks` to set up rootHooks for the new
+      // suite
+      newMocha.rootHooks(newMocha.options.rootHooks);
+
+      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
+ *   `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`.
+ * @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 +181,6 @@ module.exports = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
     rerunner.scheduleRun();
   });
 
-  console.log();
   hideCursor();
   process.on('exit', () => {
     showCursor();
@@ -74,36 +201,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 +270,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 +309,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

@@ -59,14 +59,19 @@ 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'
+  INSTANCE_ALREADY_DISPOSED: 'ERR_MOCHA_INSTANCE_ALREADY_DISPOSED',
+
+  /**
+   * Use of `only()` w/ `--forbid-only` results in this error.
+   */
+  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY'
 };
 
 /**
@@ -293,6 +298,23 @@ function createMultipleDoneError(runnable, 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,
@@ -307,5 +329,6 @@ module.exports = {
   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

@@ -52,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
+  };
+};

package/lib/interfaces/common.js

@@ -1,13 +1,19 @@
 'use strict';
 
+/**
+ @module interfaces/common
+*/
+
 var Suite = require('../suite');
 var errors = require('../errors');
 var createMissingArgumentError = errors.createMissingArgumentError;
 var createUnsupportedError = errors.createUnsupportedError;
+var createForbiddenExclusivityError = errors.createForbiddenExclusivityError;
 
 /**
  * Functions common to more than one interface.
  *
+ * @private
  * @param {Suite[]} suites
  * @param {Context} context
  * @param {Mocha} mocha
@@ -93,6 +99,9 @@ module.exports = function(suites, context, mocha) {
        * @returns {Suite}
        */
       only: function only(opts) {
+        if (mocha.options.forbidOnly) {
+          throw createForbiddenExclusivityError(mocha);
+        }
         opts.isOnly = true;
         return this.create(opts);
       },
@@ -126,16 +135,14 @@ module.exports = function(suites, context, mocha) {
         suite.file = opts.file;
         suites.unshift(suite);
         if (opts.isOnly) {
-          if (mocha.options.forbidOnly && shouldBeTested(suite)) {
-            throw createUnsupportedError('`.only` forbidden');
-          }
-
-          suite.parent.appendOnlySuite(suite);
+          suite.markOnly();
         }
-        if (suite.pending) {
-          if (mocha.options.forbidPending && shouldBeTested(suite)) {
-            throw createUnsupportedError('Pending test forbidden');
-          }
+        if (
+          suite.pending &&
+          mocha.options.forbidPending &&
+          shouldBeTested(suite)
+        ) {
+          throw createUnsupportedError('Pending test forbidden');
         }
         if (typeof opts.fn === 'function') {
           opts.fn.call(suite);
@@ -166,8 +173,9 @@ module.exports = function(suites, context, mocha) {
        * @returns {*}
        */
       only: function(mocha, test) {
-        if (mocha.options.forbidOnly)
-          throw createUnsupportedError('`.only` forbidden');
+        if (mocha.options.forbidOnly) {
+          throw createForbiddenExclusivityError(mocha);
+        }
         test.markOnly();
         return test;
       },