mocha 7.1.2 → 8.1.0

package/lib/mocha.js

@@ -9,40 +9,72 @@
 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;
+var createMochaInstanceAlreadyDisposedError =
+  errors.createMochaInstanceAlreadyDisposedError;
+var createMochaInstanceAlreadyRunningError =
+  errors.createMochaInstanceAlreadyRunningError;
 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'
+});
+
 /**
  * To require local UIs and reporters when running in node.
  */
 
-if (!process.browser) {
-  var cwd = process.cwd();
+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');
 /**
@@ -90,6 +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 || {});
@@ -97,6 +134,8 @@ function Mocha(options) {
   this.options = 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)
@@ -136,6 +175,43 @@ function Mocha(options) {
       this[opt]();
     }
   }, this);
+
+  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);
+  }
 }
 
 /**
@@ -176,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
@@ -186,52 +262,52 @@ 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' ||
-          err.message.indexOf('Cannot find module') !== -1
+          err.code === 'MODULE_NOT_FOUND' ||
+          err.message.indexOf('Cannot find module') >= 0
         ) {
           // Try to load reporters from a path (absolute or relative)
           try {
-            _reporter = require(path.resolve(process.cwd(), reporter));
+            reporter = require(path.resolve(utils.cwd(), reporterName));
           } catch (_err) {
-            _err.code !== 'MODULE_NOT_FOUND' ||
-            _err.message.indexOf('Cannot find module') !== -1
-              ? console.warn(sQuote(reporter) + ' reporter not found')
-              : console.warn(
-                  sQuote(reporter) +
+            _err.code === 'MODULE_NOT_FOUND' ||
+            _err.message.indexOf('Cannot find module') >= 0
+              ? utils.warn(sQuote(reporterName) + ' reporter not found')
+              : utils.warn(
+                  sQuote(reporterName) +
                     ' reporter blew up with error:\n' +
                     err.stack
                 );
           }
         } else {
-          console.warn(
-            sQuote(reporter) + ' reporter blew up with error:\n' + err.stack
+          utils.warn(
+            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
@@ -340,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) {
@@ -388,7 +464,18 @@ Mocha.unloadFile = function(file) {
  * @chainable
  */
 Mocha.prototype.unloadFiles = function() {
-  this.files.forEach(Mocha.unloadFile);
+  if (this._state === mochaStates.DISPOSED) {
+    throw createMochaInstanceAlreadyDisposedError(
+      'Mocha instance is already disposed, it cannot be used again.',
+      this._cleanReferencesAfterRun,
+      this
+    );
+  }
+
+  this.files.forEach(function(file) {
+    Mocha.unloadFile(file);
+  });
+  this._state = mochaStates.INIT;
   return this;
 };
 
@@ -475,37 +562,51 @@ Mocha.prototype.invert = function() {
 };
 
 /**
- * Enables or disables ignoring global leaks.
+ * Enables or disables checking for global variables leaked while running tests.
  *
- * @deprecated since v7.0.0
  * @public
- * @see {@link Mocha#checkLeaks}
- * @param {boolean} [ignoreLeaks=false] - Whether to ignore global leaks.
+ * @see [CLI option](../#-check-leaks)
+ * @param {boolean} [checkLeaks=true] - Whether to check for global variable leaks.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.ignoreLeaks = function(ignoreLeaks) {
-  utils.deprecate(
-    '"ignoreLeaks()" is DEPRECATED, please use "checkLeaks()" instead.'
-  );
-  this.options.checkLeaks = !ignoreLeaks;
+Mocha.prototype.checkLeaks = function(checkLeaks) {
+  this.options.checkLeaks = checkLeaks !== false;
   return this;
 };
 
 /**
- * Enables or disables checking for global variables leaked while running tests.
- *
+ * Enables or disables whether or not to dispose after each test run.
+ * Disable this to ensure you can run the test suite multiple times.
+ * If disabled, be sure to dispose mocha when you're done to prevent memory leaks.
  * @public
- * @see [CLI option](../#-check-leaks)
- * @param {boolean} [checkLeaks=true] - Whether to check for global variable leaks.
+ * @see {@link Mocha#dispose}
+ * @param {boolean} cleanReferencesAfterRun
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.checkLeaks = function(checkLeaks) {
-  this.options.checkLeaks = checkLeaks !== false;
+Mocha.prototype.cleanReferencesAfterRun = function(cleanReferencesAfterRun) {
+  this._cleanReferencesAfterRun = cleanReferencesAfterRun !== false;
   return this;
 };
 
+/**
+ * Manually dispose this mocha instance. Mark this instance as `disposed` and unable to run more tests.
+ * It also removes function references to tests functions and hooks, so variables trapped in closures can be cleaned by the garbage collector.
+ * @public
+ */
+Mocha.prototype.dispose = function() {
+  if (this._state === mochaStates.RUNNING) {
+    throw createMochaInstanceAlreadyRunningError(
+      'Cannot dispose while the mocha instance is still running tests.'
+    );
+  }
+  this.unloadFiles();
+  this._previousRunner && this._previousRunner.dispose();
+  this.suite.dispose();
+  this._state = mochaStates.DISPOSED;
+};
+
 /**
  * Displays full stack trace upon test failure.
  *
@@ -531,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!');
@@ -589,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.
  *
@@ -621,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.
@@ -655,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.
  *
@@ -696,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
@@ -728,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;
 };
 
@@ -755,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.
  *
@@ -856,6 +887,29 @@ Mocha.prototype.forbidPending = function(forbidPending) {
   return this;
 };
 
+/**
+ * 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) {
+    throw createMochaInstanceAlreadyRunningError(
+      'Mocha instance is currently running tests, cannot start a next test run until this one is done',
+      this
+    );
+  }
+  if (
+    this._state === mochaStates.DISPOSED ||
+    this._state === mochaStates.REFERENCES_CLEANED
+  ) {
+    throw createMochaInstanceAlreadyDisposedError(
+      'Mocha instance is already disposed, cannot start a new test run. Please create a new mocha instance. Be sure to set disable `cleanReferencesAfterRun` when you want to reuse the same mocha instance for multiple test runs.',
+      this._cleanReferencesAfterRun,
+      this
+    );
+  }
+};
+
 /**
  * Mocha version as specified by "package.json".
  *
@@ -873,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.
  */
@@ -896,13 +951,23 @@ Object.defineProperty(Mocha.prototype, 'version', {
  * mocha.run(failures => process.exitCode = failures ? 1 : 0);
  */
 Mocha.prototype.run = function(fn) {
-  if (this.files.length && !this.loadAsync) {
+  this._guardRunningStateTransition();
+  this._state = mochaStates.RUNNING;
+  if (this._previousRunner) {
+    this._previousRunner.dispose();
+    this.suite.reset();
+  }
+  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, options.delay);
+  var runner = new this._runnerClass(suite, {
+    delay: options.delay,
+    cleanReferencesAfterRun: this._cleanReferencesAfterRun
+  });
   createStatsCollector(runner);
   var reporter = new this._reporter(runner, options);
   runner.checkLeaks = options.checkLeaks === true;
@@ -927,6 +992,12 @@ Mocha.prototype.run = function(fn) {
   exports.reporters.Base.hideDiff = !options.diff;
 
   function done(failures) {
+    self._previousRunner = runner;
+    if (self._cleanReferencesAfterRun) {
+      self._state = mochaStates.REFERENCES_CLEANED;
+    } else {
+      self._state = mochaStates.INIT;
+    }
     fn = fn || utils.noop;
     if (reporter.done) {
       reporter.done(failures, fn);
@@ -935,5 +1006,109 @@ Mocha.prototype.run = function(fn) {
     }
   }
 
-  return runner.run(done);
+  return runner.run(done, {files: this.files, options: options});
+};
+
+/**
+ * Assigns hooks to the root suite
+ * @param {MochaRootHookObject} [hooks] - Hooks to assign to root suite
+ * @chainable
+ */
+Mocha.prototype.rootHooks = function rootHooks(hooks) {
+  if (utils.type(hooks) === 'object') {
+    var beforeAll = [].concat(hooks.beforeAll || []);
+    var beforeEach = [].concat(hooks.beforeEach || []);
+    var afterAll = [].concat(hooks.afterAll || []);
+    var afterEach = [].concat(hooks.afterEach || []);
+    var rootSuite = this.suite;
+    beforeAll.forEach(function(hook) {
+      rootSuite.beforeAll(hook);
+    });
+    beforeEach.forEach(function(hook) {
+      rootSuite.beforeEach(hook);
+    });
+    afterAll.forEach(function(hook) {
+      rootSuite.afterAll(hook);
+    });
+    afterEach.forEach(function(hook) {
+      rootSuite.afterEach(hook);
+    });
+  }
+  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)
+ * @property {Function|Function[]} [afterAll] - "After all" hook(s)
+ * @property {Function|Function[]} [afterEach] - "After each" hook(s)
+ */
+
+/**
+ * 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,