mocha 9.1.2

package/lib/runner.js

@@ -0,0 +1,1269 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ * @private
+ */
+var EventEmitter = require('events').EventEmitter;
+var Pending = require('./pending');
+var utils = require('./utils');
+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 STATE_PENDING = Runnable.constants.STATE_PENDING;
+var stackFilter = utils.stackTraceFilter();
+var stringify = utils.stringify;
+
+const {
+  createInvalidExceptionError,
+  createUnsupportedError,
+  createFatalError,
+  isMochaError,
+  constants: errorConstants
+} = require('./errors');
+
+/**
+ * Non-enumerable globals.
+ * @private
+ * @readonly
+ */
+var globals = [
+  'setTimeout',
+  'clearTimeout',
+  'setInterval',
+  'clearInterval',
+  'XMLHttpRequest',
+  'Date',
+  'setImmediate',
+  'clearImmediate'
+];
+
+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|boolean} [opts] - Options. If `boolean` (deprecated), 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.
+   * @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} [options.failZero] - Whether to fail test run if zero tests encountered.
+   */
+  constructor(suite, opts) {
+    super();
+    if (opts === undefined) {
+      opts = {};
+    }
+    if (typeof opts === 'boolean') {
+      // TODO: remove this
+      require('./errors').deprecate(
+        '"Runner(suite: Suite, delay: boolean)" is deprecated. Use "Runner(suite: Suite, {delay: boolean})" instead.'
+      );
+      this._delay = opts;
+      opts = {};
+    } else {
+      this._delay = opts.delay;
+    }
+    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
+ * @private
+ */
+Runner.immediately = global.setImmediate || process.nextTick;
+
+/**
+ * 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
+ */
+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.
+ *
+ * @public
+ * @memberof Runner
+ * @param {RegExp} re
+ * @param {boolean} invert
+ * @return {Runner} Runner instance.
+ */
+Runner.prototype.grep = function(re, invert) {
+  debug('grep(): setting to %s', re);
+  this._grep = re;
+  this._invert = invert;
+  this.total = this.grepTotal(this.suite);
+  return this;
+};
+
+/**
+ * Returns the number of tests matching the grep search for the
+ * given suite.
+ *
+ * @memberof Runner
+ * @public
+ * @param {Suite} suite
+ * @return {number}
+ */
+Runner.prototype.grepTotal = function(suite) {
+  var self = this;
+  var total = 0;
+
+  suite.eachTest(function(test) {
+    var match = self._grep.test(test.fullTitle());
+    if (self._invert) {
+      match = !match;
+    }
+    if (match) {
+      total++;
+    }
+  });
+
+  return total;
+};
+
+/**
+ * Return a list of global properties.
+ *
+ * @return {Array}
+ * @private
+ */
+Runner.prototype.globalProps = function() {
+  var props = Object.keys(global);
+
+  // non-enumerables
+  for (var i = 0; i < globals.length; ++i) {
+    if (~props.indexOf(globals[i])) {
+      continue;
+    }
+    props.push(globals[i]);
+  }
+
+  return props;
+};
+
+/**
+ * Allow the given `arr` of globals.
+ *
+ * @public
+ * @memberof Runner
+ * @param {Array} arr
+ * @return {Runner} Runner instance.
+ */
+Runner.prototype.globals = function(arr) {
+  if (!arguments.length) {
+    return this._globals;
+  }
+  debug('globals(): setting to %O', arr);
+  this._globals = this._globals.concat(arr);
+  return this;
+};
+
+/**
+ * Check for global variable leaks.
+ *
+ * @private
+ */
+Runner.prototype.checkGlobals = function(test) {
+  if (!this.checkLeaks) {
+    return;
+  }
+  var ok = this._globals;
+
+  var globals = this.globalProps();
+  var leaks;
+
+  if (test) {
+    ok = ok.concat(test._allowedGlobals || []);
+  }
+
+  if (this.prevGlobalsLength === globals.length) {
+    return;
+  }
+  this.prevGlobalsLength = globals.length;
+
+  leaks = filterLeaks(ok, globals);
+  this._globals = this._globals.concat(leaks);
+
+  if (leaks.length) {
+    var msg = `global leak(s) detected: ${leaks.map(e => `'${e}'`).join(', ')}`;
+    this.fail(test, new Error(msg));
+  }
+};
+
+/**
+ * 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 {Runnable} test
+ * @param {Error} err
+ * @param {boolean} [force=false] - Whether to fail a pending test.
+ */
+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);
+  }
+
+  try {
+    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(constants.EVENT_TEST_FAIL, test, err);
+};
+
+/**
+ * Run hook `name` callbacks and then invoke `fn()`.
+ *
+ * @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.getHooks(name);
+  var self = this;
+
+  function next(i) {
+    var hook = hooks[i];
+    if (!hook) {
+      return fn();
+    }
+    self.currentRunnable = hook;
+
+    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);
+
+    hook.allowUncaught = self.allowUncaught;
+
+    self.emit(constants.EVENT_HOOK_BEGIN, hook);
+
+    if (!hook.listeners('error').length) {
+      self._addEventListener(hook, 'error', function(err) {
+        self.fail(hook, err);
+      });
+    }
+
+    hook.run(function cbHookRun(err) {
+      var testError = hook.error();
+      if (testError) {
+        self.fail(self.test, testError);
+      }
+      // 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 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 {
+          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(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() {
+    next(0);
+  });
+};
+
+/**
+ * Run hook `name` for the given array of `suites`
+ * in order, and callback `fn(err, errSuite)`.
+ *
+ * @private
+ * @param {string} name
+ * @param {Array} suites
+ * @param {Function} fn
+ */
+Runner.prototype.hooks = function(name, suites, fn) {
+  var self = this;
+  var orig = this.suite;
+
+  function next(suite) {
+    self.suite = suite;
+
+    if (!suite) {
+      self.suite = orig;
+      return fn();
+    }
+
+    self.hook(name, function(err) {
+      if (err) {
+        var errSuite = self.suite;
+        self.suite = orig;
+        return fn(err, errSuite);
+      }
+
+      next(suites.pop());
+    });
+  }
+
+  next(suites.pop());
+};
+
+/**
+ * Run 'afterEach' hooks from bottom up.
+ *
+ * @param {String} name
+ * @param {Function} fn
+ * @private
+ */
+Runner.prototype.hookUp = function(name, fn) {
+  var suites = [this.suite].concat(this.parents()).reverse();
+  this.hooks(name, suites, fn);
+};
+
+/**
+ * Run 'beforeEach' hooks from top level down.
+ *
+ * @param {String} name
+ * @param {Function} fn
+ * @private
+ */
+Runner.prototype.hookDown = function(name, fn) {
+  var suites = [this.suite].concat(this.parents());
+  this.hooks(name, suites, fn);
+};
+
+/**
+ * Return an array of parent Suites from
+ * closest to furthest.
+ *
+ * @return {Array}
+ * @private
+ */
+Runner.prototype.parents = function() {
+  var suite = this.suite;
+  var suites = [];
+  while (suite.parent) {
+    suite = suite.parent;
+    suites.push(suite);
+  }
+  return suites;
+};
+
+/**
+ * Run the current test and callback `fn(err)`.
+ *
+ * @param {Function} fn
+ * @private
+ */
+Runner.prototype.runTest = function(fn) {
+  if (this._opts.dryRun) return fn();
+
+  var self = this;
+  var test = this.test;
+
+  if (!test) {
+    return;
+  }
+
+  if (this.asyncOnly) {
+    test.asyncOnly = true;
+  }
+  this._addEventListener(test, 'error', function(err) {
+    self.fail(test, err);
+  });
+  if (this.allowUncaught) {
+    test.allowUncaught = true;
+    return test.run(fn);
+  }
+  try {
+    test.run(fn);
+  } catch (err) {
+    fn(err);
+  }
+};
+
+/**
+ * Run tests in the given `suite` and invoke the callback `fn()` when complete.
+ *
+ * @private
+ * @param {Suite} suite
+ * @param {Function} fn
+ */
+Runner.prototype.runTests = function(suite, fn) {
+  var self = this;
+  var tests = suite.tests.slice();
+  var test;
+
+  function hookErr(_, errSuite, after) {
+    // before/after Each hook for errSuite failed:
+    var orig = self.suite;
+
+    // for failed 'after each' hook start from errSuite parent,
+    // otherwise start from errSuite itself
+    self.suite = after ? errSuite.parent : errSuite;
+
+    if (self.suite) {
+      self.hookUp(HOOK_TYPE_AFTER_EACH, function(err2, errSuite2) {
+        self.suite = orig;
+        // some hooks may fail even now
+        if (err2) {
+          return hookErr(err2, errSuite2, true);
+        }
+        // report error suite
+        fn(errSuite);
+      });
+    } else {
+      // there is no need calling other 'after each' hooks
+      self.suite = orig;
+      fn(errSuite);
+    }
+  }
+
+  function next(err, errSuite) {
+    // if we bail after first err
+    if (self.failures && suite._bail) {
+      tests = [];
+    }
+
+    if (self._abort) {
+      return fn();
+    }
+
+    if (err) {
+      return hookErr(err, errSuite, true);
+    }
+
+    // next test
+    test = tests.shift();
+
+    // all done
+    if (!test) {
+      return fn();
+    }
+
+    // grep
+    var match = self._grep.test(test.fullTitle());
+    if (self._invert) {
+      match = !match;
+    }
+    if (!match) {
+      // Run immediately only if we have defined a grep. When we
+      // define a grep — It can cause maximum callstack error if
+      // the grep is doing a large recursive loop by neglecting
+      // all tests. The run immediately function also comes with
+      // a performance cost. So we don't want to run immediately
+      // if we run the whole test suite, because running the whole
+      // test suite don't do any immediate recursive loops. Thus,
+      // allowing a JS runtime to breathe.
+      if (self._grep !== self._defaultGrep) {
+        Runner.immediately(next);
+      } else {
+        next();
+      }
+      return;
+    }
+
+    // static skip, no hooks are executed
+    if (test.isPending()) {
+      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(constants.EVENT_TEST_BEGIN, (self.test = test));
+    self.hookDown(HOOK_TYPE_BEFORE_EACH, function(err, errSuite) {
+      // conditional skip within beforeEach
+      if (test.isPending()) {
+        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);
+      }
+      self.currentRunnable = self.test;
+      self.runTest(function(err) {
+        test = self.test;
+        // 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 (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(HOOK_TYPE_AFTER_EACH, next);
+          } else {
+            self.fail(test, err);
+          }
+          self.emit(constants.EVENT_TEST_END, test);
+          return self.hookUp(HOOK_TYPE_AFTER_EACH, 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);
+      });
+    });
+  }
+
+  this.next = next;
+  this.hookErr = hookErr;
+  next();
+};
+
+/**
+ * Run the given `suite` and invoke the callback `fn()` when complete.
+ *
+ * @private
+ * @param {Suite} suite
+ * @param {Function} fn
+ */
+Runner.prototype.runSuite = function(suite, fn) {
+  var i = 0;
+  var self = this;
+  var total = this.grepTotal(suite);
+
+  debug('runSuite(): running %s', suite.fullTitle());
+
+  if (!total || (self.failures && suite._bail)) {
+    debug('runSuite(): bailing');
+    return fn();
+  }
+
+  this.emit(constants.EVENT_SUITE_BEGIN, (this.suite = suite));
+
+  function next(errSuite) {
+    if (errSuite) {
+      // current suite failed on a hook from errSuite
+      if (errSuite === suite) {
+        // if errSuite is current suite
+        // continue to the next sibling suite
+        return done();
+      }
+      // errSuite is among the parents of current suite
+      // stop execution of errSuite and all sub-suites
+      return done(errSuite);
+    }
+
+    if (self._abort) {
+      return done();
+    }
+
+    var curr = suite.suites[i++];
+    if (!curr) {
+      return done();
+    }
+
+    // Avoid grep neglecting large number of tests causing a
+    // 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() {
+        self.runSuite(curr, next);
+      });
+    } else {
+      self.runSuite(curr, next);
+    }
+  }
+
+  function done(errSuite) {
+    self.suite = suite;
+    self.nextSuite = next;
+
+    // remove reference to test
+    delete self.test;
+
+    self.hook(HOOK_TYPE_AFTER_ALL, function() {
+      self.emit(constants.EVENT_SUITE_END, suite);
+      fn(errSuite);
+    });
+  }
+
+  this.nextSuite = next;
+
+  this.hook(HOOK_TYPE_BEFORE_ALL, function(err) {
+    if (err) {
+      return done();
+    }
+    self.runTests(suite, next);
+  });
+};
+
+/**
+ * Handle uncaught exceptions within runner.
+ *
+ * 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) {
+  // 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(): got truthy exception %O', err);
+  } else {
+    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;
+
+  var runnable = this.currentRunnable;
+
+  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.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);
+    }
+
+    return;
+  }
+
+  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
+    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('uncaught(): forcing Runnable to complete with Error');
+    return runnable.callback(err);
+  }
+};
+
+/**
+ * Run the root suite and invoke `fn(failures)`
+ * on completion.
+ *
+ * @public
+ * @memberof Runner
+ * @param {Function} fn - Callback when finished
+ * @param {{files: string[], options: Options}} [opts] - For subclasses
+ * @returns {Runner} Runner instance.
+ */
+Runner.prototype.run = function(fn, opts = {}) {
+  var rootSuite = this.suite;
+  var options = opts.options || {};
+
+  debug('run(): got options: %O', options);
+  fn = fn || function() {};
+
+  const end = () => {
+    if (!this.total && this._opts.failZero) this.failures = 1;
+
+    debug('run(): root suite completed; emitting %s', constants.EVENT_RUN_END);
+    this.emit(constants.EVENT_RUN_END);
+  };
+
+  const begin = () => {
+    debug('run(): emitting %s', constants.EVENT_RUN_BEGIN);
+    this.emit(constants.EVENT_RUN_BEGIN);
+    debug('run(): emitted %s', constants.EVENT_RUN_BEGIN);
+
+    this.runSuite(rootSuite, end);
+  };
+
+  const prepare = () => {
+    debug('run(): starting');
+    // If there is an `only` filter
+    if (rootSuite.hasOnly()) {
+      rootSuite.filterOnly();
+      debug('run(): filtered exclusive Runnables');
+    }
+    this.state = constants.STATE_RUNNING;
+    if (this._delay) {
+      this.emit(constants.EVENT_DELAY_END);
+      debug('run(): "delay" ended');
+    }
+
+    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);
+  });
+
+  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) {
+    // 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, prepare);
+    debug('run(): waiting for green light due to --delay');
+  } else {
+    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.
+ *
+ * @memberof Runner
+ * @public
+ * @return {Runner} Runner instance.
+ */
+Runner.prototype.abort = function() {
+  debug('abort(): aborting');
+  this._abort = true;
+
+  return this;
+};
+
+/**
+ * Returns `true` if Mocha is running in parallel mode.  For reporters.
+ *
+ * Subclasses should return an appropriate value.
+ * @public
+ * @returns {false}
+ */
+Runner.prototype.isParallelMode = function isParallelMode() {
+  return false;
+};
+
+/**
+ * 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
+ */
+Runner.prototype.workerReporter = function() {
+  throw createUnsupportedError('workerReporter() not supported in serial mode');
+};
+
+/**
+ * Filter leaks with the given globals flagged as `ok`.
+ *
+ * @private
+ * @param {Array} ok
+ * @param {Array} globals
+ * @return {Array}
+ */
+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;
+    }
+
+    // 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)) {
+      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)) {
+      return false;
+    }
+
+    // Opera and IE expose global variables for HTML element IDs (issue #243)
+    if (/^mocha-/.test(key)) {
+      return false;
+    }
+
+    var matched = ok.filter(function(ok) {
+      if (~ok.indexOf('*')) {
+        return key.indexOf(ok.split('*')[0]) === 0;
+      }
+      return key === ok;
+    });
+    return !matched.length && (!global.navigator || key !== 'onerror');
+  });
+}
+
+/**
+ * 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 ${utils.canonicalType(err)} ${stringify(
+      err
+    )} was thrown, throw an Error :)`
+  );
+}
+
+Runner.constants = constants;
+
+/**
+ * Node.js' `EventEmitter`
+ * @external EventEmitter
+ * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter}
+ */
+
+module.exports = Runner;