mocha-compat 3.6.4 → 10.8.2

package/lib/runner.js

@@ -2,28 +2,38 @@
 
 /**
  * Module dependencies.
+ * @private
  */
-
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var utils = require('./utils');
-var inherits = utils.inherits;
 var debug = require('debug')('mocha:runner');
 var Runnable = require('./runnable');
-var filter = utils.filter;
-var indexOf = utils.indexOf;
-var some = utils.some;
-var keys = utils.keys;
+var Suite = require('./suite');
+var HOOK_TYPE_BEFORE_EACH = Suite.constants.HOOK_TYPE_BEFORE_EACH;
+var HOOK_TYPE_AFTER_EACH = Suite.constants.HOOK_TYPE_AFTER_EACH;
+var HOOK_TYPE_AFTER_ALL = Suite.constants.HOOK_TYPE_AFTER_ALL;
+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 stackFilter = utils.stackTraceFilter();
 var stringify = utils.stringify;
-var type = utils.type;
-var undefinedError = utils.undefinedError;
-var isArray = utils.isArray;
+
+const {
+  createInvalidExceptionError,
+  createUnsupportedError,
+  createFatalError,
+  isMochaError,
+  constants: errorConstants
+} = require('./errors');
 
 /**
  * Non-enumerable globals.
+ * @private
+ * @readonly
  */
