mocha 6.0.0-1 → 6.0.0

package/lib/runner.js

@@ -1,27 +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 createStatsCollector = require('./stats-collector');
+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',
@@ -33,33 +42,85 @@ 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
- * @param {Suite} [suite] Root suite
+ * @param {Suite} suite Root suite
  * @param {boolean} [delay] Whether or not to delay execution of root suite
  * until ready.
  */
@@ -72,16 +133,15 @@ 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 = /.*/;
   this.grep(this._defaultGrep);
   this.globals(this.globalProps().concat(extraGlobals()));
-  createStatsCollector(this);
 }
 
 /**
@@ -102,7 +162,7 @@ inherits(Runner, EventEmitter);
  * with number of tests matched.
  *
  * @public
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @param {RegExp} re
  * @param {boolean} invert
  * @return {Runner} Runner instance.
@@ -119,7 +179,7 @@ Runner.prototype.grep = function(re, invert) {
  * Returns the number of tests matching the grep search for the
  * given suite.
  *
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @public
  * @param {Suite} suite
  * @return {number}
@@ -165,7 +225,7 @@ Runner.prototype.globalProps = function() {
  * Allow the given `arr` of globals.
  *
  * @public
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @param {Array} arr
  * @return {Runner} Runner instance.
  */
@@ -204,13 +264,14 @@ 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(', ') + '')
+  if (leaks.length) {
+    var format = ngettext(
+      leaks.length,
+      'global leak detected: %s',
+      'global leaks detected: %s'
     );
-  } else if (leaks.length) {
-    this.fail(test, new Error('global leak detected: ' + leaks[0]));
+    var error = new Error(util.format(format, leaks.map(sQuote).join(', ')));
+    this.fail(test, error);
   }
 };
 
@@ -227,7 +288,7 @@ Runner.prototype.fail = function(test, err) {
   }
 
   ++this.failures;
-  test.state = 'failed';
+  test.state = STATE_FAILED;
 
   if (!isError(err)) {
     err = thrown2Error(err);
@@ -240,7 +301,7 @@ Runner.prototype.fail = function(test, err) {
     // some environments do not take kindly to monkeying with the stack
   }
 
-  this.emit('fail', test, err);
+  this.emit(constants.EVENT_TEST_FAIL, test, err);
 };
 
 /**
@@ -265,10 +326,18 @@ Runner.prototype.fail = function(test, err) {
  * @param {Error} 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.originalTitle + ' for ' + dQuote(hook.ctx.currentTest.title);
+  } else {
+    var parentTitle;
+    if (hook.parent.title) {
+      parentTitle = hook.parent.title;
+    } else {
+      parentTitle = hook.parent.root ? '{root}' : '';
+    }
+    hook.title = hook.originalTitle + ' in ' + dQuote(parentTitle);
   }
 
   this.fail(hook, err);
@@ -284,7 +353,7 @@ Runner.prototype.failHook = function(hook, err) {
 
 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) {
@@ -294,9 +363,15 @@ Runner.prototype.hook = function(name, 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) {
@@ -311,7 +386,7 @@ Runner.prototype.hook = function(name, fn) {
       }
       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) {
@@ -330,7 +405,7 @@ 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);
     });
@@ -430,7 +505,9 @@ Runner.prototype.runTest = function(fn) {
   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;
   }
@@ -473,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) {
@@ -539,24 +616,24 @@ 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) {
@@ -571,33 +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('retry', test, err);
+            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);
       });
     });
   }
@@ -630,7 +707,7 @@ 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) {
     if (errSuite) {
@@ -680,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);
       });
     }
@@ -689,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();
     }
@@ -705,18 +782,13 @@ Runner.prototype.runSuite = function(suite, fn) {
  */
 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)) {
@@ -734,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;
@@ -756,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);
@@ -777,53 +852,15 @@ 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.
  *
  * @public
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @param {Function} fn
  * @return {Runner} Runner instance.
  */
@@ -839,30 +876,31 @@ Runner.prototype.run = function(fn) {
 
   function start() {
     // If there is an `only` filter
-    if (hasOnly(rootSuite)) {
-      filterOnly(rootSuite);
+    if (rootSuite.hasOnly()) {
+      rootSuite.filterOnly();
     }
     self.started = true;
-    Runner.immediately(function() {
-      self.emit('start');
-    });
+    if (self._delay) {
+      self.emit(constants.EVENT_DELAY_END);
+    }
+    self.emit(constants.EVENT_RUN_BEGIN);
 
     self.runSuite(rootSuite, function() {
       debug('finished running');
-      Runner.immediately(function() {
-        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);
   });
@@ -873,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();
   }
@@ -885,7 +923,7 @@ Runner.prototype.run = function(fn) {
 /**
  * Cleanly abort execution.
  *
- * @memberof Mocha.Runner
+ * @memberof Runner
  * @public
  * @return {Runner} Runner instance.
  */
@@ -896,54 +934,6 @@ Runner.prototype.abort = function() {
   return this;
 };
 
-/**
- * Filter suites based on `isOnly` logic.
- *
- * @param {Array} suite
- * @returns {Boolean}
- * @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}
- * @private
- */
-function hasOnly(suite) {
-  return (
-    suite._onlyTests.length ||
-    suite._onlySuites.length ||
-    suite.suites.some(hasOnly)
-  );
-}
-
 /**
  * Filter leaks with the given globals flagged as `ok`.
  *
@@ -1017,6 +1007,8 @@ function thrown2Error(err) {
  * Array of globals dependent on the environment.
  *
  * @return {Array}
+ * @deprecated
+ * @todo remove; long since unsupported
  * @private
  */
 function extraGlobals() {
@@ -1027,7 +1019,6 @@ function extraGlobals() {
     });
 
     // 'errno' was renamed to process._errno in v0.9.11.
-
     if (nodeVersion < 0x00090b) {
       return ['errno'];
     }
@@ -1035,3 +1026,11 @@ function extraGlobals() {
 
   return [];
 }
+
+Runner.constants = constants;
+
+/**
+ * Node.js' `EventEmitter`
+ * @external EventEmitter
+ * @see {@link https://nodejs.org/api/events.html#events_class_eventemitter}
+ */