mocha 5.1.1 → 6.0.0

package/lib/runner.js

@@ -1,26 +1,36 @@
 'use strict';
 
-/**
- * @module Runner
- */
 /**
  * Module dependencies.
  */
+var util = require('util');
 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 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 dQuote = utils.dQuote;
+var ngettext = utils.ngettext;
+var sQuote = utils.sQuote;
 var stackFilter = utils.stackTraceFilter();
 var stringify = utils.stringify;
 var type = utils.type;
-var undefinedError = utils.undefinedError;
+var createInvalidExceptionError = require('./errors')
+  .createInvalidExceptionError;
 
 /**
  * Non-enumerable globals.
+ * @readonly
  */
-
 var globals = [
   'setTimeout',
   'clearTimeout',
@@ -32,38 +42,89 @@ var globals = [
   'clearImmediate'
 ];
 
-/**
- * Expose `Runner`.
- */
+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'
+  }
+);
 
 module.exports = Runner;
 
 /**
- * Initialize a `Runner` for the given `suite`. Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
- *
- * 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
+ * Initialize a `Runner` at the Root {@link Suite}, which represents a hierarchy of {@link Suite|Suites} and {@link Test|Tests}.
  *
- * @memberof Mocha
+ * @extends external:EventEmitter
  * @public
  * @class
- * @api public
- * @param {Suite} [suite] Root suite
+ * @param {Suite} suite Root suite
  * @param {boolean} [delay] Whether or not to delay execution of root suite
  * until ready.
  */
