mocha 7.1.1 → 8.0.1

package/lib/runner.js

@@ -18,8 +18,8 @@ var HOOK_TYPE_BEFORE_ALL = Suite.constants.HOOK_TYPE_BEFORE_ALL;
 var EVENT_ROOT_SUITE_RUN = Suite.constants.EVENT_ROOT_SUITE_RUN;
 var STATE_FAILED = Runnable.constants.STATE_FAILED;
 var STATE_PASSED = Runnable.constants.STATE_PASSED;
+var STATE_PENDING = Runnable.constants.STATE_PENDING;
 var dQuote = utils.dQuote;
-var ngettext = utils.ngettext;
 var sQuote = utils.sQuote;
 var stackFilter = utils.stackTraceFilter();
 var stringify = utils.stringify;
@@ -27,6 +27,7 @@ var type = utils.type;
 var errors = require('./errors');
 var createInvalidExceptionError = errors.createInvalidExceptionError;
 var createUnsupportedError = errors.createUnsupportedError;
+var createFatalError = errors.createFatalError;
 
 /**
  * Non-enumerable globals.
@@ -109,7 +110,19 @@ var constants = utils.defineConstants(
     /**
      * Emitted when {@link Test} execution has failed, but will retry
      */
-    EVENT_TEST_RETRY: 'retry'
+    EVENT_TEST_RETRY: 'retry',
+    /**
+     * Initial state of Runner
+     */
+    STATE_IDLE: 'idle',
+    /**
+     * State set to this value when the Runner has started running
+     */
+    STATE_RUNNING: 'running',
+    /**
+     * State set to this value when the Runner has stopped
+     */
+    STATE_STOPPED: 'stopped'
   }
 );
 
@@ -121,21 +134,32 @@ module.exports = Runner;
  * @extends external:EventEmitter
  * @public
  * @class
- * @param {Suite} suite Root suite
- * @param {boolean} [delay] Whether or not to delay execution of root suite
- * until ready.
+ * @param {Suite} suite - Root suite
+ * @param {Object|boolean} [opts] - Options. If `boolean`, whether or not to delay execution of root suite until ready (for backwards compatibility).
+ * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
+ * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
  */
