mocha 7.1.2 → 8.1.0

package/lib/runner.js

@@ -2,6 +2,7 @@
 
 /**
  * Module dependencies.
+ * @private
  */
 var util = require('util');
 var EventEmitter = require('events').EventEmitter;
@@ -18,6 +19,7 @@ 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 sQuote = utils.sQuote;
 var stackFilter = utils.stackTraceFilter();
@@ -26,9 +28,11 @@ var type = utils.type;
 var errors = require('./errors');
 var createInvalidExceptionError = errors.createInvalidExceptionError;
 var createUnsupportedError = errors.createUnsupportedError;
+var createFatalError = errors.createFatalError;
 
 /**
  * Non-enumerable globals.
+ * @private
  * @readonly
  */
 var globals = [
@@ -108,7 +112,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'
   }
 );
 
@@ -120,19 +136,30 @@ 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.type === 'test' && test.retriedTest() && test.parent) {
       var idx =
@@ -147,6 +174,8 @@ function Runner(suite, delay) {
   this._defaultGrep = /.*/;
   this.grep(this._defaultGrep);
   this.globals(this.globalProps());
+
+  this.uncaught = this._uncaught.bind(this);
 }
 
 /**
@@ -162,6 +191,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.
@@ -173,7 +254,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);
@@ -238,7 +319,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;
 };
@@ -279,16 +360,41 @@ Runner.prototype.checkGlobals = function(test) {
 /**
  * Fail the given `test`.
  *
+ * If `test` is a hook, failures work in the following pattern:
+ * - If bail, run corresponding `after each` and `after` hooks,
+ *   then exit
+ * - Failed `before` hook skips all tests in a suite and subsuites,
+ *   but jumps to corresponding `after` hook
+ * - Failed `before each` hook skips remaining tests in a
+ *   suite and jumps to corresponding `after each` hook,
+ *   which is run only once
+ * - Failed `after` hook does not alter execution order
+ * - Failed `after each` hook skips remaining tests in a
+ *   suite and subsuites, but executes other `after each`
+ *   hooks
+ *
  * @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)) {
@@ -305,44 +411,6 @@ Runner.prototype.fail = function(test, err) {
   this.emit(constants.EVENT_TEST_FAIL, test, err);
 };
 
-/**
- * Fail the given `hook` with `err`.
- *
- * Hook failures work in the following pattern:
- * - If bail, run corresponding `after each` and `after` hooks,
- *   then exit
- * - Failed `before` hook skips all tests in a suite and subsuites,
- *   but jumps to corresponding `after` hook
- * - Failed `before each` hook skips remaining tests in a
- *   suite and jumps to corresponding `after each` hook,
- *   which is run only once
- * - Failed `after` hook does not alter execution order
- * - Failed `after each` hook skips remaining tests in a
- *   suite and subsuites, but executes other `after each`
- *   hooks
- *
- * @private
- * @param {Hook} hook
- * @param {Error} err
- */
-Runner.prototype.failHook = function(hook, err) {
-  hook.originalTitle = hook.originalTitle || hook.title;
-  if (hook.ctx && hook.ctx.currentTest) {
-    hook.title =
-      hook.originalTitle + ' for ' + dQuote(hook.ctx.currentTest.title);
-  } else {
-    var parentTitle;
-    if (hook.parent.title) {
-      parentTitle = hook.parent.title;
-    } else {
-      parentTitle = hook.parent.root ? '{root}' : '';
-    }
-    hook.title = hook.originalTitle + ' in ' + dQuote(parentTitle);
-  }
-
-  this.fail(hook, err);
-};
-
 /**
  * Run hook `name` callbacks and then invoke `fn()`.
  *
@@ -371,17 +439,19 @@ Runner.prototype.hook = function(name, fn) {
       hook.ctx.currentTest = self.test;
     }
 
+    setHookTitle(hook);
+
     hook.allowUncaught = self.allowUncaught;
 
     self.emit(constants.EVENT_HOOK_BEGIN, hook);
 
     if (!hook.listeners('error').length) {
-      hook.on('error', function(err) {
-        self.failHook(hook, err);
+      self._addEventListener(hook, 'error', function(err) {
+        self.fail(hook, err);
       });
     }
 
-    hook.run(function(err) {
+    hook.run(function cbHookRun(err) {
       var testError = hook.error();
       if (testError) {
         self.fail(self.test, testError);
@@ -407,21 +477,39 @@ 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');
-          self.failHook(hook, errForbid);
+          self.fail(hook, errForbid);
           return fn(errForbid);
         }
       } else if (err) {
-        self.failHook(hook, err);
+        self.fail(hook, err);
         // stop executing hooks, notify callee of hook err
         return fn(err);
       }
       self.emit(constants.EVENT_HOOK_END, hook);
       delete hook.ctx.currentTest;
+      setHookTitle(hook);
       next(++i);
     });
+
+    function setHookTitle(hook) {
+      hook.originalTitle = hook.originalTitle || hook.title;
+      if (hook.ctx && hook.ctx.currentTest) {
+        hook.title =
+          hook.originalTitle + ' for ' + dQuote(hook.ctx.currentTest.title);
+      } else {
+        var parentTitle;
+        if (hook.parent.title) {
+          parentTitle = hook.parent.title;
+        } else {
+          parentTitle = hook.parent.root ? '{root}' : '';
+        }
+        hook.title = hook.originalTitle + ' in ' + dQuote(parentTitle);
+      }
+    }
   }
 
   Runner.immediately(function() {
@@ -519,18 +607,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) {
@@ -629,10 +709,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);
@@ -645,10 +724,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);
@@ -669,10 +747,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);
@@ -709,10 +786,6 @@ Runner.prototype.runTests = function(suite, fn) {
   next();
 };
 
-function alwaysFalse() {
-  return false;
-}
-
 /**
  * Run the given `suite` and invoke the callback `fn()` when complete.
  *
@@ -725,9 +798,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();
   }
 
@@ -793,22 +867,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
@@ -817,6 +918,7 @@ Runner.prototype.uncaught = function(err) {
 
   if (!isError(err)) {
     err = thrown2Error(err);
+    debug('uncaught(): converted "error" %o to Error', err);
   }
   err.uncaught = true;
 
@@ -824,12 +926,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);
@@ -841,98 +946,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();
@@ -950,7 +1051,7 @@ Runner.prototype.run = function(fn) {
  * @return {Runner} Runner instance.
  */
 Runner.prototype.abort = function() {
-  debug('aborting');
+  debug('abort(): aborting');
   this._abort = true;
 
   return this;