-function Runner (suite, delay) {
+function Runner(suite, delay) {
   var self = this;
   this._globals = [];
   this._abort = false;
@@ -72,10 +133,10 @@ function Runner (suite, delay) {
   this.started = false;
   this.total = suite.total();
   this.failures = 0;
-  this.on('test end', function (test) {
+  this.on(constants.EVENT_TEST_END, function(test) {
     self.checkGlobals(test);
   });
-  this.on('hook end', function (hook) {
+  this.on(constants.EVENT_HOOK_END, function(hook) {
     self.checkGlobals(hook);
   });
   this._defaultGrep = /.*/;
@@ -87,7 +148,7 @@ function Runner (suite, delay) {
  * Wrapper for setImmediate, process.nextTick, or browser polyfill.
  *
  * @param {Function} fn
- * @api private
+ * @private
  */
 Runner.immediately = global.setImmediate || process.nextTick;
 
@@ -100,14 +161,13 @@ inherits(Runner, EventEmitter);
  * Run tests with full titles matching `re`. Updates runner.total
  * with number of tests matched.
  *
- * @api public
  * @public
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @param {RegExp} re
  * @param {boolean} invert
  * @return {Runner} Runner instance.
  */
-Runner.prototype.grep = function (re, invert) {
+Runner.prototype.grep = function(re, invert) {
   debug('grep %s', re);
   this._grep = re;
   this._invert = invert;
@@ -119,17 +179,16 @@ Runner.prototype.grep = function (re, invert) {
  * Returns the number of tests matching the grep search for the
  * given suite.
  *
- * @memberof Mocha.Runner
- * @api public
+ * @memberof Runner
  * @public
  * @param {Suite} suite
  * @return {number}
  */
-Runner.prototype.grepTotal = function (suite) {
+Runner.prototype.grepTotal = function(suite) {
   var self = this;
   var total = 0;
 
-  suite.eachTest(function (test) {
+  suite.eachTest(function(test) {
     var match = self._grep.test(test.fullTitle());
     if (self._invert) {
       match = !match;
@@ -146,9 +205,9 @@ Runner.prototype.grepTotal = function (suite) {
  * Return a list of global properties.
  *
  * @return {Array}
- * @api private
+ * @private
  */
-Runner.prototype.globalProps = function () {
+Runner.prototype.globalProps = function() {
   var props = Object.keys(global);
 
   // non-enumerables
@@ -165,13 +224,12 @@ Runner.prototype.globalProps = function () {
 /**
  * Allow the given `arr` of globals.
  *
- * @api public
  * @public
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @param {Array} arr
  * @return {Runner} Runner instance.
  */
-Runner.prototype.globals = function (arr) {
+Runner.prototype.globals = function(arr) {
   if (!arguments.length) {
     return this._globals;
   }
@@ -183,9 +241,9 @@ Runner.prototype.globals = function (arr) {
 /**
  * Check for global variable leaks.
  *
- * @api private
+ * @private
  */
-Runner.prototype.checkGlobals = function (test) {
+Runner.prototype.checkGlobals = function(test) {
   if (this.ignoreLeaks) {
     return;
   }
@@ -206,48 +264,52 @@ 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 format = ngettext(
+      leaks.length,
+      'global leak detected: %s',
+      'global leaks detected: %s'
+    );
+    var error = new Error(util.format(format, leaks.map(sQuote).join(', ')));
+    this.fail(test, error);
   }
 };
 
 /**
  * Fail the given `test`.
  *
- * @api private
+ * @private
  * @param {Test} test
  * @param {Error} err
  */
-Runner.prototype.fail = function (test, err) {
+Runner.prototype.fail = function(test, err) {
   if (test.isPending()) {
     return;
   }
 
   ++this.failures;
-  test.state = 'failed';
+  test.state = STATE_FAILED;
 
-  if (!(err instanceof Error || (err && typeof err.message === 'string'))) {
-    err = new Error('the ' + type(err) + ' ' + stringify(err) + ' was thrown, throw an Error :)');
+  if (!isError(err)) {
+    err = thrown2Error(err);
   }
 
   try {
-    err.stack = (this.fullStackTrace || !err.stack)
-      ? err.stack
-      : stackFilter(err.stack);
-  } catch (ignored) {
+    err.stack =
+      this.fullStackTrace || !err.stack ? err.stack : stackFilter(err.stack);
+  } catch (ignore) {
     // some environments do not take kindly to monkeying with the stack
   }
 
-  this.emit('fail', 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, then exit
+ * - 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
@@ -259,65 +321,80 @@ Runner.prototype.fail = function (test, err) {
  *   suite and subsuites, but executes other `after each`
  *   hooks
  *
- * @api private
+ * @private
  * @param {Hook} hook
  * @param {Error} err
  */
-Runner.prototype.failHook = function (hook, err) {
+Runner.prototype.failHook = function(hook, err) {
+  hook.originalTitle = hook.originalTitle || hook.title;
   if (hook.ctx && hook.ctx.currentTest) {
-    hook.originalTitle = hook.originalTitle || hook.title;
-    hook.title = hook.originalTitle + ' for "' + hook.ctx.currentTest.title + '"';
+    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);
   }
 
-  if (this.suite.bail()) {
-    this.emit('end');
-  }
   this.fail(hook, err);
 };
 
 /**
  * Run hook `name` callbacks and then invoke `fn()`.
  *
- * @api private
+ * @private
  * @param {string} name
  * @param {Function} fn
  */
 
-Runner.prototype.hook = function (name, fn) {
+Runner.prototype.hook = function(name, 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 === 'beforeAll') {
+      hook.ctx.currentTest = hook.parent.tests[0];
+    } else if (name === 'afterAll') {
+      hook.ctx.currentTest = hook.parent.tests[hook.parent.tests.length - 1];
+    } else {
+      hook.ctx.currentTest = self.test;
+    }
 
-    self.emit('hook', hook);
+    self.emit(constants.EVENT_HOOK_BEGIN, hook);
 
     if (!hook.listeners('error').length) {
-      hook.on('error', function (err) {
+      hook.on('error', function(err) {
         self.failHook(hook, err);
       });
     }
 
-    hook.run(function (err) {
+    hook.run(function(err) {
       var testError = hook.error();
       if (testError) {
         self.fail(self.test, testError);
       }
       if (err) {
         if (err instanceof Pending) {
-          if (name === 'beforeEach' || name === 'afterEach') {
+          if (name === HOOK_TYPE_BEFORE_EACH || name === HOOK_TYPE_AFTER_EACH) {
             self.test.pending = true;
           } else {
-            suite.tests.forEach(function (test) {
+            suite.tests.forEach(function(test) {
               test.pending = true;
             });
+            suite.suites.forEach(function(suite) {
+              suite.pending = true;
+            });
             // a pending hook won't be executed twice.
             hook.pending = true;
           }
@@ -328,13 +405,13 @@ Runner.prototype.hook = function (name, fn) {
           return fn(err);
         }
       }
-      self.emit('hook end', hook);
+      self.emit(constants.EVENT_HOOK_END, hook);
       delete hook.ctx.currentTest;
       next(++i);
     });
   }
 
-  Runner.immediately(function () {
+  Runner.immediately(function() {
     next(0);
   });
 };
@@ -343,16 +420,16 @@ 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
  */
-Runner.prototype.hooks = function (name, suites, fn) {
+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) {
@@ -360,7 +437,7 @@ Runner.prototype.hooks = function (name, suites, fn) {
       return fn();
     }
 
-    self.hook(name, function (err) {
+    self.hook(name, function(err) {
       if (err) {
         var errSuite = self.suite;
         self.suite = orig;
@@ -379,9 +456,9 @@ Runner.prototype.hooks = function (name, suites, fn) {
  *
  * @param {String} name
  * @param {Function} fn
- * @api private
+ * @private
  */
-Runner.prototype.hookUp = function (name, fn) {
+Runner.prototype.hookUp = function(name, fn) {
   var suites = [this.suite].concat(this.parents()).reverse();
   this.hooks(name, suites, fn);
 };
@@ -391,9 +468,9 @@ Runner.prototype.hookUp = function (name, fn) {
  *
  * @param {String} name
  * @param {Function} fn
- * @api private
+ * @private
  */
-Runner.prototype.hookDown = function (name, fn) {
+Runner.prototype.hookDown = function(name, fn) {
   var suites = [this.suite].concat(this.parents());
   this.hooks(name, suites, fn);
 };
@@ -403,9 +480,9 @@ Runner.prototype.hookDown = function (name, fn) {
  * closest to furthest.
  *
  * @return {Array}
- * @api private
+ * @private
  */
-Runner.prototype.parents = function () {
+Runner.prototype.parents = function() {
   var suite = this.suite;
   var suites = [];
   while (suite.parent) {
@@ -419,23 +496,25 @@ Runner.prototype.parents = function () {
  * Run the current test and callback `fn(err)`.
  *
  * @param {Function} fn
- * @api private
+ * @private
  */
-Runner.prototype.runTest = function (fn) {
+Runner.prototype.runTest = function(fn) {
   var self = this;
   var test = this.test;
 
   if (!test) {
     return;
   }
-  if (this.forbidOnly && hasOnly(this.parents().reverse()[0] || this.suite)) {
+
+  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) {
+  test.on('error', function(err) {
     self.fail(test, err);
   });
   if (this.allowUncaught) {
@@ -452,16 +531,16 @@ 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
  */
-Runner.prototype.runTests = function (suite, fn) {
+Runner.prototype.runTests = function(suite, fn) {
   var self = this;
   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;
 
@@ -471,7 +550,7 @@ Runner.prototype.runTests = function (suite, fn) {
 
     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) {
@@ -487,10 +566,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) {
@@ -537,31 +616,31 @@ Runner.prototype.runTests = function (suite, fn) {
         self.fail(test, new Error('Pending test forbidden'));
         delete test.isPending;
       } else {
-        self.emit('pending', test);
+        self.emit(constants.EVENT_TEST_PENDING, test);
       }
-      self.emit('test end', 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) {
       if (test.isPending()) {
         if (self.forbidPending) {
           test.isPending = alwaysFalse;
           self.fail(test, new Error('Pending test forbidden'));
           delete test.isPending;
         } else {
-          self.emit('pending', test);
+          self.emit(constants.EVENT_TEST_PENDING, test);
         }
-        self.emit('test end', test);
+        self.emit(constants.EVENT_TEST_END, test);
         return next();
       }
       if (err) {
         return hookErr(err, errSuite, false);
       }
       self.currentRunnable = self.test;
-      self.runTest(function (err) {
+      self.runTest(function(err) {
         test = self.test;
         if (err) {
           var retry = test.currentRetry();
@@ -569,31 +648,33 @@ Runner.prototype.runTests = function (suite, fn) {
             self.fail(test, new Error('Pending test forbidden'));
           } else if (err instanceof Pending) {
             test.pending = true;
-            self.emit('pending', test);
+            self.emit(constants.EVENT_TEST_PENDING, test);
           } else 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);
+          self.emit(constants.EVENT_TEST_END, test);
 
           if (err instanceof Pending) {
             return next();
           }
 
-          return self.hookUp('afterEach', next);
+          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);
       });
     });
   }
@@ -603,18 +684,18 @@ Runner.prototype.runTests = function (suite, fn) {
   next();
 };
 
-function alwaysFalse () {
+function alwaysFalse() {
   return false;
 }
 
 /**
  * Run the given `suite` and invoke the callback `fn()` when complete.
  *
- * @api private
+ * @private
  * @param {Suite} suite
  * @param {Function} fn
  */
-Runner.prototype.runSuite = function (suite, fn) {
+Runner.prototype.runSuite = function(suite, fn) {
   var i = 0;
   var self = this;
   var total = this.grepTotal(suite);
@@ -626,9 +707,9 @@ Runner.prototype.runSuite = function (suite, fn) {
     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) {
@@ -654,7 +735,7 @@ Runner.prototype.runSuite = function (suite, fn) {
     // huge recursive loop and thus a maximum call stack error.
     // See comment in `this.runTests()` for more information.
     if (self._grep !== self._defaultGrep) {
-      Runner.immediately(function () {
+      Runner.immediately(function() {
         self.runSuite(curr, next);
       });
     } else {
@@ -662,7 +743,7 @@ Runner.prototype.runSuite = function (suite, fn) {
     }
   }
 
-  function done (errSuite) {
+  function done(errSuite) {
     self.suite = suite;
     self.nextSuite = next;
 
@@ -676,8 +757,8 @@ Runner.prototype.runSuite = function (suite, fn) {
       // remove reference to test
       delete self.test;
 
-      self.hook('afterAll', function () {
-        self.emit('suite end', suite);
+      self.hook(HOOK_TYPE_AFTER_ALL, function() {
+        self.emit(constants.EVENT_SUITE_END, suite);
         fn(errSuite);
       });
     }
@@ -685,7 +766,7 @@ Runner.prototype.runSuite = function (suite, fn) {
 
   this.nextSuite = next;
 
-  this.hook('beforeAll', function (err) {
+  this.hook(HOOK_TYPE_BEFORE_ALL, function(err) {
     if (err) {
       return done();
     }
@@ -697,16 +778,21 @@ Runner.prototype.runSuite = function (suite, fn) {
  * Handle uncaught exceptions.
  *
  * @param {Error} err
- * @api private
+ * @private
  */
-Runner.prototype.uncaught = function (err) {
+Runner.prototype.uncaught = function(err) {
   if (err) {
-    debug('uncaught exception %s', err === (function () {
-      return this;
-    }.call(err)) ? (err.message || err) : err);
+    debug('uncaught 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);
   }
   err.uncaught = true;
 
@@ -720,9 +806,9 @@ Runner.prototype.uncaught = function (err) {
       this.fail(runnable, err);
     } else {
       // Can't recover from this failure
-      this.emit('start');
+      this.emit(constants.EVENT_RUN_BEGIN);
       this.fail(runnable, err);
-      this.emit('end');
+      this.emit(constants.EVENT_RUN_END);
     }
 
     return;
@@ -742,14 +828,17 @@ Runner.prototype.uncaught = function (err) {
   this.fail(runnable, err);
   if (!alreadyPassed) {
     // recover from test
-    if (runnable.type === 'test') {
-      this.emit('test end', runnable);
-      this.hookUp('afterEach', this.next);
+    if (runnable.type === constants.EVENT_TEST_BEGIN) {
+      this.emit(constants.EVENT_TEST_END, runnable);
+      this.hookUp(HOOK_TYPE_AFTER_EACH, this.next);
       return;
     }
+    debug(runnable);
 
     // recover from hooks
     var errSuite = this.suite;
+
+    // XXX how about a less awful way to determine this?
     // if hook failure is in afterEach block
     if (runnable.fullTitle().indexOf('after each') > -1) {
       return this.hookErr(err, errSuite, true);
@@ -763,88 +852,55 @@ Runner.prototype.uncaught = function (err) {
   }
 
   // bail
-  this.emit('end');
+  this.emit(constants.EVENT_RUN_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 (Array.isArray(suite._beforeAll)) {
-    cleanArrReferences(suite._beforeAll);
-  }
-
-  if (Array.isArray(suite._beforeEach)) {
-    cleanArrReferences(suite._beforeEach);
-  }
-
-  if (Array.isArray(suite._afterAll)) {
-    cleanArrReferences(suite._afterAll);
-  }
-
-  if (Array.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.
  *
- * @api public
  * @public
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @param {Function} fn
  * @return {Runner} Runner instance.
  */
-Runner.prototype.run = function (fn) {
+Runner.prototype.run = function(fn) {
   var self = this;
   var rootSuite = this.suite;
 
-  fn = fn || function () {};
+  fn = fn || function() {};
 
-  function uncaught (err) {
+  function uncaught(err) {
     self.uncaught(err);
   }
 
-  function start () {
+  function start() {
     // If there is an `only` filter
-    if (hasOnly(rootSuite)) {
-      filterOnly(rootSuite);
+    if (rootSuite.hasOnly()) {
+      rootSuite.filterOnly();
     }
     self.started = true;
-    self.emit('start');
-    self.runSuite(rootSuite, function () {
+    if (self._delay) {
+      self.emit(constants.EVENT_DELAY_END);
+    }
+    self.emit(constants.EVENT_RUN_BEGIN);
+
+    self.runSuite(rootSuite, function() {
       debug('finished running');
-      self.emit('end');
+      self.emit(constants.EVENT_RUN_END);
     });
   }
 
-  debug('start');
+  debug(constants.EVENT_RUN_BEGIN);
 
   // references cleanup to avoid memory leaks
-  this.on('suite end', cleanSuiteReferences);
+  this.on(constants.EVENT_SUITE_END, function(suite) {
+    suite.cleanReferences();
+  });
 
   // callback
-  this.on('end', function () {
-    debug('end');
+  this.on(constants.EVENT_RUN_END, function() {
+    debug(constants.EVENT_RUN_END);
     process.removeListener('uncaughtException', uncaught);
     fn(self.failures);
   });
@@ -855,8 +911,8 @@ Runner.prototype.run = function (fn) {
   if (this._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, start);
   } else {
     start();
   }
@@ -867,70 +923,27 @@ Runner.prototype.run = function (fn) {
 /**
  * Cleanly abort execution.
  *
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @public
- * @api public
  * @return {Runner} Runner instance.
  */
-Runner.prototype.abort = function () {
+Runner.prototype.abort = function() {
   debug('aborting');
   this._abort = true;
 
   return this;
 };
 
-/**
- * Filter suites based on `isOnly` logic.
- *
- * @param {Array} suite
- * @returns {Boolean}
- * @api private
- */
-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 = [];
-    suite._onlySuites.forEach(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 = suite.suites.filter(function (childSuite) {
-      return suite._onlySuites.indexOf(childSuite) !== -1 || filterOnly(childSuite);
-    });
-  }
-  // Keep the suite only if there is something to run
-  return suite.tests.length || suite.suites.length;
-}
-
-/**
- * Determines whether a suite has an `only` test or suite as a descendant.
- *
- * @param {Array} suite
- * @returns {Boolean}
- * @api private
- */
-function hasOnly (suite) {
-  return suite._onlyTests.length || suite._onlySuites.length || suite.suites.some(hasOnly);
-}
-
 /**
  * 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 globals.filter(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;
@@ -939,13 +952,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;
     }
 
@@ -954,7 +967,7 @@ function filterLeaks (ok, globals) {
       return false;
     }
 
-    var matched = ok.filter(function (ok) {
+    var matched = ok.filter(function(ok) {
       if (~ok.indexOf('*')) {
         return key.indexOf(ok.split('*')[0]) === 0;
       }
@@ -964,25 +977,60 @@ function filterLeaks (ok, globals) {
   });
 }
 
+/**
+ * Check if argument is an instance of Error object or a duck-typed equivalent.
+ *
+ * @private
+ * @param {Object} err - object to check
+ * @param {string} err.message - error message
+ * @returns {boolean}
+ */
+function isError(err) {
+  return err instanceof Error || (err && typeof err.message === 'string');
+}
+
+/**
+ *
+ * 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 ' + type(err) + ' ' + stringify(err) + ' was thrown, throw an Error :)'
+  );
+}
+
 /**
  * Array of globals dependent on the environment.
  *
  * @return {Array}
- * @api private
+ * @deprecated
+ * @todo remove; long since unsupported
+ * @private
  */
-function extraGlobals () {
+function extraGlobals() {
   if (typeof process === 'object' && typeof process.version === 'string') {
     var parts = process.version.split('.');
-    var nodeVersion = parts.reduce(function (a, v) {
-      return a << 8 | v;
+    var nodeVersion = parts.reduce(function(a, v) {
+      return (a << 8) | v;
     });
 
     // 'errno' was renamed to process._errno in v0.9.11.
-
-    if (nodeVersion < 0x00090B) {
+    if (nodeVersion < 0x00090b) {
       return ['errno'];
     }
   }
 
   return [];
 }
+
+Runner.constants = constants;
+
+/**
+ * Node.js' `EventEmitter`
+ * @external EventEmitter
+ * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter}
+ */