mocha 7.2.0 → 8.1.1

package/lib/mocha.js

@@ -9,12 +9,14 @@
 var escapeRe = require('escape-string-regexp');
 var path = require('path');
 var builtinReporters = require('./reporters');
-var growl = require('./growl');
+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() ? require('./esm-utils') : undefined;
+var esmUtils = utils.supportsEsModules(true)
+  ? require('./esm-utils')
+  : undefined;
 var createStatsCollector = require('./stats-collector');
 var createInvalidReporterError = errors.createInvalidReporterError;
 var createInvalidInterfaceError = errors.createInvalidInterfaceError;
@@ -26,29 +28,35 @@ 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;
 var sQuote = utils.sQuote;
+var debug = require('debug')('mocha:mocha');
 
 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'
 });
@@ -57,20 +65,16 @@ var mochaStates = utils.defineConstants({
  * To require local UIs and reporters when running in node.
  */
 
-if (!process.browser && typeof module.paths !== 'undefined') {
+if (!utils.isBrowser() && typeof module.paths !== 'undefined') {
   var cwd = utils.cwd();
   module.paths.push(cwd, path.join(cwd, 'node_modules'));
 }
 
 /**
  * Expose internals.
+ * @private
  */
 
-/**
- * @public
- * @class utils
- * @memberof Mocha
- */
 exports.utils = utils;
 exports.interfaces = require('./interfaces');
 /**
@@ -118,8 +122,11 @@ exports.Test = require('./test');
  * @param {number} [options.slow] - Slow threshold value.
  * @param {number|string} [options.timeout] - Timeout threshold value.
  * @param {string} [options.ui] - Interface name.
+ * @param {boolean} [options.parallel] - Run jobs in parallel
+ * @param {number} [options.jobs] - Max number of worker processes for parallel runs
  * @param {MochaRootHookObject} [options.rootHooks] - Hooks to bootstrap the root
  * 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 || {});
@@ -128,6 +135,7 @@ function Mocha(options) {
   // root suite
   this.suite = new exports.Suite('', new exports.Context(), true);
   this._cleanReferencesAfterRun = true;
+  this._state = mochaStates.INIT;
 
   this.grep(options.grep)
     .fgrep(options.fgrep)
@@ -171,6 +179,39 @@ function Mocha(options) {
   if (options.rootHooks) {
     this.rootHooks(options.rootHooks);
   }
+
+  /**
+   * The class which we'll instantiate in {@link Mocha#run}.  Defaults to
+   * {@link Runner} in serial mode; changes in parallel mode.
+   * @memberof Mocha
+   * @private
+   */
+  this._runnerClass = exports.Runner;
+
+  /**
+   * Whether or not to call {@link Mocha#loadFiles} implicitly when calling
+   * {@link Mocha#run}.  If this is `true`, then it's up to the consumer to call
+   * {@link Mocha#loadFiles} _or_ {@link Mocha#loadFilesAsync}.
+   * @private
+   * @memberof Mocha
+   */
+  this._lazyLoadFiles = false;
+
+  /**
+   * It's useful for a Mocha instance to know if it's running in a worker process.
+   * We could derive this via other means, but it's helpful to have a flag to refer to.
+   * @memberof Mocha
+   * @private
+   */
+  this.isWorker = Boolean(options.isWorker);
+
+  if (
+    options.parallel &&
+    (typeof options.jobs === 'undefined' || options.jobs > 1)
+  ) {
+    debug('attempting to enable parallel mode');
+    this.parallelMode(true);
+  }
 }
 
 /**
@@ -211,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
@@ -221,20 +262,20 @@ Mocha.prototype.addFile = function(file) {
  * // Use XUnit reporter and direct its output to file
  * mocha.reporter('xunit', { output: '/path/to/testspec.xunit.xml' });
  */
-Mocha.prototype.reporter = function(reporter, reporterOptions) {
-  if (typeof reporter === 'function') {
-    this._reporter = reporter;
+Mocha.prototype.reporter = function(reporterName, reporterOptions) {
+  if (typeof reporterName === 'function') {
+    this._reporter = reporterName;
   } else {
-    reporter = reporter || 'spec';
-    var _reporter;
+    reporterName = reporterName || 'spec';
+    var reporter;
     // Try to load a built-in reporter.
-    if (builtinReporters[reporter]) {
-      _reporter = builtinReporters[reporter];
+    if (builtinReporters[reporterName]) {
+      reporter = builtinReporters[reporterName];
     }
     // Try to load reporters from process.cwd() and node_modules
-    if (!_reporter) {
+    if (!reporter) {
       try {
-        _reporter = require(reporter);
+        reporter = require(reporterName);
       } catch (err) {
         if (
           err.code === 'MODULE_NOT_FOUND' ||
@@ -242,31 +283,31 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
         ) {
           // Try to load reporters from a path (absolute or relative)
           try {
-            _reporter = require(path.resolve(utils.cwd(), reporter));
+            reporter = require(path.resolve(utils.cwd(), reporterName));
           } catch (_err) {
             _err.code === 'MODULE_NOT_FOUND' ||
             _err.message.indexOf('Cannot find module') >= 0
-              ? utils.warn(sQuote(reporter) + ' reporter not found')
+              ? utils.warn(sQuote(reporterName) + ' reporter not found')
               : utils.warn(
-                  sQuote(reporter) +
+                  sQuote(reporterName) +
                     ' reporter blew up with error:\n' +
                     err.stack
                 );
           }
         } else {
           utils.warn(
-            sQuote(reporter) + ' reporter blew up with error:\n' + err.stack
+            sQuote(reporterName) + ' reporter blew up with error:\n' + err.stack
           );
         }
       }
     }
-    if (!_reporter) {
+    if (!reporter) {
       throw createInvalidReporterError(
-        'invalid reporter ' + sQuote(reporter),
-        reporter
+        'invalid reporter ' + sQuote(reporterName),
+        reporterName
       );
     }
-    this._reporter = _reporter;
+    this._reporter = reporter;
   }
   this.options.reporterOption = reporterOptions;
   // alias option name is used in public reporters xunit/tap/progress
@@ -375,7 +416,7 @@ Mocha.prototype.loadFiles = function(fn) {
 Mocha.prototype.loadFilesAsync = function() {
   var self = this;
   var suite = this.suite;
-  this.loadAsync = true;
+  this.lazyLoadFiles(true);
 
   if (!esmUtils) {
     return new Promise(function(resolve) {
@@ -520,24 +561,6 @@ Mocha.prototype.invert = function() {
   return this;
 };
 
-/**
- * Enables or disables ignoring global leaks.
- *
- * @deprecated since v7.0.0
- * @public
- * @see {@link Mocha#checkLeaks}
- * @param {boolean} [ignoreLeaks=false] - Whether to ignore global leaks.
- * @return {Mocha} this
- * @chainable
- */
-Mocha.prototype.ignoreLeaks = function(ignoreLeaks) {
-  utils.deprecate(
-    '"ignoreLeaks()" is DEPRECATED, please use "checkLeaks()" instead.'
-  );
-  this.options.checkLeaks = !ignoreLeaks;
-  return this;
-};
-
 /**
  * Enables or disables checking for global variables leaked while running tests.
  *
@@ -609,7 +632,7 @@ Mocha.prototype.fullTrace = function(fullTrace) {
 Mocha.prototype.growl = function() {
   this.options.growl = this.isGrowlCapable();
   if (!this.options.growl) {
-    var detail = process.browser
+    var detail = utils.isBrowser()
       ? 'notification support not available in this browser...'
       : 'notification support prerequisites not installed...';
     console.error(detail + ' cannot enable!');
@@ -667,24 +690,6 @@ Mocha.prototype.global = function(global) {
 // for backwards compability, 'globals' is an alias of 'global'
 Mocha.prototype.globals = Mocha.prototype.global;
 
-/**
- * Enables or disables TTY color output by screen-oriented reporters.
- *
- * @deprecated since v7.0.0
- * @public
- * @see {@link Mocha#color}
- * @param {boolean} colors - Whether to enable color output.
- * @return {Mocha} this
- * @chainable
- */
-Mocha.prototype.useColors = function(colors) {
-  utils.deprecate('"useColors()" is DEPRECATED, please use "color()" instead.');
-  if (colors !== undefined) {
-    this.options.color = colors;
-  }
-  return this;
-};
-
 /**
  * Enables or disables TTY color output by screen-oriented reporters.
  *
@@ -699,25 +704,6 @@ Mocha.prototype.color = function(color) {
   return this;
 };
 
-/**
- * Determines if reporter should use inline diffs (rather than +/-)
- * in test failure output.
- *
- * @deprecated since v7.0.0
- * @public
- * @see {@link Mocha#inlineDiffs}
- * @param {boolean} [inlineDiffs=false] - Whether to use inline diffs.
- * @return {Mocha} this
- * @chainable
- */
-Mocha.prototype.useInlineDiffs = function(inlineDiffs) {
-  utils.deprecate(
-    '"useInlineDiffs()" is DEPRECATED, please use "inlineDiffs()" instead.'
-  );
-  this.options.inlineDiffs = inlineDiffs !== undefined && inlineDiffs;
-  return this;
-};
-
 /**
  * Enables or disables reporter to use inline diffs (rather than +/-)
  * in test failure output.
@@ -733,22 +719,6 @@ Mocha.prototype.inlineDiffs = function(inlineDiffs) {
   return this;
 };
 
-/**
- * Determines if reporter should include diffs in test failure output.
- *
- * @deprecated since v7.0.0
- * @public
- * @see {@link Mocha#diff}
- * @param {boolean} [hideDiff=false] - Whether to hide diffs.
- * @return {Mocha} this
- * @chainable
- */
-Mocha.prototype.hideDiff = function(hideDiff) {
-  utils.deprecate('"hideDiff()" is DEPRECATED, please use "diff()" instead.');
-  this.options.diff = !(hideDiff === true);
-  return this;
-};
-
 /**
  * Enables or disables reporter to include diff in test failure output.
  *
@@ -774,7 +744,6 @@ Mocha.prototype.diff = function(diff) {
  * @public
  * @see [CLI option](../#-timeout-ms-t-ms)
  * @see [Timeouts](../#timeouts)
- * @see {@link Mocha#enableTimeouts}
  * @param {number|string} msecs - Timeout threshold value.
  * @return {Mocha} this
  * @chainable
@@ -806,8 +775,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;
 };
 
@@ -833,22 +802,6 @@ Mocha.prototype.slow = function(msecs) {
   return this;
 };
 
-/**
- * Enables or disables timeouts.
- *
- * @public
- * @see [CLI option](../#-timeout-ms-t-ms)
- * @param {boolean} enableTimeouts - Whether to enable timeouts.
- * @return {Mocha} this
- * @chainable
- */
-Mocha.prototype.enableTimeouts = function(enableTimeouts) {
-  this.suite.enableTimeouts(
-    arguments.length && enableTimeouts !== undefined ? enableTimeouts : true
-  );
-  return this;
-};
-
 /**
  * Forces all tests to either accept a `done` callback or return a promise.
  *
@@ -936,6 +889,7 @@ Mocha.prototype.forbidPending = function(forbidPending) {
 
 /**
  * Throws an error if mocha is in the wrong state to be able to transition to a "running" state.
+ * @private
  */
 Mocha.prototype._guardRunningStateTransition = function() {
   if (this._state === mochaStates.RUNNING) {
@@ -973,6 +927,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.
  */
@@ -1002,14 +957,14 @@ Mocha.prototype.run = function(fn) {
     this._previousRunner.dispose();
     this.suite.reset();
   }
-  if (this.files.length && !this.loadAsync) {
+  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 exports.Runner(suite, {
+  var runner = new this._runnerClass(suite, {
     delay: options.delay,
     cleanReferencesAfterRun: this._cleanReferencesAfterRun
   });
@@ -1051,7 +1006,7 @@ Mocha.prototype.run = function(fn) {
     }
   }
 
-  return runner.run(done);
+  return runner.run(done, {files: this.files, options: options});
 };
 
 /**
@@ -1082,8 +1037,68 @@ Mocha.prototype.rootHooks = function rootHooks(hooks) {
   return this;
 };
 
+/**
+ * Toggles parallel mode.
+ *
+ * Must be run before calling {@link Mocha#run}. Changes the `Runner` class to
+ * use; also enables lazy file loading if not already done so.
+ * @param {boolean} [enable] - If `true`, enable; otherwise disable.
+ * @throws If run in browser
+ * @throws If Mocha not in "INIT" state
+ * @returns {Mocha}
+ * @chainable
+ * @public
+ */
+Mocha.prototype.parallelMode = function parallelMode(enable) {
+  if (utils.isBrowser()) {
+    throw errors.createUnsupportedError(
+      'parallel mode is only supported in Node.js'
+    );
+  }
+  var parallel = enable === true;
+  if (
+    parallel === this.options.parallel &&
+    this._lazyLoadFiles &&
+    this._runnerClass !== exports.Runner
+  ) {
+    return this;
+  }
+  if (this._state !== mochaStates.INIT) {
+    throw errors.createUnsupportedError(
+      'cannot change parallel mode after having called run()'
+    );
+  }
+  this.options.parallel = parallel;
+
+  // swap Runner class
+  this._runnerClass = parallel
+    ? require('./nodejs/parallel-buffered-runner')
+    : exports.Runner;
+
+  // lazyLoadFiles may have been set `true` otherwise (for ESM loading),
+  // so keep `true` if so.
+  return this.lazyLoadFiles(this._lazyLoadFiles || parallel);
+};
+
+/**
+ * Disables implicit call to {@link Mocha#loadFiles} in {@link Mocha#run}. This
+ * setting is used by watch mode, parallel mode, and for loading ESM files.
+ * @todo This should throw if we've already loaded files; such behavior
+ * necessitates adding a new state.
+ * @param {boolean} [enable] - If `true`, disable eager loading of files in
+ * {@link Mocha#run}
+ * @chainable
+ * @public
+ */
+Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
+  this._lazyLoadFiles = enable === true;
+  debug('set lazy load to %s', enable);
+  return this;
+};
+
 /**
  * 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)
@@ -1093,6 +1108,7 @@ Mocha.prototype.rootHooks = function rootHooks(hooks) {
 
 /**
  * An function that returns a {@link MochaRootHookObject}, either sync or async.
+ * @private
  * @callback MochaRootHookFunction
  * @returns {MochaRootHookObject|Promise<MochaRootHookObject>}
  */

package/lib/mocharc.json

@@ -1,7 +1,6 @@
 {
   "diff": true,
   "extension": ["js", "cjs", "mjs"],
-  "opts": "./test/mocha.opts",
   "package": "./package.json",
   "reporter": "spec",
   "slow": 75,

package/lib/nodejs/buffered-worker-pool.js

@@ -0,0 +1,174 @@
+/**
+ * A wrapper around a third-party child process worker pool implementation.
+ * Used by {@link module:buffered-runner}.
+ * @private
+ * @module buffered-worker-pool
+ */
+
+'use strict';
+
+const serializeJavascript = require('serialize-javascript');
+const workerpool = require('workerpool');
+const {deserialize} = require('./serializer');
+const debug = require('debug')('mocha:parallel:buffered-worker-pool');
+const {createInvalidArgumentTypeError} = require('../errors');
+
+const WORKER_PATH = require.resolve('./worker.js');
+
+/**
+ * A mapping of Mocha `Options` objects to serialized values.
+ *
+ * This is helpful because we tend to same the same options over and over
+ * over IPC.
+ * @type {WeakMap<Options,string>}
+ */
+let optionsCache = new WeakMap();
+
+/**
+ * These options are passed into the [workerpool](https://npm.im/workerpool) module.
+ * @type {Partial<WorkerPoolOptions>}
+ */
+const WORKER_POOL_DEFAULT_OPTS = {
+  // use child processes, not worker threads!
+  workerType: 'process',
+  // ensure the same flags sent to `node` for this `mocha` invocation are passed
+  // along to children
+  forkOpts: {execArgv: process.execArgv},
+  maxWorkers: workerpool.cpus - 1
+};
+
+/**
+ * A wrapper around a third-party worker pool implementation.
+ * @private
+ */
+class BufferedWorkerPool {
+  /**
+   * Creates an underlying worker pool instance; determines max worker count
+   * @param {Partial<WorkerPoolOptions>} [opts] - Options
+   */
+  constructor(opts = {}) {
+    const maxWorkers = Math.max(
+      1,
+      typeof opts.maxWorkers === 'undefined'
+        ? WORKER_POOL_DEFAULT_OPTS.maxWorkers
+        : opts.maxWorkers
+    );
+
+    /* istanbul ignore next */
+    if (workerpool.cpus < 2) {
+      // TODO: decide whether we should warn
+      debug(
+        'not enough CPU cores available to run multiple jobs; avoid --parallel on this machine'
+      );
+    } else if (maxWorkers >= workerpool.cpus) {
+      // TODO: decide whether we should warn
+      debug(
+        '%d concurrent job(s) requested, but only %d core(s) available',
+        maxWorkers,
+        workerpool.cpus
+      );
+    }
+    /* istanbul ignore next */
+    debug(
+      'run(): starting worker pool of max size %d, using node args: %s',
+      maxWorkers,
+      process.execArgv.join(' ')
+    );
+
+    this.options = Object.assign({}, WORKER_POOL_DEFAULT_OPTS, opts, {
+      maxWorkers
+    });
+    this._pool = workerpool.pool(WORKER_PATH, this.options);
+  }
+
+  /**
+   * Terminates all workers in the pool.
+   * @param {boolean} [force] - Whether to force-kill workers. By default, lets workers finish their current task before termination.
+   * @private
+   * @returns {Promise<void>}
+   */
+  async terminate(force = false) {
+    /* istanbul ignore next */
+    debug('terminate(): terminating with force = %s', force);
+    return this._pool.terminate(force);
+  }
+
+  /**
+   * Adds a test file run to the worker pool queue for execution by a worker process.
+   *
+   * Handles serialization/deserialization.
+   *
+   * @param {string} filepath - Filepath of test
+   * @param {Options} [options] - Options for Mocha instance
+   * @private
+   * @returns {Promise<SerializedWorkerResult>}
+   */
+  async run(filepath, options = {}) {
+    if (!filepath || typeof filepath !== 'string') {
+      throw createInvalidArgumentTypeError(
+        'Expected a non-empty filepath',
+        'filepath',
+        'string'
+      );
+    }
+    const serializedOptions = BufferedWorkerPool.serializeOptions(options);
+    const result = await this._pool.exec('run', [filepath, serializedOptions]);
+    return deserialize(result);
+  }
+
+  /**
+   * Returns stats about the state of the worker processes in the pool.
+   *
+   * Used for debugging.
+   *
+   * @private
+   */
+  stats() {
+    return this._pool.stats();
+  }
+
+  /**
+   * Instantiates a {@link WorkerPool}.
+   * @private
+   */
+  static create(...args) {
+    return new BufferedWorkerPool(...args);
+  }
+
+  /**
+   * Given Mocha options object `opts`, serialize into a format suitable for
+   * transmission over IPC.
+   *
+   * @param {Options} [opts] - Mocha options
+   * @private
+   * @returns {string} Serialized options
+   */
+  static serializeOptions(opts = {}) {
+    if (!optionsCache.has(opts)) {
+      const serialized = serializeJavascript(opts, {
+        unsafe: true, // this means we don't care about XSS
+        ignoreFunction: true // do not serialize functions
+      });
+      optionsCache.set(opts, serialized);
+      /* istanbul ignore next */
+      debug(
+        'serializeOptions(): serialized options %O to: %s',
+        opts,
+        serialized
+      );
+    }
+    return optionsCache.get(opts);
+  }
+
+  /**
+   * Resets internal cache of serialized options objects.
+   *
+   * For testing/debugging
+   * @private
+   */
+  static resetOptionsCache() {
+    optionsCache = new WeakMap();
+  }
+}
+
+exports.BufferedWorkerPool = BufferedWorkerPool;

package/lib/{growl.js → nodejs/growl.js}

@@ -8,7 +8,8 @@
 const os = require('os');
 const path = require('path');
 const {sync: which} = require('which');
-const {EVENT_RUN_END} = require('./runner').constants;
+const {EVENT_RUN_END} = require('../runner').constants;
+const {isBrowser} = require('../utils');
 
 /**
  * @summary
@@ -25,7 +26,7 @@ const {EVENT_RUN_END} = require('./runner').constants;
  * @return {boolean} whether Growl notification support can be expected
  */
 exports.isCapable = () => {
-  if (!process.browser) {
+  if (!isBrowser()) {
     return getSupportBinaries().reduce(
       (acc, binary) => acc || Boolean(which(binary, {nothrow: true})),
       false