-
 var globals = [
   'setTimeout',
   'clearTimeout',
@@ -35,81 +45,259 @@ var globals = [
   'clearImmediate'
 ];
 
-/**
- * Expose `Runner`.
- */
-
-module.exports = Runner;
-
-/**
- * Initialize a `Runner` for the given `suite`.
- *
- * Events:
- *
- *   - `start`  execution started
- *   - `end`  execution complete
- *   - `suite`  (suite) test suite execution started
- *   - `suite end`  (suite) all tests (and sub-suites) have finished
- *   - `test`  (test) test execution started
- *   - `test end`  (test) test completed
- *   - `hook`  (hook) hook execution started
- *   - `hook end`  (hook) hook complete
- *   - `pass`  (test) test passed
- *   - `fail`  (test, err) test failed
- *   - `pending`  (test) test pending
- *
- * @api public
- * @param {Suite} suite Root suite
- * @param {boolean} [delay] Whether or not to delay execution of root suite
- * until ready.
- */
-function Runner (suite, delay) {
-  var self = this;
-  this._globals = [];
-  this._abort = false;
-  this._delay = delay;
-  this.suite = suite;
-  this.started = false;
-  this.total = suite.total();
-  this.failures = 0;
-  this.on('test end', function (test) {
-    self.checkGlobals(test);
-  });
-  this.on('hook end', function (hook) {
-    self.checkGlobals(hook);
-  });
-  this._defaultGrep = /.*/;
-  this.grep(this._defaultGrep);
-  this.globals(this.globalProps().concat(extraGlobals()));
+var constants = utils.defineConstants(
+  /**
+   * {@link Runner}-related constants.
+   * @public
+   * @memberof Runner
+   * @readonly
+   * @alias constants
+   * @static
+   * @enum {string}
+   */
+  {
+    /**
+     * Emitted when {@link Hook} execution begins
+     */
+    EVENT_HOOK_BEGIN: 'hook',
+    /**
+     * Emitted when {@link Hook} execution ends
+     */
+    EVENT_HOOK_END: 'hook end',
+    /**
+     * Emitted when Root {@link Suite} execution begins (all files have been parsed and hooks/tests are ready for execution)
+     */
+    EVENT_RUN_BEGIN: 'start',
+    /**
+     * Emitted when Root {@link Suite} execution has been delayed via `delay` option
+     */
+    EVENT_DELAY_BEGIN: 'waiting',
+    /**
+     * Emitted when delayed Root {@link Suite} execution is triggered by user via `global.run()`
+     */
+    EVENT_DELAY_END: 'ready',
+    /**
+     * Emitted when Root {@link Suite} execution ends
+     */
+    EVENT_RUN_END: 'end',
+    /**
+     * Emitted when {@link Suite} execution begins
+     */
+    EVENT_SUITE_BEGIN: 'suite',
+    /**
+     * Emitted when {@link Suite} execution ends
+     */
+    EVENT_SUITE_END: 'suite end',
+    /**
+     * Emitted when {@link Test} execution begins
+     */
+    EVENT_TEST_BEGIN: 'test',
+    /**
+     * Emitted when {@link Test} execution ends
+     */
+    EVENT_TEST_END: 'test end',
+    /**
+     * Emitted when {@link Test} execution fails
+     */
+    EVENT_TEST_FAIL: 'fail',
+    /**
+     * Emitted when {@link Test} execution succeeds
+     */
+    EVENT_TEST_PASS: 'pass',
+    /**
+     * Emitted when {@link Test} becomes pending
+     */
+    EVENT_TEST_PENDING: 'pending',
+    /**
+     * Emitted when {@link Test} execution has failed, but will 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'
+  }
+);
+
+class Runner extends EventEmitter {
+  /**
+   * Initialize a `Runner` at the Root {@link Suite}, which represents a hierarchy of {@link Suite|Suites} and {@link Test|Tests}.
+   *
+   * @extends external:EventEmitter
+   * @public
+   * @class
+   * @param {Suite} suite - Root suite
+   * @param {Object} [opts] - Settings object
+   * @param {boolean} [opts.cleanReferencesAfterRun] - Whether to clean references to test fns and hooks when a suite is done.
+   * @param {boolean} [opts.delay] - Whether to delay execution of root suite until ready.
+   * @param {boolean} [opts.dryRun] - Whether to report tests without running them.
+   * @param {boolean} [opts.failZero] - Whether to fail test run if zero tests encountered.
+   */
+  constructor(suite, opts = {}) {
+    super();
+
+    var self = this;
+    this._globals = [];
+    this._abort = false;
+    this.suite = suite;
+    this._opts = opts;
+    this.state = constants.STATE_IDLE;
+    this.total = suite.total();
+    this.failures = 0;
+    /**
+     * @type {Map<EventEmitter,Map<string,Set<EventListener>>>}
+     */
+    this._eventListeners = new Map();
+    this.on(constants.EVENT_TEST_END, function (test) {
+      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;
+      }
+      self.checkGlobals(test);
+    });
+    this.on(constants.EVENT_HOOK_END, function (hook) {
+      self.checkGlobals(hook);
+    });
+    this._defaultGrep = /.*/;
+    this.grep(this._defaultGrep);
+    this.globals(this.globalProps());
+
+    this.uncaught = this._uncaught.bind(this);
+    this.unhandled = (reason, promise) => {
+      if (isMochaError(reason)) {
+        debug(
+          'trapped unhandled rejection coming out of Mocha; forwarding to uncaught handler:',
+          reason
+        );
+        this.uncaught(reason);
+      } else {
+        debug(
+          'trapped unhandled rejection from (probably) user code; re-emitting on process'
+        );
+        this._removeEventListener(
+          process,
+          'unhandledRejection',
+          this.unhandled
+        );
+        try {
+          process.emit('unhandledRejection', reason, promise);
+        } finally {
+          this._addEventListener(process, 'unhandledRejection', this.unhandled);
+        }
+      }
+    };
+  }
 }
 
 /**
  * Wrapper for setImmediate, process.nextTick, or browser polyfill.
  *
  * @param {Function} fn
- * @api private
+ * @private
  */
 Runner.immediately = global.setImmediate || process.nextTick;
 
 /**
- * Inherit from `EventEmitter.prototype`.
+ * 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) {
+  debug(
+    '_addEventListener(): adding for event %s; %d current listeners',
+    eventName,
+    target.listenerCount(eventName)
+  );
+  /* istanbul ignore next */
+  if (
+    this._eventListeners.has(target) &&
+    this._eventListeners.get(target).has(eventName) &&
+    this._eventListeners.get(target).get(eventName).has(listener)
+  ) {
+    debug(
+      'warning: tried to attach duplicate event listener for %s',
+      eventName
+    );
+    return;
+  }
+  target.on(eventName, listener);
+  const targetListeners = this._eventListeners.has(target)
+    ? this._eventListeners.get(target)
+    : new Map();
+  const targetEventListeners = targetListeners.has(eventName)
+    ? targetListeners.get(eventName)
+    : new Set();
+  targetEventListeners.add(listener);
+  targetListeners.set(eventName, targetEventListeners);
+  this._eventListeners.set(target, targetListeners);
+};
+
+/**
+ * Replacement for `target.removeListener(eventName, listener)` that also updates the bookkeeping.
+ * @param {EventEmitter} target - The `EventEmitter`
+ * @param {string} eventName - The event name
+ * @param {function} listener - Listener function
+ * @private
  */
-inherits(Runner, EventEmitter);
+Runner.prototype._removeEventListener = function (target, eventName, listener) {
+  target.removeListener(eventName, listener);
+
+  if (this._eventListeners.has(target)) {
+    const targetListeners = this._eventListeners.get(target);
+    if (targetListeners.has(eventName)) {
+      const targetEventListeners = targetListeners.get(eventName);
+      targetEventListeners.delete(listener);
+      if (!targetEventListeners.size) {
+        targetListeners.delete(eventName);
+      }
+    }
+    if (!targetListeners.size) {
+      this._eventListeners.delete(target);
+    }
+  } else {
+    debug('trying to remove listener for untracked object %s', target);
+  }
+};
+
+/**
+ * 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((targetListeners, target) => {
+    targetListeners.forEach((targetEventListeners, eventName) => {
+      targetEventListeners.forEach(listener => {
+        target.removeListener(eventName, listener);
+      });
+    });
+  });
+  this._eventListeners.clear();
+};
 
 /**
  * Run tests with full titles matching `re`. Updates runner.total
  * with number of tests matched.
  *
- * @param {RegExp} re
- * @param {Boolean} invert
- * @return {Runner} for chaining
- * @api public
+ * @public
+ * @memberof Runner
  * @param {RegExp} re
  * @param {boolean} invert
  * @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);
@@ -120,9 +308,8 @@ Runner.prototype.grep = function (re, invert) {
  * Returns the number of tests matching the grep search for the
  * given suite.
  *
- * @param {Suite} suite
- * @return {Number}
- * @api public
+ * @memberof Runner
+ * @public
  * @param {Suite} suite
  * @return {number}
  */
@@ -147,14 +334,14 @@ Runner.prototype.grepTotal = function (suite) {
  * Return a list of global properties.
  *
  * @return {Array}
- * @api private
+ * @private
  */
 Runner.prototype.globalProps = function () {
-  var props = keys(global);
+  var props = Object.keys(global);
 
   // non-enumerables
   for (var i = 0; i < globals.length; ++i) {
-    if (~indexOf(props, globals[i])) {
+    if (~props.indexOf(globals[i])) {
       continue;
     }
     props.push(globals[i]);
@@ -166,9 +353,8 @@ Runner.prototype.globalProps = function () {
 /**
  * Allow the given `arr` of globals.
  *
- * @param {Array} arr
- * @return {Runner} for chaining
- * @api public
+ * @public
+ * @memberof Runner
  * @param {Array} arr
  * @return {Runner} Runner instance.
  */
@@ -176,7 +362,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;
 };
@@ -184,10 +370,10 @@ Runner.prototype.globals = function (arr) {
 /**
  * Check for global variable leaks.
  *
- * @api private
+ * @private
  */
 Runner.prototype.checkGlobals = function (test) {
-  if (this.ignoreLeaks) {
+  if (!this.checkLeaks) {
     return;
   }
   var ok = this._globals;
@@ -207,132 +393,177 @@ Runner.prototype.checkGlobals = function (test) {
   leaks = filterLeaks(ok, globals);
   this._globals = this._globals.concat(leaks);
 
-  if (leaks.length > 1) {
-    this.fail(test, new Error('global leaks detected: ' + leaks.join(', ') + ''));
-  } else if (leaks.length) {
-    this.fail(test, new Error('global leak detected: ' + leaks[0]));
+  if (leaks.length) {
+    var msg = `global leak(s) detected: ${leaks.map(e => `'${e}'`).join(', ')}`;
+    this.fail(test, new Error(msg));
   }
 };
 
 /**
  * Fail the given `test`.
  *
- * @api private
- * @param {Test} test
- * @param {Error} err
- */
-Runner.prototype.fail = function (test, err) {
-  if (test.isPending()) {
-    return;
-  }
-
-  ++this.failures;
-  test.state = 'failed';
-
-  if (!(err instanceof Error || err && typeof err.message === 'string')) {
-    err = new Error('the ' + type(err) + ' ' + stringify(err) + ' was thrown, throw an Error :)');
-  }
-
-  try {
-    err.stack = (this.fullStackTrace || !err.stack)
-      ? err.stack
-      : stackFilter(err.stack);
-  } catch (ignored) {
-    // some environments do not take kindly to monkeying with the stack
-  }
-
-  this.emit('fail', test, err);
-};
-
-/**
- * Fail the given `hook` with `err`.
- *
- * Hook failures work in the following pattern:
- * - If bail, then exit
+ * 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` hook does not alter execution order
  * - Failed `after each` hook skips remaining tests in a
  *   suite and subsuites, but executes other `after each`
  *   hooks
  *
- * @api private
- * @param {Hook} hook
+ * @private
+ * @param {Runnable} test
  * @param {Error} err
+ * @param {boolean} [force=false] - Whether to fail a pending test.
  */
-Runner.prototype.failHook = function (hook, err) {
-  if (hook.ctx && hook.ctx.currentTest) {
-    hook.originalTitle = hook.originalTitle || hook.title;
-    hook.title = hook.originalTitle + ' for "' + hook.ctx.currentTest.title + '"';
+Runner.prototype.fail = function (test, err, force) {
+  force = force === true;
+  if (test.isPending() && !force) {
+    return;
+  }
+  if (this.state === constants.STATE_STOPPED) {
+    if (err.code === errorConstants.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)) {
+    err = thrown2Error(err);
   }
 
-  this.fail(hook, err);
-  if (this.suite.bail()) {
-    this.emit('end');
+  // Filter the stack traces
+  if (!this.fullStackTrace) {
+    const alreadyFiltered = new Set();
+    let currentErr = err;
+
+    while (currentErr && currentErr.stack && !alreadyFiltered.has(currentErr)) {
+      alreadyFiltered.add(currentErr);
+
+      try {
+        currentErr.stack = stackFilter(currentErr.stack);
+      } catch (ignore) {
+        // some environments do not take kindly to monkeying with the stack
+      }
+
+      currentErr = currentErr.cause;
+    }
   }
+
+  this.emit(constants.EVENT_TEST_FAIL, test, err);
 };
 
 /**
  * Run hook `name` callbacks and then invoke `fn()`.
  *
- * @api private
+ * @private
  * @param {string} name
  * @param {Function} fn
  */
 
 Runner.prototype.hook = function (name, fn) {
+  if (this._opts.dryRun) return fn();
+
   var suite = this.suite;
-  var hooks = suite['_' + name];
+  var hooks = suite.getHooks(name);
   var self = this;
 
-  function next (i) {
+  function next(i) {
     var hook = hooks[i];
     if (!hook) {
       return fn();
     }
     self.currentRunnable = hook;
 
-    hook.ctx.currentTest = self.test;
+    if (name === HOOK_TYPE_BEFORE_ALL) {
+      hook.ctx.currentTest = hook.parent.tests[0];
+    } else if (name === HOOK_TYPE_AFTER_ALL) {
+      hook.ctx.currentTest = hook.parent.tests[hook.parent.tests.length - 1];
+    } else {
+      hook.ctx.currentTest = self.test;
+    }
+
+    setHookTitle(hook);
 
-    self.emit('hook', 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);
       }
-      if (err) {
-        if (err instanceof Pending) {
-          if (name === 'beforeEach' || name === 'afterEach') {
+      // conditional skip
+      if (hook.pending) {
+        if (name === HOOK_TYPE_AFTER_EACH) {
+          // TODO define and implement use case
+          if (self.test) {
             self.test.pending = true;
-          } else {
-            utils.forEach(suite.tests, function (test) {
-              test.pending = true;
-            });
-            // a pending hook won't be executed twice.
-            hook.pending = true;
           }
+        } else if (name === HOOK_TYPE_BEFORE_EACH) {
+          if (self.test) {
+            self.test.pending = true;
+          }
+          self.emit(constants.EVENT_HOOK_END, hook);
+          hook.pending = false; // activates hook for next test
+          return fn(new Error('abort hookDown'));
+        } else if (name === HOOK_TYPE_BEFORE_ALL) {
+          suite.tests.forEach(function (test) {
+            test.pending = true;
+          });
+          suite.suites.forEach(function (suite) {
+            suite.pending = true;
+          });
+          hooks = [];
         } else {
-          self.failHook(hook, err);
-
-          // stop executing hooks, notify callee of hook err
-          return fn(err);
+          hook.pending = false;
+          var errForbid = createUnsupportedError('`this.skip` forbidden');
+          self.fail(hook, errForbid);
+          return fn(errForbid);
         }
+      } else if (err) {
+        self.fail(hook, err);
+        // stop executing hooks, notify callee of hook err
+        return fn(err);
       }
-      self.emit('hook end', hook);
+      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 "${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 "${parentTitle}"`;
+      }
+    }
   }
 
   Runner.immediately(function () {
@@ -344,7 +575,7 @@ Runner.prototype.hook = function (name, fn) {
  * Run hook `name` for the given array of `suites`
  * in order, and callback `fn(err, errSuite)`.
  *
- * @api private
+ * @private
  * @param {string} name
  * @param {Array} suites
  * @param {Function} fn
@@ -353,7 +584,7 @@ Runner.prototype.hooks = function (name, suites, fn) {
   var self = this;
   var orig = this.suite;
 
-  function next (suite) {
+  function next(suite) {
     self.suite = suite;
 
     if (!suite) {
@@ -376,11 +607,11 @@ Runner.prototype.hooks = function (name, suites, fn) {
 };
 
 /**
- * Run hooks from the top level down.
+ * Run 'afterEach' hooks from bottom up.
  *
  * @param {String} name
  * @param {Function} fn
- * @api private
+ * @private
  */
 Runner.prototype.hookUp = function (name, fn) {
   var suites = [this.suite].concat(this.parents()).reverse();
@@ -388,11 +619,11 @@ Runner.prototype.hookUp = function (name, fn) {
 };
 
 /**
- * Run hooks from the bottom up.
+ * Run 'beforeEach' hooks from top level down.
  *
  * @param {String} name
  * @param {Function} fn
- * @api private
+ * @private
  */
 Runner.prototype.hookDown = function (name, fn) {
   var suites = [this.suite].concat(this.parents());
@@ -404,7 +635,7 @@ Runner.prototype.hookDown = function (name, fn) {
  * closest to furthest.
  *
  * @return {Array}
- * @api private
+ * @private
  */
 Runner.prototype.parents = function () {
   var suite = this.suite;
@@ -420,19 +651,22 @@ Runner.prototype.parents = function () {
  * Run the current test and callback `fn(err)`.
  *
  * @param {Function} fn
- * @api private
+ * @private
  */
 Runner.prototype.runTest = function (fn) {
+  if (this._opts.dryRun) return Runner.immediately(fn);
+
   var self = this;
   var test = this.test;
 
   if (!test) {
     return;
   }
+
   if (this.asyncOnly) {
     test.asyncOnly = true;
   }
-  test.on('error', function (err) {
+  this._addEventListener(test, 'error', function (err) {
     self.fail(test, err);
   });
   if (this.allowUncaught) {
@@ -449,7 +683,7 @@ Runner.prototype.runTest = function (fn) {
 /**
  * Run tests in the given `suite` and invoke the callback `fn()` when complete.
  *
- * @api private
+ * @private
  * @param {Suite} suite
  * @param {Function} fn
  */
@@ -458,7 +692,7 @@ Runner.prototype.runTests = function (suite, fn) {
   var tests = suite.tests.slice();
   var test;
 
-  function hookErr (_, errSuite, after) {
+  function hookErr(_, errSuite, after) {
     // before/after Each hook for errSuite failed:
     var orig = self.suite;
 
@@ -467,8 +701,7 @@ Runner.prototype.runTests = function (suite, fn) {
     self.suite = after ? errSuite.parent : errSuite;
 
     if (self.suite) {
-      // call hookUp afterEach
-      self.hookUp('afterEach', function (err2, errSuite2) {
+      self.hookUp(HOOK_TYPE_AFTER_EACH, function (err2, errSuite2) {
         self.suite = orig;
         // some hooks may fail even now
         if (err2) {
@@ -484,10 +717,10 @@ Runner.prototype.runTests = function (suite, fn) {
     }
   }
 
-  function next (err, errSuite) {
+  function next(err, errSuite) {
     // if we bail after first err
     if (self.failures && suite._bail) {
-      return fn();
+      tests = [];
     }
 
     if (self._abort) {
@@ -528,19 +761,37 @@ Runner.prototype.runTests = function (suite, fn) {
       return;
     }
 
+    // static skip, no hooks are executed
     if (test.isPending()) {
-      self.emit('pending', test);
-      self.emit('test end', test);
+      if (self.forbidPending) {
+        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);
       return next();
     }
 
     // execute test and hook(s)
-    self.emit('test', self.test = test);
-    self.hookDown('beforeEach', function (err, errSuite) {
+    self.emit(constants.EVENT_TEST_BEGIN, (self.test = test));
+    self.hookDown(HOOK_TYPE_BEFORE_EACH, function (err, errSuite) {
+      // conditional skip within beforeEach
       if (test.isPending()) {
-        self.emit('pending', test);
-        self.emit('test end', test);
-        return next();
+        if (self.forbidPending) {
+          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);
+        // skip inner afterEach hooks below errSuite level
+        var origSuite = self.suite;
+        self.suite = errSuite || self.suite;
+        return self.hookUp(HOOK_TYPE_AFTER_EACH, function (e, eSuite) {
+          self.suite = origSuite;
+          next(e, eSuite);
+        });
       }
       if (err) {
         return hookErr(err, errSuite, false);
@@ -548,35 +799,39 @@ Runner.prototype.runTests = function (suite, fn) {
       self.currentRunnable = self.test;
       self.runTest(function (err) {
         test = self.test;
-        if (err) {
+        // conditional skip within it
+        if (test.pending) {
+          if (self.forbidPending) {
+            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);
+          return self.hookUp(HOOK_TYPE_AFTER_EACH, next);
+        } else if (err) {
           var retry = test.currentRetry();
-          if (err instanceof Pending) {
-            test.pending = true;
-            self.emit('pending', test);
-          } else if (retry < test.retries()) {
+          if (retry < test.retries()) {
             var clonedTest = test.clone();
             clonedTest.currentRetry(retry + 1);
             tests.unshift(clonedTest);
 
+            self.emit(constants.EVENT_TEST_RETRY, test, err);
+
             // Early return + hook trigger so that it doesn't
             // increment the count wrong
-            return self.hookUp('afterEach', next);
+            return self.hookUp(HOOK_TYPE_AFTER_EACH, next);
           } else {
             self.fail(test, err);
           }
-          self.emit('test end', test);
-
-          if (err instanceof Pending) {
-            return next();
-          }
-
-          return self.hookUp('afterEach', next);
+          self.emit(constants.EVENT_TEST_END, test);
+          return self.hookUp(HOOK_TYPE_AFTER_EACH, next);
         }
 
-        test.state = 'passed';
-        self.emit('pass', test);
-        self.emit('test end', test);
-        self.hookUp('afterEach', next);
+        test.state = STATE_PASSED;
+        self.emit(constants.EVENT_TEST_PASS, test);
+        self.emit(constants.EVENT_TEST_END, test);
+        self.hookUp(HOOK_TYPE_AFTER_EACH, next);
       });
     });
   }
@@ -589,7 +844,7 @@ Runner.prototype.runTests = function (suite, fn) {
 /**
  * Run the given `suite` and invoke the callback `fn()` when complete.
  *
- * @api private
+ * @private
  * @param {Suite} suite
  * @param {Function} fn
  */
@@ -597,17 +852,17 @@ Runner.prototype.runSuite = function (suite, fn) {
   var i = 0;
   var self = this;
   var total = this.grepTotal(suite);
-  var afterAllHookCalled = false;
 
-  debug('run suite %s', suite.fullTitle());
+  debug('runSuite(): running %s', suite.fullTitle());
 
   if (!total || (self.failures && suite._bail)) {
+    debug('runSuite(): bailing');
     return fn();
   }
 
-  this.emit('suite', this.suite = suite);
+  this.emit(constants.EVENT_SUITE_BEGIN, (this.suite = suite));
 
-  function next (errSuite) {
+  function next(errSuite) {
     if (errSuite) {
       // current suite failed on a hook from errSuite
       if (errSuite === suite) {
@@ -641,30 +896,22 @@ Runner.prototype.runSuite = function (suite, fn) {
     }
   }
 
-  function done (errSuite) {
+  function done(errSuite) {
     self.suite = suite;
     self.nextSuite = next;
 
-    if (afterAllHookCalled) {
-      fn(errSuite);
-    } else {
-      // mark that the afterAll block has been called once
-      // and so can be skipped if there is an error in it.
-      afterAllHookCalled = true;
-
-      // remove reference to test
-      delete self.test;
+    // remove reference to test
+    delete self.test;
 
-      self.hook('afterAll', function () {
-        self.emit('suite end', suite);
-        fn(errSuite);
-      });
-    }
+    self.hook(HOOK_TYPE_AFTER_ALL, function () {
+      self.emit(constants.EVENT_SUITE_END, suite);
+      fn(errSuite);
+    });
   }
 
   this.nextSuite = next;
 
-  this.hook('beforeAll', function (err) {
+  this.hook(HOOK_TYPE_BEFORE_ALL, function (err) {
     if (err) {
       return done();
     }
@@ -673,19 +920,60 @@ Runner.prototype.runSuite = function (suite, fn) {
 };
 
 /**
- * Handle uncaught exceptions.
+ * Handle uncaught exceptions within runner.
  *
- * @param {Error} err
- * @api private
+ * 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 && !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 %s', err === (function () {
-      return this;
-    }.call(err)) ? (err.message || err) : err);
+    debug('uncaught(): got truthy exception %O', err);
   } else {
-    debug('uncaught undefined exception');
-    err = undefinedError();
+    debug('uncaught(): undefined/falsy exception');
+    err = createInvalidExceptionError(
+      'Caught falsy/undefined exception which would otherwise be uncaught. No stack trace found; try a debugger',
+      err
+    );
+  }
+
+  if (!isError(err)) {
+    err = thrown2Error(err);
+    debug('uncaught(): converted "error" %o to Error', err);
   }
   err.uncaught = true;
 
@@ -693,15 +981,18 @@ 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
-      this.emit('start');
+      debug('uncaught(): test run has not yet started; unrecoverable');
+      this.emit(constants.EVENT_RUN_BEGIN);
       this.fail(runnable, err);
-      this.emit('end');
+      this.emit(constants.EVENT_RUN_END);
     }
 
     return;
@@ -709,208 +1000,201 @@ Runner.prototype.uncaught = function (err) {
 
   runnable.clearTimeout();
 
-  // Ignore errors if complete or pending
-  if (runnable.state || runnable.isPending()) {
+  if (runnable.isFailed()) {
+    debug('uncaught(): Runnable has already failed');
+    // Ignore error if already failed
     return;
-  }
-  this.fail(runnable, err);
-
-  // recover from test
-  if (runnable.type === 'test') {
-    this.emit('test end', runnable);
-    this.hookUp('afterEach', this.next);
+  } else if (runnable.isPending()) {
+    debug('uncaught(): pending Runnable wound up failing!');
+    // report 'pending test' retrospectively as failed
+    this.fail(runnable, err, true);
     return;
   }
 
- // recover from hooks
-  if (runnable.type === 'hook') {
-    var errSuite = this.suite;
-    // if hook failure is in afterEach block
-    if (runnable.fullTitle().indexOf('after each') > -1) {
-      return this.hookErr(err, errSuite, true);
-    }
-    // if hook failure is in beforeEach block
-    if (runnable.fullTitle().indexOf('before each') > -1) {
-      return this.hookErr(err, errSuite, false);
-    }
-    // if hook failure is in after or before blocks
-    return this.nextSuite(errSuite);
+  // 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('uncaught(): forcing Runnable to complete with Error');
+    return runnable.callback(err);
   }
-
-  // bail
-  this.emit('end');
 };
 
-/**
- * Cleans up the references to all the deferred functions
- * (before/after/beforeEach/afterEach) and tests of a Suite.
- * These must be deleted otherwise a memory leak can happen,
- * as those functions may reference variables from closures,
- * thus those variables can never be garbage collected as long
- * as the deferred functions exist.
- *
- * @param {Suite} suite
- */
-function cleanSuiteReferences (suite) {
-  function cleanArrReferences (arr) {
-    for (var i = 0; i < arr.length; i++) {
-      delete arr[i].fn;
-    }
-  }
-
-  if (isArray(suite._beforeAll)) {
-    cleanArrReferences(suite._beforeAll);
-  }
-
-  if (isArray(suite._beforeEach)) {
-    cleanArrReferences(suite._beforeEach);
-  }
-
-  if (isArray(suite._afterAll)) {
-    cleanArrReferences(suite._afterAll);
-  }
-
-  if (isArray(suite._afterEach)) {
-    cleanArrReferences(suite._afterEach);
-  }
-
-  for (var i = 0; i < suite.tests.length; i++) {
-    delete suite.tests[i].fn;
-  }
-}
-
 /**
  * Run the root suite and invoke `fn(failures)`
  * on completion.
  *
- * @param {Function} fn
- * @return {Runner} for chaining
- * @api public
- * @param {Function} fn
- * @return {Runner} Runner instance.
+ * @public
+ * @memberof Runner
+ * @param {Function} fn - Callback when finished
+ * @param {Object} [opts] - For subclasses
+ * @param {string[]} opts.files - Files to run
+ * @param {Options} opts.options - command-line options
+ * @returns {Runner} Runner instance.
  */
-Runner.prototype.run = function (fn) {
-  var self = this;
+Runner.prototype.run = function (fn, opts = {}) {
   var rootSuite = this.suite;
+  var options = opts.options || {};
 
-  // If there is an `only` filter
-  if (this.hasOnly) {
-    filterOnly(rootSuite);
-  }
-
+  debug('run(): got options: %O', options);
   fn = fn || function () {};
 
-  function uncaught (err) {
-    self.uncaught(err);
-  }
+  const end = () => {
+    if (!this.total && this._opts.failZero) this.failures = 1;
 
-  function start () {
-    self.started = true;
-    self.emit('start');
-    self.runSuite(rootSuite, function () {
-      debug('finished running');
-      self.emit('end');
-    });
-  }
+    debug('run(): root suite completed; emitting %s', constants.EVENT_RUN_END);
+    this.emit(constants.EVENT_RUN_END);
+  };
 
-  debug('start');
+  const begin = () => {
+    debug('run(): emitting %s', constants.EVENT_RUN_BEGIN);
+    this.emit(constants.EVENT_RUN_BEGIN);
+    debug('run(): emitted %s', constants.EVENT_RUN_BEGIN);
 
-  // references cleanup to avoid memory leaks
-  this.on('suite end', cleanSuiteReferences);
+    this.runSuite(rootSuite, end);
+  };
 
-  // callback
-  this.on('end', function () {
-    if (self.forbidOnly && self.hasOnly) {
-      self.failures += self.stats.tests;
+  const prepare = () => {
+    debug('run(): starting');
+    // If there is an `only` filter
+    if (rootSuite.hasOnly()) {
+      rootSuite.filterOnly();
+      debug('run(): filtered exclusive Runnables');
     }
-    if (self.forbidPending) {
-      self.failures += self.stats.pending;
+    this.state = constants.STATE_RUNNING;
+    if (this._opts.delay) {
+      this.emit(constants.EVENT_DELAY_END);
+      debug('run(): "delay" ended');
     }
-    debug('end');
-    process.removeListener('uncaughtException', uncaught);
-    fn(self.failures);
+
+    return begin();
+  };
+
+  // references cleanup to avoid memory leaks
+  if (this._opts.cleanReferencesAfterRun) {
+    this.on(constants.EVENT_SUITE_END, suite => {
+      suite.cleanReferences();
+    });
+  }
+
+  // callback
+  this.on(constants.EVENT_RUN_END, function () {
+    this.state = constants.STATE_STOPPED;
+    debug('run(): emitted %s', constants.EVENT_RUN_END);
+    fn(this.failures);
   });
 
-  // uncaught exception
-  process.on('uncaughtException', uncaught);
+  this._removeEventListener(process, 'uncaughtException', this.uncaught);
+  this._removeEventListener(process, 'unhandledRejection', this.unhandled);
+  this._addEventListener(process, 'uncaughtException', this.uncaught);
+  this._addEventListener(process, 'unhandledRejection', this.unhandled);
 
-  if (this._delay) {
+  if (this._opts.delay) {
     // for reporters, I guess.
     // might be nice to debounce some dots while we wait.
-    this.emit('waiting', rootSuite);
-    rootSuite.once('run', start);
+    this.emit(constants.EVENT_DELAY_BEGIN, rootSuite);
+    rootSuite.once(EVENT_ROOT_SUITE_RUN, prepare);
+    debug('run(): waiting for green light due to --delay');
   } else {
-    start();
+    Runner.immediately(prepare);
   }
 
   return this;
 };
 
+/**
+ * Toggle partial object linking behavior; used for building object references from
+ * unique ID's. Does nothing in serial mode, because the object references already exist.
+ * Subclasses can implement this (e.g., `ParallelBufferedRunner`)
+ * @abstract
+ * @param {boolean} [value] - If `true`, enable partial object linking, otherwise disable
+ * @returns {Runner}
+ * @chainable
+ * @public
+ * @example
+ * // this reporter needs proper object references when run in parallel mode
+ * class MyReporter() {
+ *   constructor(runner) {
+ *     this.runner.linkPartialObjects(true)
+ *       .on(EVENT_SUITE_BEGIN, suite => {
+           // this Suite may be the same object...
+ *       })
+ *       .on(EVENT_TEST_BEGIN, test => {
+ *         // ...as the `test.parent` property
+ *       });
+ *   }
+ * }
+ */
+Runner.prototype.linkPartialObjects = function (value) {
+  return this;
+};
+
+/*
+ * Like {@link Runner#run}, but does not accept a callback and returns a `Promise` instead of a `Runner`.
+ * This function cannot reject; an `unhandledRejection` event will bubble up to the `process` object instead.
+ * @public
+ * @memberof Runner
+ * @param {Object} [opts] - Options for {@link Runner#run}
+ * @returns {Promise<number>} Failure count
+ */
+Runner.prototype.runAsync = async function runAsync(opts = {}) {
+  return new Promise(resolve => {
+    this.run(resolve, opts);
+  });
+};
+
 /**
  * Cleanly abort execution.
  *
- * @api public
+ * @memberof Runner
+ * @public
  * @return {Runner} Runner instance.
  */
 Runner.prototype.abort = function () {
-  debug('aborting');
+  debug('abort(): aborting');
   this._abort = true;
 
   return this;
 };
 
 /**
- * Filter suites based on `isOnly` logic.
+ * Returns `true` if Mocha is running in parallel mode.  For reporters.
  *
- * @param {Array} suite
- * @returns {Boolean}
- * @api private
+ * Subclasses should return an appropriate value.
+ * @public
+ * @returns {false}
  */
-function filterOnly (suite) {
-  if (suite._onlyTests.length) {
-    // If the suite contains `only` tests, run those and ignore any nested suites.
-    suite.tests = suite._onlyTests;
-    suite.suites = [];
-  } else {
-    // Otherwise, do not run any of the tests in this suite.
-    suite.tests = [];
-    utils.forEach(suite._onlySuites, function (onlySuite) {
-      // If there are other `only` tests/suites nested in the current `only` suite, then filter that `only` suite.
-      // Otherwise, all of the tests on this `only` suite should be run, so don't filter it.
-      if (hasOnly(onlySuite)) {
-        filterOnly(onlySuite);
-      }
-    });
-    // Run the `only` suites, as well as any other suites that have `only` tests/suites as descendants.
-    suite.suites = filter(suite.suites, function (childSuite) {
-      return indexOf(suite._onlySuites, childSuite) !== -1 || filterOnly(childSuite);
-    });
-  }
-  // Keep the suite only if there is something to run
-  return suite.tests.length || suite.suites.length;
-}
+Runner.prototype.isParallelMode = function isParallelMode() {
+  return false;
+};
 
 /**
- * Determines whether a suite has an `only` test or suite as a descendant.
- *
- * @param {Array} suite
- * @returns {Boolean}
- * @api private
+ * Configures an alternate reporter for worker processes to use. Subclasses
+ * using worker processes should implement this.
+ * @public
+ * @param {string} path - Absolute path to alternate reporter for worker processes to use
+ * @returns {Runner}
+ * @throws When in serial mode
+ * @chainable
+ * @abstract
  */
-function hasOnly (suite) {
-  return suite._onlyTests.length || suite._onlySuites.length || some(suite.suites, hasOnly);
-}
+Runner.prototype.workerReporter = function () {
+  throw createUnsupportedError('workerReporter() not supported in serial mode');
+};
 
 /**
  * Filter leaks with the given globals flagged as `ok`.
  *
- * @api private
+ * @private
  * @param {Array} ok
  * @param {Array} globals
  * @return {Array}
  */
-function filterLeaks (ok, globals) {
-  return filter(globals, function (key) {
+function filterLeaks(ok, globals) {
+  return globals.filter(function (key) {
     // Firefox and Chrome exposes iframes as index inside the window object
     if (/^\d+/.test(key)) {
       return false;
@@ -919,13 +1203,13 @@ function filterLeaks (ok, globals) {
     // in firefox
     // if runner runs in an iframe, this iframe's window.getInterface method
     // not init at first it is assigned in some seconds
-    if (global.navigator && (/^getInterface/).test(key)) {
+    if (global.navigator && /^getInterface/.test(key)) {
       return false;
     }
 
     // an iframe could be approached by window[iframeIndex]
     // in ie6,7,8 and opera, iframeIndex is enumerable, this could cause leak
-    if (global.navigator && (/^\d+/).test(key)) {
+    if (global.navigator && /^\d+/.test(key)) {
       return false;
     }
 
@@ -934,7 +1218,7 @@ function filterLeaks (ok, globals) {
       return false;
     }
 
-    var matched = filter(ok, function (ok) {
+    var matched = ok.filter(function (ok) {
       if (~ok.indexOf('*')) {
         return key.indexOf(ok.split('*')[0]) === 0;
       }
@@ -945,24 +1229,39 @@ function filterLeaks (ok, globals) {
 }
 
 /**
- * Array of globals dependent on the environment.
+ * Check if argument is an instance of Error object or a duck-typed equivalent.
  *
- * @return {Array}
- * @api private
+ * @private
+ * @param {Object} err - object to check
+ * @param {string} err.message - error message
+ * @returns {boolean}
  */
-function extraGlobals () {
-  if (typeof process === 'object' && typeof process.version === 'string') {
-    var parts = process.version.split('.');
-    var nodeVersion = utils.reduce(parts, function (a, v) {
-      return a << 8 | v;
-    });
+function isError(err) {
+  return err instanceof Error || (err && typeof err.message === 'string');
+}
 
-    // 'errno' was renamed to process._errno in v0.9.11.
+/**
+ *
+ * Converts thrown non-extensible type into proper Error.
+ *
+ * @private
+ * @param {*} thrown - Non-extensible type thrown by code
+ * @return {Error}
+ */
+function thrown2Error(err) {
+  return new Error(
+    `the ${utils.canonicalType(err)} ${stringify(
+      err
+    )} was thrown, throw an Error :)`
+  );
+}
 
-    if (nodeVersion < 0x00090B) {
-      return ['errno'];
-    }
-  }
+Runner.constants = constants;
 
-  return [];
-}
+/**
+ * Node.js' `EventEmitter`
+ * @external EventEmitter
+ * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter}
+ */
+
+module.exports = Runner;