mocha 5.0.4 → 5.2.0

package/lib/reporters/xunit.js

@@ -1,5 +1,7 @@
 'use strict';
-
+/**
+ * @module XUnit
+ */
 /**
  * Module dependencies.
  */
@@ -33,10 +35,14 @@ exports = module.exports = XUnit;
 /**
  * Initialize a new `XUnit` reporter.
  *
+ * @public
+ * @class
+ * @memberof Mocha.reporters
+ * @extends Mocha.reporters.Base
  * @api public
  * @param {Runner} runner
  */
-function XUnit (runner, options) {
+function XUnit(runner, options) {
   Base.call(this, runner);
 
   var stats = this.stats;
@@ -66,30 +72,36 @@ function XUnit (runner, options) {
   // fall back to the default suite name
   suiteName = suiteName || DEFAULT_SUITE_NAME;
 
-  runner.on('pending', function (test) {
+  runner.on('pending', function(test) {
     tests.push(test);
   });
 
-  runner.on('pass', function (test) {
+  runner.on('pass', function(test) {
     tests.push(test);
   });
 
-  runner.on('fail', function (test) {
+  runner.on('fail', function(test) {
     tests.push(test);
   });
 
-  runner.once('end', function () {
-    self.write(tag('testsuite', {
-      name: suiteName,
-      tests: stats.tests,
-      failures: stats.failures,
-      errors: stats.failures,
-      skipped: stats.tests - stats.failures - stats.passes,
-      timestamp: (new Date()).toUTCString(),
-      time: (stats.duration / 1000) || 0
-    }, false));
-
-    tests.forEach(function (t) {
+  runner.once('end', function() {
+    self.write(
+      tag(
+        'testsuite',
+        {
+          name: suiteName,
+          tests: stats.tests,
+          failures: stats.failures,
+          errors: stats.failures,
+          skipped: stats.tests - stats.failures - stats.passes,
+          timestamp: new Date().toUTCString(),
+          time: stats.duration / 1000 || 0
+        },
+        false
+      )
+    );
+
+    tests.forEach(function(t) {
       self.test(t);
     });
 
@@ -108,9 +120,9 @@ inherits(XUnit, Base);
  * @param failures
  * @param {Function} fn
  */
-XUnit.prototype.done = function (failures, fn) {
+XUnit.prototype.done = function(failures, fn) {
   if (this.fileStream) {
-    this.fileStream.end(function () {
+    this.fileStream.end(function() {
       fn(failures);
     });
   } else {
@@ -123,7 +135,7 @@ XUnit.prototype.done = function (failures, fn) {
  *
  * @param {string} line
  */
-XUnit.prototype.write = function (line) {
+XUnit.prototype.write = function(line) {
   if (this.fileStream) {
     this.fileStream.write(line + '\n');
   } else if (typeof process === 'object' && process.stdout) {
@@ -138,16 +150,28 @@ XUnit.prototype.write = function (line) {
  *
  * @param {Test} test
  */
-XUnit.prototype.test = function (test) {
+XUnit.prototype.test = function(test) {
   var attrs = {
     classname: test.parent.fullTitle(),
     name: test.title,
-    time: (test.duration / 1000) || 0
+    time: test.duration / 1000 || 0
   };
 
   if (test.state === 'failed') {
     var err = test.err;
-    this.write(tag('testcase', attrs, false, tag('failure', {}, false, escape(err.message) + '\n' + escape(err.stack))));
+    this.write(
+      tag(
+        'testcase',
+        attrs,
+        false,
+        tag(
+          'failure',
+          {},
+          false,
+          escape(err.message) + '\n' + escape(err.stack)
+        )
+      )
+    );
   } else if (test.isPending()) {
     this.write(tag('testcase', attrs, false, tag('skipped', {}, true)));
   } else {
@@ -164,7 +188,7 @@ XUnit.prototype.test = function (test) {
  * @param content
  * @return {string}
  */
-function tag (name, attrs, close, content) {
+function tag(name, attrs, close, content) {
   var end = close ? '/>' : '>';
   var pairs = [];
   var tag;

package/lib/runnable.js

@@ -1,9 +1,4 @@
 'use strict';
-
-/**
- * Module dependencies.
- */
-
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var debug = require('debug')('mocha:runnable');
@@ -22,28 +17,19 @@ var clearTimeout = global.clearTimeout;
 var clearInterval = global.clearInterval;
 /* eslint-enable no-unused-vars, no-native-reassign */
 
-/**
- * Object#toString().
- */
-
 var toString = Object.prototype.toString;
 
-/**
- * Expose `Runnable`.
- */
-
 module.exports = Runnable;
 
 /**
- * Initialize a new `Runnable` with the given `title` and callback `fn`.
+ * Initialize a new `Runnable` with the given `title` and callback `fn`.  Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
  *
+ * @class
+ * @extends EventEmitter
  * @param {String} title
  * @param {Function} fn
- * @api private
- * @param {string} title
- * @param {Function} fn
  */
-function Runnable (title, fn) {
+function Runnable(title, fn) {
   this.title = title;
   this.fn = fn;
   this.body = (fn || '').toString();
@@ -70,7 +56,7 @@ utils.inherits(Runnable, EventEmitter);
  * @param {number|string} ms
  * @return {Runnable|number} ms or Runnable instance.
  */
-Runnable.prototype.timeout = function (ms) {
+Runnable.prototype.timeout = function(ms) {
   if (!arguments.length) {
     return this._timeout;
   }
@@ -96,14 +82,14 @@ Runnable.prototype.timeout = function (ms) {
  * @param {number|string} ms
  * @return {Runnable|number} ms or Runnable instance.
  */
-Runnable.prototype.slow = function (ms) {
+Runnable.prototype.slow = function(ms) {
   if (!arguments.length || typeof ms === 'undefined') {
     return this._slow;
   }
   if (typeof ms === 'string') {
     ms = milliseconds(ms);
   }
-  debug('timeout %d', ms);
+  debug('slow %d', ms);
   this._slow = ms;
   return this;
 };
@@ -115,7 +101,7 @@ Runnable.prototype.slow = function (ms) {
  * @param {boolean} enabled
  * @return {Runnable|boolean} enabled or Runnable instance.
  */
-Runnable.prototype.enableTimeouts = function (enabled) {
+Runnable.prototype.enableTimeouts = function(enabled) {
   if (!arguments.length) {
     return this._enableTimeouts;
   }
@@ -127,9 +113,11 @@ Runnable.prototype.enableTimeouts = function (enabled) {
 /**
  * Halt and mark as pending.
  *
+ * @memberof Mocha.Runnable
+ * @public
  * @api public
  */
-Runnable.prototype.skip = function () {
+Runnable.prototype.skip = function() {
   throw new Pending('sync skip');
 };
 
@@ -138,7 +126,7 @@ Runnable.prototype.skip = function () {
  *
  * @api private
  */
-Runnable.prototype.isPending = function () {
+Runnable.prototype.isPending = function() {
   return this.pending || (this.parent && this.parent.isPending());
 };
 
@@ -147,7 +135,7 @@ Runnable.prototype.isPending = function () {
  * @return {boolean}
  * @private
  */
-Runnable.prototype.isFailed = function () {
+Runnable.prototype.isFailed = function() {
   return !this.isPending() && this.state === 'failed';
 };
 
@@ -156,7 +144,7 @@ Runnable.prototype.isFailed = function () {
  * @return {boolean}
  * @private
  */
-Runnable.prototype.isPassed = function () {
+Runnable.prototype.isPassed = function() {
   return !this.isPending() && this.state === 'passed';
 };
 
@@ -165,7 +153,7 @@ Runnable.prototype.isPassed = function () {
  *
  * @api private
  */
-Runnable.prototype.retries = function (n) {
+Runnable.prototype.retries = function(n) {
   if (!arguments.length) {
     return this._retries;
   }
@@ -177,7 +165,7 @@ Runnable.prototype.retries = function (n) {
  *
  * @api private
  */
-Runnable.prototype.currentRetry = function (n) {
+Runnable.prototype.currentRetry = function(n) {
   if (!arguments.length) {
     return this._currentRetry;
   }
@@ -188,20 +176,24 @@ Runnable.prototype.currentRetry = function (n) {
  * Return the full title generated by recursively concatenating the parent's
  * full title.
  *
+ * @memberof Mocha.Runnable
+ * @public
  * @api public
  * @return {string}
  */
-Runnable.prototype.fullTitle = function () {
+Runnable.prototype.fullTitle = function() {
   return this.titlePath().join(' ');
 };
 
 /**
  * Return the title path generated by concatenating the parent's title path with the title.
  *
+ * @memberof Mocha.Runnable
+ * @public
  * @api public
  * @return {string}
  */
-Runnable.prototype.titlePath = function () {
+Runnable.prototype.titlePath = function() {
   return this.parent.titlePath().concat([this.title]);
 };
 
@@ -210,7 +202,7 @@ Runnable.prototype.titlePath = function () {
  *
  * @api private
  */
-Runnable.prototype.clearTimeout = function () {
+Runnable.prototype.clearTimeout = function() {
   clearTimeout(this.timer);
 };
 
@@ -220,19 +212,23 @@ Runnable.prototype.clearTimeout = function () {
  * @api private
  * @return {string}
  */
-Runnable.prototype.inspect = function () {
-  return JSON.stringify(this, function (key, val) {
-    if (key[0] === '_') {
-      return;
-    }
-    if (key === 'parent') {
-      return '#<Suite>';
-    }
-    if (key === 'ctx') {
-      return '#<Context>';
-    }
-    return val;
-  }, 2);
+Runnable.prototype.inspect = function() {
+  return JSON.stringify(
+    this,
+    function(key, val) {
+      if (key[0] === '_') {
+        return;
+      }
+      if (key === 'parent') {
+        return '#<Suite>';
+      }
+      if (key === 'ctx') {
+        return '#<Context>';
+      }
+      return val;
+    },
+    2
+  );
 };
 
 /**
@@ -240,7 +236,7 @@ Runnable.prototype.inspect = function () {
  *
  * @api private
  */
-Runnable.prototype.resetTimeout = function () {
+Runnable.prototype.resetTimeout = function() {
   var self = this;
   var ms = this.timeout() || 1e9;
 
@@ -248,12 +244,11 @@ Runnable.prototype.resetTimeout = function () {
     return;
   }
   this.clearTimeout();
-  this.timer = setTimeout(function () {
+  this.timer = setTimeout(function() {
     if (!self._enableTimeouts) {
       return;
     }
-    self.callback(new Error('Timeout of ' + ms +
-      'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.'));
+    self.callback(self._timeoutError(ms));
     self.timedOut = true;
   }, ms);
 };
@@ -264,7 +259,7 @@ Runnable.prototype.resetTimeout = function () {
  * @api private
  * @param {string[]} globals
  */
-Runnable.prototype.globals = function (globals) {
+Runnable.prototype.globals = function(globals) {
   if (!arguments.length) {
     return this._allowedGlobals;
   }
@@ -277,7 +272,7 @@ Runnable.prototype.globals = function (globals) {
  * @param {Function} fn
  * @api private
  */
-Runnable.prototype.run = function (fn) {
+Runnable.prototype.run = function(fn) {
   var self = this;
   var start = new Date();
   var ctx = this.ctx;
@@ -290,7 +285,7 @@ Runnable.prototype.run = function (fn) {
   }
 
   // called multiple times
-  function multiple (err) {
+  function multiple(err) {
     if (emitted) {
       return;
     }
@@ -305,7 +300,7 @@ Runnable.prototype.run = function (fn) {
   }
 
   // finished
-  function done (err) {
+  function done(err) {
     var ms = self.timeout();
     if (self.timedOut) {
       return;
@@ -319,8 +314,7 @@ Runnable.prototype.run = function (fn) {
     self.duration = new Date() - start;
     finished = true;
     if (!err && self.duration > ms && self._enableTimeouts) {
-      err = new Error('Timeout of ' + ms +
-      'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.');
+      err = self._timeoutError(ms);
     }
     fn(err);
   }
@@ -333,7 +327,7 @@ Runnable.prototype.run = function (fn) {
     this.resetTimeout();
 
     // allows skip() to be used in an explicit async context
-    this.skip = function asyncSkip () {
+    this.skip = function asyncSkip() {
       done(new Pending('async skip call'));
       // halt execution.  the Runnable will be marked pending
       // by the previous call, and the uncaught handler will ignore
@@ -374,46 +368,74 @@ Runnable.prototype.run = function (fn) {
     done(utils.getError(err));
   }
 
-  function callFn (fn) {
+  function callFn(fn) {
     var result = fn.call(ctx);
     if (result && typeof result.then === 'function') {
       self.resetTimeout();
-      result
-        .then(function () {
+      result.then(
+        function() {
           done();
           // Return null so libraries like bluebird do not warn about
           // subsequently constructed Promises.
           return null;
         },
-        function (reason) {
+        function(reason) {
           done(reason || new Error('Promise rejected with no or falsy reason'));
-        });
+        }
+      );
     } else {
       if (self.asyncOnly) {
-        return done(new Error('--async-only option in use without declaring `done()` or returning a promise'));
+        return done(
+          new Error(
+            '--async-only option in use without declaring `done()` or returning a promise'
+          )
+        );
       }
 
       done();
     }
   }
 
-  function callFnAsync (fn) {
-    var result = fn.call(ctx, function (err) {
+  function callFnAsync(fn) {
+    var result = fn.call(ctx, function(err) {
       if (err instanceof Error || toString.call(err) === '[object Error]') {
         return done(err);
       }
       if (err) {
         if (Object.prototype.toString.call(err) === '[object Object]') {
-          return done(new Error('done() invoked with non-Error: ' +
-            JSON.stringify(err)));
+          return done(
+            new Error('done() invoked with non-Error: ' + JSON.stringify(err))
+          );
         }
         return done(new Error('done() invoked with non-Error: ' + err));
       }
       if (result && utils.isPromise(result)) {
-        return done(new Error('Resolution method is overspecified. Specify a callback *or* return a Promise; not both.'));
+        return done(
+          new Error(
+            'Resolution method is overspecified. Specify a callback *or* return a Promise; not both.'
+          )
+        );
       }
 
       done();
     });
   }
 };
+
+/**
+ * Instantiates a "timeout" error
+ *
+ * @param {number} ms - Timeout (in milliseconds)
+ * @returns {Error} a "timeout" error
+ * @private
+ */
+Runnable.prototype._timeoutError = function(ms) {
+  var msg =
+    'Timeout of ' +
+    ms +
+    'ms exceeded. For async tests and hooks, ensure "done()" is called; if returning a Promise, ensure it resolves.';
+  if (this.file) {
+    msg += ' (' + this.file + ')';
+  }
+  return new Error(msg);
+};