mocha 7.1.2 → 8.1.0

package/lib/cli/run.js

@@ -7,6 +7,8 @@
  * @private
  */
 
+const symbols = require('log-symbols');
+const ansi = require('ansi-colors');
 const Mocha = require('../mocha');
 const {
   createUnsupportedError,
@@ -18,6 +20,7 @@ const {
   list,
   handleRequires,
   validatePlugin,
+  loadRootHooks,
   runMocha
 } = require('./run-helpers');
 const {ONE_AND_DONES, ONE_AND_DONE_ARGS} = require('./one-and-dones');
@@ -150,6 +153,13 @@ exports.builder = yargs =>
         description: 'Inverts --grep and --fgrep matches',
         group: GROUPS.FILTERS
       },
+      jobs: {
+        description:
+          'Number of concurrent jobs for --parallel; use 1 to run in serial',
+        defaultDescription: '(number of CPU cores - 1)',
+        requiresArg: true,
+        group: GROUPS.RULES
+      },
       'list-interfaces': {
         conflicts: Array.from(ONE_AND_DONE_ARGS),
         description: 'List built-in user interfaces & exit'
@@ -163,19 +173,16 @@ exports.builder = yargs =>
         group: GROUPS.OUTPUT,
         hidden: true
       },
-      opts: {
-        default: defaults.opts,
-        description: 'Path to `mocha.opts` (DEPRECATED)',
-        group: GROUPS.CONFIG,
-        normalize: true,
-        requiresArg: true
-      },
       package: {
         description: 'Path to package.json for config',
         group: GROUPS.CONFIG,
         normalize: true,
         requiresArg: true
       },
+      parallel: {
+        description: 'Run tests in parallel',
+        group: GROUPS.RULES
+      },
       recursive: {
         description: 'Look for tests in subdirectories',
         group: GROUPS.FILES
@@ -278,6 +285,40 @@ exports.builder = yargs =>
         );
       }
 
+      if (argv.parallel) {
+        // yargs.conflicts() can't deal with `--file foo.js --no-parallel`, either
+        if (argv.file) {
+          throw createUnsupportedError(
+            '--parallel runs test files in a non-deterministic order, and is mutually exclusive with --file'
+          );
+        }
+
+        // or this
+        if (argv.sort) {
+          throw createUnsupportedError(
+            '--parallel runs test files in a non-deterministic order, and is mutually exclusive with --sort'
+          );
+        }
+
+        if (argv.reporter === 'progress') {
+          throw createUnsupportedError(
+            '--reporter=progress is mutually exclusive with --parallel'
+          );
+        }
+
+        if (argv.reporter === 'markdown') {
+          throw createUnsupportedError(
+            '--reporter=markdown is mutually exclusive with --parallel'
+          );
+        }
+
+        if (argv.reporter === 'json-stream') {
+          throw createUnsupportedError(
+            '--reporter=json-stream is mutually exclusive with --parallel'
+          );
+        }
+      }
+
       if (argv.compilers) {
         throw createUnsupportedError(
           `--compilers is DEPRECATED and no longer supported.
@@ -285,13 +326,32 @@ exports.builder = yargs =>
         );
       }
 
-      // load requires first, because it can impact "plugin" validation
-      handleRequires(argv.require);
-      validatePlugin(argv, 'reporter', Mocha.reporters);
-      validatePlugin(argv, 'ui', Mocha.interfaces);
+      if (argv.opts) {
+        throw createUnsupportedError(
+          `--opts: configuring Mocha via 'mocha.opts' is DEPRECATED and no longer supported.
+          Please use a configuration file instead.`
+        );
+      }
 
       return true;
     })
+    .middleware(async (argv, yargs) => {
+      // currently a failing middleware does not work nicely with yargs' `fail()`.
+      try {
+        // load requires first, because it can impact "plugin" validation
+        const rawRootHooks = await handleRequires(argv.require);
+        validatePlugin(argv, 'reporter', Mocha.reporters);
+        validatePlugin(argv, 'ui', Mocha.interfaces);
+
+        if (rawRootHooks && rawRootHooks.length) {
+          argv.rootHooks = await loadRootHooks(rawRootHooks);
+        }
+      } catch (err) {
+        // this could be a bad --require, bad reporter, ui, etc.
+        console.error(`\n${symbols.error} ${ansi.red('ERROR:')}`, err);
+        yargs.exit(1);
+      }
+    })
     .array(types.array)
     .boolean(types.boolean)
     .string(types.string)

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`.
  *