mocha 7.0.1 → 7.2.0

package/lib/mocha.js

@@ -14,9 +14,14 @@ 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 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;
@@ -24,12 +29,36 @@ var sQuote = utils.sQuote;
 
 exports = module.exports = Mocha;
 
+/**
+ * A Mocha instance is a finite state machine.
+ * These are the states it can be in.
+ */
+var mochaStates = utils.defineConstants({
+  /**
+   * Initial state of the mocha instance
+   */
+  INIT: 'init',
+  /**
+   * Mocha instance is running tests
+   */
+  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.
+   */
+  REFERENCES_CLEANED: 'referencesCleaned',
+  /**
+   * Mocha instance is disposed and can no longer be used.
+   */
+  DISPOSED: 'disposed'
+});
+
 /**
  * To require local UIs and reporters when running in node.
  */
 
-if (!process.browser) {
-  var cwd = process.cwd();
+if (!process.browser && typeof module.paths !== 'undefined') {
+  var cwd = utils.cwd();
   module.paths.push(cwd, path.join(cwd, 'node_modules'));
 }
 
@@ -89,6 +118,8 @@ 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 {MochaRootHookObject} [options.rootHooks] - Hooks to bootstrap the root
+ * suite with
  */
 function Mocha(options) {
   options = utils.assign({}, mocharc, options || {});
@@ -96,6 +127,7 @@ function Mocha(options) {
   this.options = options;
   // root suite
   this.suite = new exports.Suite('', new exports.Context(), true);
+  this._cleanReferencesAfterRun = true;
 
   this.grep(options.grep)
     .fgrep(options.fgrep)
@@ -135,6 +167,10 @@ function Mocha(options) {
       this[opt]();
     }
   }, this);
+
+  if (options.rootHooks) {
+    this.rootHooks(options.rootHooks);
+  }
 }
 
 /**
@@ -201,24 +237,24 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
         _reporter = require(reporter);
       } 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(), reporter));
           } catch (_err) {
-            _err.code !== 'MODULE_NOT_FOUND' ||
-            _err.message.indexOf('Cannot find module') !== -1
-              ? console.warn(sQuote(reporter) + ' reporter not found')
-              : console.warn(
+            _err.code === 'MODULE_NOT_FOUND' ||
+            _err.message.indexOf('Cannot find module') >= 0
+              ? utils.warn(sQuote(reporter) + ' reporter not found')
+              : utils.warn(
                   sQuote(reporter) +
                     ' reporter blew up with error:\n' +
                     err.stack
                 );
           }
         } else {
-          console.warn(
+          utils.warn(
             sQuote(reporter) + ' reporter blew up with error:\n' + err.stack
           );
         }
@@ -290,16 +326,18 @@ Mocha.prototype.ui = function(ui) {
 };
 
 /**
- * Loads `files` prior to execution.
+ * Loads `files` prior to execution. Does not support ES Modules.
  *
  * @description
  * The implementation relies on Node's `require` to execute
  * the test interface functions and will be subject to its cache.
+ * Supports only CommonJS modules. To load ES modules, use Mocha#loadFilesAsync.
  *
  * @private
  * @see {@link Mocha#addFile}
  * @see {@link Mocha#run}
  * @see {@link Mocha#unloadFiles}
+ * @see {@link Mocha#loadFilesAsync}
  * @param {Function} [fn] - Callback invoked upon completion.
  */
 Mocha.prototype.loadFiles = function(fn) {
@@ -314,6 +352,49 @@ Mocha.prototype.loadFiles = function(fn) {
   fn && fn();
 };
 
+/**
+ * Loads `files` prior to execution. Supports Node ES Modules.
+ *
+ * @description
+ * The implementation relies on Node's `require` and `import` to execute
+ * the test interface functions and will be subject to its cache.
+ * Supports both CJS and ESM modules.
+ *
+ * @public
+ * @see {@link Mocha#addFile}
+ * @see {@link Mocha#run}
+ * @see {@link Mocha#unloadFiles}
+ * @returns {Promise}
+ * @example
+ *
+ * // loads ESM (and CJS) test files asynchronously, then runs root suite
+ * mocha.loadFilesAsync()
+ *   .then(() => mocha.run(failures => process.exitCode = failures ? 1 : 0))
+ *   .catch(() => process.exitCode = 1);
+ */
+Mocha.prototype.loadFilesAsync = function() {
+  var self = this;
+  var suite = this.suite;
+  this.loadAsync = true;
+
+  if (!esmUtils) {
+    return new Promise(function(resolve) {
+      self.loadFiles(resolve);
+    });
+  }
+
+  return esmUtils.loadFilesAsync(
+    this.files,
+    function(file) {
+      suite.emit(EVENT_FILE_PRE_REQUIRE, global, file, self);
+    },
+    function(file, resultModule) {
+      suite.emit(EVENT_FILE_REQUIRE, resultModule, file, self);
+      suite.emit(EVENT_FILE_POST_REQUIRE, global, file, self);
+    }
+  );
+};
+
 /**
  * Removes a previously loaded file from Node's `require` cache.
  *
@@ -330,8 +411,9 @@ Mocha.unloadFile = function(file) {
  * Unloads `files` from Node's `require` cache.
  *
  * @description
- * This allows files to be "freshly" reloaded, providing the ability
+ * This allows required files to be "freshly" reloaded, providing the ability
  * to reuse a Mocha instance programmatically.
+ * Note: does not clear ESM module files from the cache
  *
  * <strong>Intended for consumers &mdash; not used internally</strong>
  *
@@ -341,7 +423,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;
 };
 
@@ -459,6 +552,38 @@ Mocha.prototype.checkLeaks = function(checkLeaks) {
   return this;
 };
 
+/**
+ * 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 {@link Mocha#dispose}
+ * @param {boolean} cleanReferencesAfterRun
+ * @return {Mocha} this
+ * @chainable
+ */
+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.
  *
@@ -809,6 +934,28 @@ 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.
+ */
+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".
  *
@@ -842,16 +989,30 @@ Object.defineProperty(Mocha.prototype, 'version', {
  * @see {@link Mocha#unloadFiles}
  * @see {@link Runner#run}
  * @param {DoneCB} [fn] - Callback invoked when test execution completed.
- * @return {Runner} runner instance
+ * @returns {Runner} runner instance
+ * @example
+ *
+ * // exit with non-zero status if there were test failures
+ * mocha.run(failures => process.exitCode = failures ? 1 : 0);
  */
 Mocha.prototype.run = function(fn) {
-  if (this.files.length) {
+  this._guardRunningStateTransition();
+  this._state = mochaStates.RUNNING;
+  if (this._previousRunner) {
+    this._previousRunner.dispose();
+    this.suite.reset();
+  }
+  if (this.files.length && !this.loadAsync) {
     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 exports.Runner(suite, {
+    delay: options.delay,
+    cleanReferencesAfterRun: this._cleanReferencesAfterRun
+  });
   createStatsCollector(runner);
   var reporter = new this._reporter(runner, options);
   runner.checkLeaks = options.checkLeaks === true;
@@ -876,6 +1037,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);
@@ -886,3 +1053,46 @@ Mocha.prototype.run = function(fn) {
 
   return runner.run(done);
 };
+
+/**
+ * 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;
+};
+
+/**
+ * An alternative way to define root hooks that works with parallel runs.
+ * @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.
+ * @callback MochaRootHookFunction
+ * @returns {MochaRootHookObject|Promise<MochaRootHookObject>}
+ */

package/lib/mocharc.json

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

package/lib/reporters/doc.js

@@ -62,6 +62,7 @@ function Doc(runner, options) {
 
   runner.on(EVENT_TEST_PASS, function(test) {
     Base.consoleLog('%s  <dt>%s</dt>', indent(), utils.escape(test.title));
+    Base.consoleLog('%s  <dt>%s</dt>', indent(), utils.escape(test.file));
     var code = utils.escape(utils.clean(test.body));
     Base.consoleLog('%s  <dd><pre><code>%s</code></pre></dd>', indent(), code);
   });
@@ -72,6 +73,11 @@ function Doc(runner, options) {
       indent(),
       utils.escape(test.title)
     );
+    Base.consoleLog(
+      '%s  <dt class="error">%s</dt>',
+      indent(),
+      utils.escape(test.file)
+    );
     var code = utils.escape(utils.clean(test.body));
     Base.consoleLog(
       '%s  <dd class="error"><pre><code>%s</code></pre></dd>',

package/lib/reporters/json-stream.js

@@ -82,6 +82,7 @@ function clean(test) {
   return {
     title: test.title,
     fullTitle: test.fullTitle(),
+    file: test.file,
     duration: test.duration,
     currentRetry: test.currentRetry()
   };

package/lib/reporters/json.js

@@ -87,6 +87,7 @@ function clean(test) {
   return {
     title: test.title,
     fullTitle: test.fullTitle(),
+    file: test.file,
     duration: test.duration,
     currentRetry: test.currentRetry(),
     err: cleanCycles(err)

package/lib/reporters/landing.js

@@ -98,6 +98,14 @@ function Landing(runner, options) {
     process.stdout.write('\n');
     self.epilogue();
   });
+
+  // if cursor is hidden when we ctrl-C, then it will remain hidden unless...
+  process.once('SIGINT', function() {
+    cursor.show();
+    process.nextTick(function() {
+      process.kill(process.pid, 'SIGINT');
+    });
+  });
 }
 
 /**

package/lib/runnable.js

@@ -5,8 +5,9 @@ var Pending = require('./pending');
 var debug = require('debug')('mocha:runnable');
 var milliseconds = require('ms');
 var utils = require('./utils');
-var createInvalidExceptionError = require('./errors')
-  .createInvalidExceptionError;
+var errors = require('./errors');
+var createInvalidExceptionError = errors.createInvalidExceptionError;
+var createMultipleDoneError = errors.createMultipleDoneError;
 
 /**
  * Save timer references to avoid Sinon interfering (see GH-237).
@@ -36,10 +37,8 @@ function Runnable(title, fn) {
   this._timeout = 2000;
   this._slow = 75;
   this._enableTimeouts = true;
-  this.timedOut = false;
   this._retries = -1;
-  this._currentRetry = 0;
-  this.pending = false;
+  this.reset();
 }
 
 /**
@@ -47,6 +46,17 @@ function Runnable(title, fn) {
  */
 utils.inherits(Runnable, EventEmitter);
 
+/**
+ * Resets the state initially or for a next run.
+ */
+Runnable.prototype.reset = function() {
+  this.timedOut = false;
+  this._currentRetry = 0;
+  this.pending = false;
+  delete this.state;
+  delete this.err;
+};
+
 /**
  * Get current timeout value in msecs.
  *
@@ -222,31 +232,6 @@ Runnable.prototype.clearTimeout = function() {
   clearTimeout(this.timer);
 };
 
-/**
- * Inspect the runnable void of private properties.
- *
- * @private
- * @return {string}
- */
-Runnable.prototype.inspect = function() {
-  return JSON.stringify(
-    this,
-    function(key, val) {
-      if (key[0] === '_') {
-        return;
-      }
-      if (key === 'parent') {
-        return '#<Suite>';
-      }
-      if (key === 'ctx') {
-        return '#<Context>';
-      }
-      return val;
-    },
-    2
-  );
-};
-
 /**
  * Reset the timeout.
  *
@@ -293,7 +278,7 @@ Runnable.prototype.run = function(fn) {
   var start = new Date();
   var ctx = this.ctx;
   var finished;
-  var emitted;
+  var errorWasHandled = false;
 
   // Sometimes the ctx exists, but it is not runnable
   if (ctx && ctx.runnable) {
@@ -302,17 +287,11 @@ Runnable.prototype.run = function(fn) {
 
   // called multiple times
   function multiple(err) {
-    if (emitted) {
+    if (errorWasHandled) {
       return;
     }
-    emitted = true;
-    var msg = 'done() called multiple times';
-    if (err && err.message) {
-      err.message += " (and Mocha's " + msg + ')';
-      self.emit('error', err);
-    } else {
-      self.emit('error', new Error(msg));
-    }
+    errorWasHandled = true;
+    self.emit('error', createMultipleDoneError(self, err));
   }
 
   // finished
@@ -363,7 +342,7 @@ Runnable.prototype.run = function(fn) {
       callFnAsync(this.fn);
     } catch (err) {
       // handles async runnables which actually run synchronously
-      emitted = true;
+      errorWasHandled = true;
       if (err instanceof Pending) {
         return; // done() is already called in this.skip()
       } else if (this.allowUncaught) {
@@ -382,7 +361,7 @@ Runnable.prototype.run = function(fn) {
       callFn(this.fn);
     }
   } catch (err) {
-    emitted = true;
+    errorWasHandled = true;
     if (err instanceof Pending) {
       return done();
     } else if (this.allowUncaught) {