mocha 5.0.4 → 5.2.0

package/lib/runner.js

@@ -1,9 +1,11 @@
 'use strict';
 
+/**
+ * @module Runner
+ */
 /**
  * Module dependencies.
  */
-
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var utils = require('./utils');
@@ -37,7 +39,7 @@ var globals = [
 module.exports = Runner;
 
 /**
- * Initialize a `Runner` for the given `suite`.
+ * Initialize a `Runner` for the given `suite`. Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
  *
  * Events:
  *
@@ -53,12 +55,15 @@ module.exports = Runner;
  *   - `fail`  (test, err) test failed
  *   - `pending`  (test) test pending
  *
+ * @memberof Mocha
+ * @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;
@@ -67,10 +72,10 @@ function Runner (suite, delay) {
   this.started = false;
   this.total = suite.total();
   this.failures = 0;
-  this.on('test end', function (test) {
+  this.on('test end', function(test) {
     self.checkGlobals(test);
   });
-  this.on('hook end', function (hook) {
+  this.on('hook end', function(hook) {
     self.checkGlobals(hook);
   });
   this._defaultGrep = /.*/;
@@ -95,15 +100,14 @@ inherits(Runner, EventEmitter);
  * 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 Mocha.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;
@@ -115,17 +119,17 @@ Runner.prototype.grep = function (re, invert) {
  * Returns the number of tests matching the grep search for the
  * given suite.
  *
- * @param {Suite} suite
- * @return {Number}
+ * @memberof Mocha.Runner
  * @api public
+ * @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;
@@ -144,7 +148,7 @@ Runner.prototype.grepTotal = function (suite) {
  * @return {Array}
  * @api private
  */
-Runner.prototype.globalProps = function () {
+Runner.prototype.globalProps = function() {
   var props = Object.keys(global);
 
   // non-enumerables
@@ -161,13 +165,13 @@ Runner.prototype.globalProps = function () {
 /**
  * Allow the given `arr` of globals.
  *
- * @param {Array} arr
- * @return {Runner} for chaining
  * @api public
+ * @public
+ * @memberof Mocha.Runner
  * @param {Array} arr
  * @return {Runner} Runner instance.
  */
-Runner.prototype.globals = function (arr) {
+Runner.prototype.globals = function(arr) {
   if (!arguments.length) {
     return this._globals;
   }
@@ -181,7 +185,7 @@ Runner.prototype.globals = function (arr) {
  *
  * @api private
  */
-Runner.prototype.checkGlobals = function (test) {
+Runner.prototype.checkGlobals = function(test) {
   if (this.ignoreLeaks) {
     return;
   }
@@ -203,7 +207,10 @@ Runner.prototype.checkGlobals = function (test) {
   this._globals = this._globals.concat(leaks);
 
   if (leaks.length > 1) {
-    this.fail(test, new Error('global leaks detected: ' + leaks.join(', ') + ''));
+    this.fail(
+      test,
+      new Error('global leaks detected: ' + leaks.join(', ') + '')
+    );
   } else if (leaks.length) {
     this.fail(test, new Error('global leak detected: ' + leaks[0]));
   }
@@ -216,7 +223,7 @@ Runner.prototype.checkGlobals = function (test) {
  * @param {Test} test
  * @param {Error} err
  */
-Runner.prototype.fail = function (test, err) {
+Runner.prototype.fail = function(test, err) {
   if (test.isPending()) {
     return;
   }
@@ -225,18 +232,26 @@ Runner.prototype.fail = function (test, err) {
   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 :)');
+    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) {
+    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);
+  if (this.suite.bail()) {
+    this.emit('end');
+  }
 };
 
 /**
@@ -259,16 +274,14 @@ Runner.prototype.fail = function (test, err) {
  * @param {Hook} hook
  * @param {Error} err
  */
-Runner.prototype.failHook = function (hook, err) {
+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 + '"';
+    hook.title =
+      hook.originalTitle + ' for "' + hook.ctx.currentTest.title + '"';
   }
 
   this.fail(hook, err);
-  if (this.suite.bail()) {
-    this.emit('end');
-  }
 };
 
 /**
@@ -279,12 +292,12 @@ Runner.prototype.failHook = function (hook, err) {
  * @param {Function} fn
  */
 
-Runner.prototype.hook = function (name, fn) {
+Runner.prototype.hook = function(name, fn) {
   var suite = this.suite;
   var hooks = suite['_' + name];
   var self = this;
 
-  function next (i) {
+  function next(i) {
     var hook = hooks[i];
     if (!hook) {
       return fn();
@@ -296,12 +309,12 @@ Runner.prototype.hook = function (name, fn) {
     self.emit('hook', 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);
@@ -311,7 +324,7 @@ Runner.prototype.hook = function (name, fn) {
           if (name === 'beforeEach' || name === 'afterEach') {
             self.test.pending = true;
           } else {
-            suite.tests.forEach(function (test) {
+            suite.tests.forEach(function(test) {
               test.pending = true;
             });
             // a pending hook won't be executed twice.
@@ -330,7 +343,7 @@ Runner.prototype.hook = function (name, fn) {
     });
   }
 
-  Runner.immediately(function () {
+  Runner.immediately(function() {
     next(0);
   });
 };
@@ -344,11 +357,11 @@ Runner.prototype.hook = function (name, fn) {
  * @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) {
@@ -356,7 +369,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;
@@ -377,7 +390,7 @@ Runner.prototype.hooks = function (name, suites, fn) {
  * @param {Function} fn
  * @api 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);
 };
@@ -389,7 +402,7 @@ Runner.prototype.hookUp = function (name, fn) {
  * @param {Function} fn
  * @api 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);
 };
@@ -401,7 +414,7 @@ Runner.prototype.hookDown = function (name, fn) {
  * @return {Array}
  * @api private
  */
-Runner.prototype.parents = function () {
+Runner.prototype.parents = function() {
   var suite = this.suite;
   var suites = [];
   while (suite.parent) {
@@ -417,7 +430,7 @@ Runner.prototype.parents = function () {
  * @param {Function} fn
  * @api private
  */
-Runner.prototype.runTest = function (fn) {
+Runner.prototype.runTest = function(fn) {
   var self = this;
   var test = this.test;
 
@@ -431,7 +444,7 @@ Runner.prototype.runTest = function (fn) {
   if (this.asyncOnly) {
     test.asyncOnly = true;
   }
-  test.on('error', function (err) {
+  test.on('error', function(err) {
     self.fail(test, err);
   });
   if (this.allowUncaught) {
@@ -452,12 +465,12 @@ Runner.prototype.runTest = function (fn) {
  * @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;
 
@@ -467,7 +480,7 @@ Runner.prototype.runTests = function (suite, fn) {
 
     if (self.suite) {
       // call hookUp afterEach
-      self.hookUp('afterEach', function (err2, errSuite2) {
+      self.hookUp('afterEach', function(err2, errSuite2) {
         self.suite = orig;
         // some hooks may fail even now
         if (err2) {
@@ -483,7 +496,7 @@ 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();
@@ -540,8 +553,8 @@ Runner.prototype.runTests = function (suite, fn) {
     }
 
     // execute test and hook(s)
-    self.emit('test', self.test = test);
-    self.hookDown('beforeEach', function (err, errSuite) {
+    self.emit('test', (self.test = test));
+    self.hookDown('beforeEach', function(err, errSuite) {
       if (test.isPending()) {
         if (self.forbidPending) {
           test.isPending = alwaysFalse;
@@ -557,7 +570,7 @@ Runner.prototype.runTests = function (suite, fn) {
         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();
@@ -599,7 +612,7 @@ Runner.prototype.runTests = function (suite, fn) {
   next();
 };
 
-function alwaysFalse () {
+function alwaysFalse() {
   return false;
 }
 
@@ -610,7 +623,7 @@ function alwaysFalse () {
  * @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);
@@ -622,9 +635,9 @@ Runner.prototype.runSuite = function (suite, fn) {
     return fn();
   }
 
-  this.emit('suite', this.suite = suite);
+  this.emit('suite', (this.suite = suite));
 
-  function next (errSuite) {
+  function next(errSuite) {
     if (errSuite) {
       // current suite failed on a hook from errSuite
       if (errSuite === suite) {
@@ -650,7 +663,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 {
@@ -658,7 +671,7 @@ Runner.prototype.runSuite = function (suite, fn) {
     }
   }
 
-  function done (errSuite) {
+  function done(errSuite) {
     self.suite = suite;
     self.nextSuite = next;
 
@@ -672,7 +685,7 @@ Runner.prototype.runSuite = function (suite, fn) {
       // remove reference to test
       delete self.test;
 
-      self.hook('afterAll', function () {
+      self.hook('afterAll', function() {
         self.emit('suite end', suite);
         fn(errSuite);
       });
@@ -681,7 +694,7 @@ Runner.prototype.runSuite = function (suite, fn) {
 
   this.nextSuite = next;
 
-  this.hook('beforeAll', function (err) {
+  this.hook('beforeAll', function(err) {
     if (err) {
       return done();
     }
@@ -695,11 +708,17 @@ Runner.prototype.runSuite = function (suite, fn) {
  * @param {Error} err
  * @api 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 %s',
+      err ===
+      function() {
+        return this;
+      }.call(err)
+        ? err.message || err
+        : err
+    );
   } else {
     debug('uncaught undefined exception');
     err = undefinedError();
@@ -772,8 +791,8 @@ Runner.prototype.uncaught = function (err) {
  *
  * @param {Suite} suite
  */
-function cleanSuiteReferences (suite) {
-  function cleanArrReferences (arr) {
+function cleanSuiteReferences(suite) {
+  function cleanArrReferences(arr) {
     for (var i = 0; i < arr.length; i++) {
       delete arr[i].fn;
     }
@@ -804,30 +823,30 @@ function cleanSuiteReferences (suite) {
  * Run the root suite and invoke `fn(failures)`
  * on completion.
  *
- * @param {Function} fn
- * @return {Runner} for chaining
  * @api public
+ * @public
+ * @memberof Mocha.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);
     }
     self.started = true;
     self.emit('start');
-    self.runSuite(rootSuite, function () {
+    self.runSuite(rootSuite, function() {
       debug('finished running');
       self.emit('end');
     });
@@ -839,7 +858,7 @@ Runner.prototype.run = function (fn) {
   this.on('suite end', cleanSuiteReferences);
 
   // callback
-  this.on('end', function () {
+  this.on('end', function() {
     debug('end');
     process.removeListener('uncaughtException', uncaught);
     fn(self.failures);
@@ -863,10 +882,12 @@ Runner.prototype.run = function (fn) {
 /**
  * Cleanly abort execution.
  *
+ * @memberof Mocha.Runner
+ * @public
  * @api public
  * @return {Runner} Runner instance.
  */
-Runner.prototype.abort = function () {
+Runner.prototype.abort = function() {
   debug('aborting');
   this._abort = true;
 
@@ -880,7 +901,7 @@ Runner.prototype.abort = function () {
  * @returns {Boolean}
  * @api private
  */
-function filterOnly (suite) {
+function filterOnly(suite) {
   if (suite._onlyTests.length) {
     // If the suite contains `only` tests, run those and ignore any nested suites.
     suite.tests = suite._onlyTests;
@@ -888,7 +909,7 @@ function filterOnly (suite) {
   } else {
     // Otherwise, do not run any of the tests in this suite.
     suite.tests = [];
-    suite._onlySuites.forEach(function (onlySuite) {
+    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)) {
@@ -896,8 +917,10 @@ function filterOnly (suite) {
       }
     });
     // 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);
+    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
@@ -911,8 +934,12 @@ function filterOnly (suite) {
  * @returns {Boolean}
  * @api private
  */
-function hasOnly (suite) {
-  return suite._onlyTests.length || suite._onlySuites.length || suite.suites.some(hasOnly);
+function hasOnly(suite) {
+  return (
+    suite._onlyTests.length ||
+    suite._onlySuites.length ||
+    suite.suites.some(hasOnly)
+  );
 }
 
 /**
@@ -923,8 +950,8 @@ function hasOnly (suite) {
  * @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;
@@ -933,13 +960,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;
     }
 
@@ -948,7 +975,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,16 +991,16 @@ function filterLeaks (ok, globals) {
  * @return {Array}
  * @api 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'];
     }
   }