-function Runner(suite, delay) {
+function Runner(suite, opts) {
+  if (opts === undefined) {
+    opts = {};
+  }
+  if (typeof opts === 'boolean') {
+    this._delay = opts;
+    opts = {};
+  } else {
+    this._delay = opts.delay;
+  }
   var self = this;
   this._globals = [];
   this._abort = false;
-  this._delay = delay;
   this.suite = suite;
-  this.started = false;
+  this._opts = opts;
+  this.state = constants.STATE_IDLE;
   this.total = suite.total();
   this.failures = 0;
+  this._eventListeners = [];
   this.on(constants.EVENT_TEST_END, function(test) {
-    if (test.retriedTest() && test.parent) {
+    if (test.type === 'test' && test.retriedTest() && test.parent) {
       var idx =
         test.parent.tests && test.parent.tests.indexOf(test.retriedTest());
       if (idx > -1) test.parent.tests[idx] = test;
@@ -148,6 +172,8 @@ function Runner(suite, delay) {
   this._defaultGrep = /.*/;
   this.grep(this._defaultGrep);
   this.globals(this.globalProps());
+
+  this.uncaught = this._uncaught.bind(this);
 }
 
 /**
@@ -163,6 +189,58 @@ Runner.immediately = global.setImmediate || process.nextTick;
  */
 inherits(Runner, EventEmitter);
 
+/**
+ * Replacement for `target.on(eventName, listener)` that does bookkeeping to remove them when this runner instance is disposed.
+ * @param {EventEmitter} target - The `EventEmitter`
+ * @param {string} eventName - The event name
+ * @param {string} fn - Listener function
+ * @private
+ */
+Runner.prototype._addEventListener = function(target, eventName, listener) {
+  target.on(eventName, listener);
+  this._eventListeners.push([target, eventName, listener]);
+};
+
+/**
+ * Replacement for `target.removeListener(eventName, listener)` that also updates the bookkeeping.
+ * @param {EventEmitter} target - The `EventEmitter`
+ * @param {string} eventName - The event anme
+ * @param {function} listener - Listener function
+ * @private
+ */
+Runner.prototype._removeEventListener = function(target, eventName, listener) {
+  var eventListenerIndex = -1;
+  for (var i = 0; i < this._eventListeners.length; i++) {
+    var eventListenerDescriptor = this._eventListeners[i];
+    if (
+      eventListenerDescriptor[0] === target &&
+      eventListenerDescriptor[1] === eventName &&
+      eventListenerDescriptor[2] === listener
+    ) {
+      eventListenerIndex = i;
+      break;
+    }
+  }
+  if (eventListenerIndex !== -1) {
+    var removedListener = this._eventListeners.splice(eventListenerIndex, 1)[0];
+    removedListener[0].removeListener(removedListener[1], removedListener[2]);
+  }
+};
+
+/**
+ * Removes all event handlers set during a run on this instance.
+ * Remark: this does _not_ clean/dispose the tests or suites themselves.
+ */
+Runner.prototype.dispose = function() {
+  this.removeAllListeners();
+  this._eventListeners.forEach(function(eventListenerDescriptor) {
+    eventListenerDescriptor[0].removeListener(
+      eventListenerDescriptor[1],
+      eventListenerDescriptor[2]
+    );
+  });
+};
+
 /**
  * Run tests with full titles matching `re`. Updates runner.total
  * with number of tests matched.
@@ -174,7 +252,7 @@ inherits(Runner, EventEmitter);
  * @return {Runner} Runner instance.
  */
 Runner.prototype.grep = function(re, invert) {
-  debug('grep %s', re);
+  debug('grep(): setting to %s', re);
   this._grep = re;
   this._invert = invert;
   this.total = this.grepTotal(this.suite);
@@ -239,7 +317,7 @@ Runner.prototype.globals = function(arr) {
   if (!arguments.length) {
     return this._globals;
   }
-  debug('globals %j', arr);
+  debug('globals(): setting to %O', arr);
   this._globals = this._globals.concat(arr);
   return this;
 };
@@ -271,12 +349,8 @@ Runner.prototype.checkGlobals = function(test) {
   this._globals = this._globals.concat(leaks);
 
   if (leaks.length) {
-    var format = ngettext(
-      leaks.length,
-      'global leak detected: %s',
-      'global leaks detected: %s'
-    );
-    var error = new Error(util.format(format, leaks.map(sQuote).join(', ')));
+    var msg = 'global leak(s) detected: %s';
+    var error = new Error(util.format(msg, leaks.map(sQuote).join(', ')));
     this.fail(test, error);
   }
 };
@@ -285,15 +359,27 @@ Runner.prototype.checkGlobals = function(test) {
  * Fail the given `test`.
  *
  * @private
- * @param {Test} test
+ * @param {Runnable} test
  * @param {Error} err
+ * @param {boolean} [force=false] - Whether to fail a pending test.
  */
-Runner.prototype.fail = function(test, err) {
-  if (test.isPending()) {
+Runner.prototype.fail = function(test, err, force) {
+  force = force === true;
+  if (test.isPending() && !force) {
     return;
   }
+  if (this.state === constants.STATE_STOPPED) {
+    if (err.code === errors.constants.MULTIPLE_DONE) {
+      throw err;
+    }
+    throw createFatalError(
+      'Test failed after root suite execution completed!',
+      err
+    );
+  }
 
   ++this.failures;
+  debug('total number of failures: %d', this.failures);
   test.state = STATE_FAILED;
 
   if (!isError(err)) {
@@ -381,12 +467,12 @@ Runner.prototype.hook = function(name, fn) {
     self.emit(constants.EVENT_HOOK_BEGIN, hook);
 
     if (!hook.listeners('error').length) {
-      hook.on('error', function(err) {
+      self._addEventListener(hook, 'error', function(err) {
         self.failHook(hook, err);
       });
     }
 
-    hook.run(function(err) {
+    hook.run(function cbHookRun(err) {
       var testError = hook.error();
       if (testError) {
         self.fail(self.test, testError);
@@ -412,6 +498,7 @@ Runner.prototype.hook = function(name, fn) {
           suite.suites.forEach(function(suite) {
             suite.pending = true;
           });
+          hooks = [];
         } else {
           hook.pending = false;
           var errForbid = createUnsupportedError('`this.skip` forbidden');
@@ -524,18 +611,10 @@ Runner.prototype.runTest = function(fn) {
     return;
   }
 
-  var suite = this.parents().reverse()[0] || this.suite;
-  if (this.forbidOnly && suite.hasOnly()) {
-    fn(new Error('`.only` forbidden'));
-    return;
-  }
   if (this.asyncOnly) {
     test.asyncOnly = true;
   }
-  test.on('error', function(err) {
-    if (err instanceof Pending) {
-      return;
-    }
+  this._addEventListener(test, 'error', function(err) {
     self.fail(test, err);
   });
   if (this.allowUncaught) {
@@ -634,10 +713,9 @@ Runner.prototype.runTests = function(suite, fn) {
     // static skip, no hooks are executed
     if (test.isPending()) {
       if (self.forbidPending) {
-        test.isPending = alwaysFalse;
-        self.fail(test, new Error('Pending test forbidden'));
-        delete test.isPending;
+        self.fail(test, new Error('Pending test forbidden'), true);
       } else {
+        test.state = STATE_PENDING;
         self.emit(constants.EVENT_TEST_PENDING, test);
       }
       self.emit(constants.EVENT_TEST_END, test);
@@ -650,10 +728,9 @@ Runner.prototype.runTests = function(suite, fn) {
       // conditional skip within beforeEach
       if (test.isPending()) {
         if (self.forbidPending) {
-          test.isPending = alwaysFalse;
-          self.fail(test, new Error('Pending test forbidden'));
-          delete test.isPending;
+          self.fail(test, new Error('Pending test forbidden'), true);
         } else {
+          test.state = STATE_PENDING;
           self.emit(constants.EVENT_TEST_PENDING, test);
         }
         self.emit(constants.EVENT_TEST_END, test);
@@ -674,10 +751,9 @@ Runner.prototype.runTests = function(suite, fn) {
         // conditional skip within it
         if (test.pending) {
           if (self.forbidPending) {
-            test.isPending = alwaysFalse;
-            self.fail(test, new Error('Pending test forbidden'));
-            delete test.isPending;
+            self.fail(test, new Error('Pending test forbidden'), true);
           } else {
+            test.state = STATE_PENDING;
             self.emit(constants.EVENT_TEST_PENDING, test);
           }
           self.emit(constants.EVENT_TEST_END, test);
@@ -714,10 +790,6 @@ Runner.prototype.runTests = function(suite, fn) {
   next();
 };
 
-function alwaysFalse() {
-  return false;
-}
-
 /**
  * Run the given `suite` and invoke the callback `fn()` when complete.
  *
@@ -730,9 +802,10 @@ Runner.prototype.runSuite = function(suite, fn) {
   var self = this;
   var total = this.grepTotal(suite);
 
-  debug('run suite %s', suite.fullTitle());
+  debug('runSuite(): running %s', suite.fullTitle());
 
   if (!total || (self.failures && suite._bail)) {
+    debug('runSuite(): bailing');
     return fn();
   }
 
@@ -798,22 +871,49 @@ Runner.prototype.runSuite = function(suite, fn) {
 /**
  * Handle uncaught exceptions within runner.
  *
- * @param {Error} err
+ * This function is bound to the instance as `Runner#uncaught` at instantiation
+ * time. It's intended to be listening on the `Process.uncaughtException` event.
+ * In order to not leak EE listeners, we need to ensure no more than a single
+ * `uncaughtException` listener exists per `Runner`.  The only way to do
+ * this--because this function needs the context (and we don't have lambdas)--is
+ * to use `Function.prototype.bind`. We need strict equality to unregister and
+ * _only_ unregister the _one_ listener we set from the
+ * `Process.uncaughtException` event; would be poor form to just remove
+ * everything. See {@link Runner#run} for where the event listener is registered
+ * and unregistered.
+ * @param {Error} err - Some uncaught error
  * @private
  */
-Runner.prototype.uncaught = function(err) {
+Runner.prototype._uncaught = function(err) {
+  // this is defensive to prevent future developers from mis-calling this function.
+  // it's more likely that it'd be called with the incorrect context--say, the global
+  // `process` object--than it would to be called with a context that is not a "subclass"
+  // of `Runner`.
+  if (!(this instanceof Runner)) {
+    throw createFatalError(
+      'Runner#uncaught() called with invalid context',
+      this
+    );
+  }
   if (err instanceof Pending) {
+    debug('uncaught(): caught a Pending');
     return;
   }
   // browser does not exit script when throwing in global.onerror()
-  if (this.allowUncaught && !process.browser) {
+  if (this.allowUncaught && !utils.isBrowser()) {
+    debug('uncaught(): bubbling exception due to --allow-uncaught');
+    throw err;
+  }
+
+  if (this.state === constants.STATE_STOPPED) {
+    debug('uncaught(): throwing after run has completed!');
     throw err;
   }
 
   if (err) {
-    debug('uncaught exception %O', err);
+    debug('uncaught(): got truthy exception %O', err);
   } else {
-    debug('uncaught undefined/falsy exception');
+    debug('uncaught(): undefined/falsy exception');
     err = createInvalidExceptionError(
       'Caught falsy/undefined exception which would otherwise be uncaught. No stack trace found; try a debugger',
       err
@@ -822,6 +922,7 @@ Runner.prototype.uncaught = function(err) {
 
   if (!isError(err)) {
     err = thrown2Error(err);
+    debug('uncaught(): converted "error" %o to Error', err);
   }
   err.uncaught = true;
 
@@ -829,12 +930,15 @@ Runner.prototype.uncaught = function(err) {
 
   if (!runnable) {
     runnable = new Runnable('Uncaught error outside test suite');
+    debug('uncaught(): no current Runnable; created a phony one');
     runnable.parent = this.suite;
 
-    if (this.started) {
+    if (this.state === constants.STATE_RUNNING) {
+      debug('uncaught(): failing gracefully');
       this.fail(runnable, err);
     } else {
       // Can't recover from this failure
+      debug('uncaught(): test run has not yet started; unrecoverable');
       this.emit(constants.EVENT_RUN_BEGIN);
       this.fail(runnable, err);
       this.emit(constants.EVENT_RUN_END);
@@ -846,98 +950,94 @@ Runner.prototype.uncaught = function(err) {
   runnable.clearTimeout();
 
   if (runnable.isFailed()) {
+    debug('uncaught(): Runnable has already failed');
     // Ignore error if already failed
     return;
   } else if (runnable.isPending()) {
+    debug('uncaught(): pending Runnable wound up failing!');
     // report 'pending test' retrospectively as failed
-    runnable.isPending = alwaysFalse;
-    this.fail(runnable, err);
-    delete runnable.isPending;
+    this.fail(runnable, err, true);
     return;
   }
 
   // we cannot recover gracefully if a Runnable has already passed
   // then fails asynchronously
   if (runnable.isPassed()) {
+    debug('uncaught(): Runnable has already passed; bailing gracefully');
     this.fail(runnable, err);
     this.abort();
   } else {
-    debug(runnable);
+    debug('uncaught(): forcing Runnable to complete with Error');
     return runnable.callback(err);
   }
 };
 
-/**
- * Handle uncaught exceptions after runner's end event.
- *
- * @param {Error} err
- * @private
- */
-Runner.prototype.uncaughtEnd = function uncaughtEnd(err) {
-  if (err instanceof Pending) return;
-  throw err;
-};
-
 /**
  * Run the root suite and invoke `fn(failures)`
  * on completion.
  *
  * @public
  * @memberof Runner
- * @param {Function} fn
+ * @param {Function} fn - Callback when finished
+ * @param {{files: string[], options: Options}} [opts] - For subclasses
  * @return {Runner} Runner instance.
  */
-Runner.prototype.run = function(fn) {
+Runner.prototype.run = function(fn, opts) {
   var self = this;
   var rootSuite = this.suite;
 
   fn = fn || function() {};
 
-  function uncaught(err) {
-    self.uncaught(err);
-  }
-
   function start() {
+    debug('run(): starting');
     // If there is an `only` filter
     if (rootSuite.hasOnly()) {
       rootSuite.filterOnly();
+      debug('run(): filtered exclusive Runnables');
     }
-    self.started = true;
+    self.state = constants.STATE_RUNNING;
     if (self._delay) {
       self.emit(constants.EVENT_DELAY_END);
+      debug('run(): "delay" ended');
     }
+    debug('run(): emitting %s', constants.EVENT_RUN_BEGIN);
     self.emit(constants.EVENT_RUN_BEGIN);
+    debug('run(): emitted %s', constants.EVENT_RUN_BEGIN);
 
     self.runSuite(rootSuite, function() {
-      debug('finished running');
+      debug(
+        'run(): root suite completed; emitting %s',
+        constants.EVENT_RUN_END
+      );
       self.emit(constants.EVENT_RUN_END);
+      debug('run(): emitted %s', constants.EVENT_RUN_END);
     });
   }
 
-  debug(constants.EVENT_RUN_BEGIN);
-
   // references cleanup to avoid memory leaks
-  this.on(constants.EVENT_SUITE_END, function(suite) {
-    suite.cleanReferences();
-  });
+  if (this._opts.cleanReferencesAfterRun) {
+    this.on(constants.EVENT_SUITE_END, function(suite) {
+      suite.cleanReferences();
+    });
+  }
 
   // callback
   this.on(constants.EVENT_RUN_END, function() {
+    self.state = constants.STATE_STOPPED;
     debug(constants.EVENT_RUN_END);
-    process.removeListener('uncaughtException', uncaught);
-    process.on('uncaughtException', self.uncaughtEnd);
+    debug('run(): emitted %s', constants.EVENT_RUN_END);
     fn(self.failures);
   });
 
-  // uncaught exception
-  process.removeListener('uncaughtException', self.uncaughtEnd);
-  process.on('uncaughtException', uncaught);
+  self._removeEventListener(process, 'uncaughtException', self.uncaught);
+  self._addEventListener(process, 'uncaughtException', self.uncaught);
 
   if (this._delay) {
     // for reporters, I guess.
     // might be nice to debounce some dots while we wait.
     this.emit(constants.EVENT_DELAY_BEGIN, rootSuite);
     rootSuite.once(EVENT_ROOT_SUITE_RUN, start);
+    debug('run(): waiting for green light due to --delay');
   } else {
     Runner.immediately(function() {
       start();
@@ -955,7 +1055,7 @@ Runner.prototype.run = function(fn) {
  * @return {Runner} Runner instance.
  */
 Runner.prototype.abort = function() {
-  debug('aborting');
+  debug('abort(): aborting');
   this._abort = true;
 
   return this;

package/lib/suite.js

@@ -61,20 +61,19 @@ function Suite(title, parentContext, isRoot) {
   this.ctx = new Context();
   this.suites = [];
   this.tests = [];
+  this.root = isRoot === true;
   this.pending = false;
+  this._retries = -1;
   this._beforeEach = [];
   this._beforeAll = [];
   this._afterEach = [];
   this._afterAll = [];
-  this.root = isRoot === true;
   this._timeout = 2000;
-  this._enableTimeouts = true;
   this._slow = 75;
   this._bail = false;
-  this._retries = -1;
   this._onlyTests = [];
   this._onlySuites = [];
-  this.delayed = false;
+  this.reset();
 
   this.on('newListener', function(event) {
     if (deprecatedEvents[event]) {
@@ -92,6 +91,22 @@ function Suite(title, parentContext, isRoot) {
  */
 inherits(Suite, EventEmitter);
 
+/**
+ * Resets the state initially or for a next run.
+ */
+Suite.prototype.reset = function() {
+  this.delayed = false;
+  function doReset(thingToReset) {
+    thingToReset.reset();
+  }
+  this.suites.forEach(doReset);
+  this.tests.forEach(doReset);
+  this._beforeEach.forEach(doReset);
+  this._afterEach.forEach(doReset);
+  this._beforeAll.forEach(doReset);
+  this._afterAll.forEach(doReset);
+};
+
 /**
  * Return a clone of this `Suite`.
  *
@@ -105,7 +120,6 @@ Suite.prototype.clone = function() {
   suite.root = this.root;
   suite.timeout(this.timeout());
   suite.retries(this.retries());
-  suite.enableTimeouts(this.enableTimeouts());
   suite.slow(this.slow());
   suite.bail(this.bail());
   return suite;
@@ -123,12 +137,15 @@ Suite.prototype.timeout = function(ms) {
   if (!arguments.length) {
     return this._timeout;
   }
-  if (ms.toString() === '0') {
-    this._enableTimeouts = false;
-  }
   if (typeof ms === 'string') {
     ms = milliseconds(ms);
   }
+
+  // Clamp to range
+  var INT_MAX = Math.pow(2, 31) - 1;
+  var range = [0, INT_MAX];
+  ms = utils.clamp(ms, range);
+
   debug('timeout %d', ms);
   this._timeout = parseInt(ms, 10);
   return this;
@@ -150,22 +167,6 @@ Suite.prototype.retries = function(n) {
   return this;
 };
 
-/**
- * Set or get timeout to `enabled`.
- *
- * @private
- * @param {boolean} enabled
- * @return {Suite|boolean} self or enabled
- */
-Suite.prototype.enableTimeouts = function(enabled) {
-  if (!arguments.length) {
-    return this._enableTimeouts;
-  }
-  debug('enableTimeouts %s', enabled);
-  this._enableTimeouts = enabled;
-  return this;
-};
-
 /**
  * Set or get slow `ms` or short-hand such as "2s".
  *
@@ -222,7 +223,6 @@ Suite.prototype._createHook = function(title, fn) {
   hook.parent = this;
   hook.timeout(this.timeout());
   hook.retries(this.retries());
-  hook.enableTimeouts(this.enableTimeouts());
   hook.slow(this.slow());
   hook.ctx = this.ctx;
   hook.file = this.file;
@@ -337,7 +337,6 @@ Suite.prototype.addSuite = function(suite) {
   suite.root = false;
   suite.timeout(this.timeout());
   suite.retries(this.retries());
-  suite.enableTimeouts(this.enableTimeouts());
   suite.slow(this.slow());
   suite.bail(this.bail());
   this.suites.push(suite);
@@ -356,7 +355,6 @@ Suite.prototype.addTest = function(test) {
   test.parent = this;
   test.timeout(this.timeout());
   test.retries(this.retries());
-  test.enableTimeouts(this.enableTimeouts());
   test.slow(this.slow());
   test.ctx = this.ctx;
   this.tests.push(test);
@@ -493,6 +491,15 @@ Suite.prototype.appendOnlySuite = function(suite) {
   this._onlySuites.push(suite);
 };
 
+/**
+ * Marks a suite to be `only`.
+ *
+ * @private
+ */
+Suite.prototype.markOnly = function() {
+  this.parent && this.parent.appendOnlySuite(this);
+};
+
 /**
  * Adds a test to the list of tests marked `only`.
  *
@@ -511,6 +518,16 @@ Suite.prototype.getHooks = function getHooks(name) {
   return this['_' + name];
 };
 
+/**
+ * cleans all references from this suite and all child suites.
+ */
+Suite.prototype.dispose = function() {
+  this.suites.forEach(function(suite) {
+    suite.dispose();
+  });
+  this.cleanReferences();
+};
+
 /**
  * Cleans up the references to all the deferred functions
  * (before/after/beforeEach/afterEach) and tests of a Suite.
@@ -549,6 +566,22 @@ Suite.prototype.cleanReferences = function cleanReferences() {
   }
 };
 
+/**
+ * Returns an object suitable for IPC.
+ * Functions are represented by keys beginning with `$$`.
+ * @private
+ * @returns {Object}
+ */
+Suite.prototype.serialize = function serialize() {
+  return {
+    _bail: this._bail,
+    $$fullTitle: this.fullTitle(),
+    $$isPending: this.isPending(),
+    root: this.root,
+    title: this.title
+  };
+};
+
 var constants = utils.defineConstants(
   /**
    * {@link Suite}-related constants.