mocha 5.1.1 → 6.0.0

package/lib/runnable.js

@@ -1,50 +1,33 @@
 'use strict';
-/**
- * @module Runnable
- */
-/**
- * Module dependencies.
- */
+
 var EventEmitter = require('events').EventEmitter;
 var Pending = require('./pending');
 var debug = require('debug')('mocha:runnable');
-var milliseconds = require('./ms');
+var milliseconds = require('ms');
 var utils = require('./utils');
+var createInvalidExceptionError = require('./errors')
+  .createInvalidExceptionError;
 
 /**
  * Save timer references to avoid Sinon interfering (see GH-237).
  */
-
-/* eslint-disable no-unused-vars, no-native-reassign */
 var Date = global.Date;
 var setTimeout = global.setTimeout;
-var setInterval = global.setInterval;
 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`.  Derived from [EventEmitter](https://nodejs.org/api/events.html#events_class_eventemitter)
+ * Initialize a new `Runnable` with the given `title` and callback `fn`.
  *
- * @memberof Mocha
- * @public
  * @class
+ * @extends external:EventEmitter
+ * @public
  * @param {String} title
  * @param {Function} fn
  */
-function Runnable (title, fn) {
+function Runnable(title, fn) {
   this.title = title;
   this.fn = fn;
   this.body = (fn || '').toString();
@@ -65,23 +48,43 @@ function Runnable (title, fn) {
 utils.inherits(Runnable, EventEmitter);
 
 /**
- * Set & get timeout `ms`.
+ * Get current timeout value in msecs.
  *
- * @api private
- * @param {number|string} ms
- * @return {Runnable|number} ms or Runnable instance.
+ * @private
+ * @returns {number} current timeout threshold value
+ */
+/**
+ * @summary
+ * Set timeout threshold value (msecs).
+ *
+ * @description
+ * A string argument can use shorthand (e.g., "2s") and will be converted.
+ * The value will be clamped to range [<code>0</code>, <code>2^<sup>31</sup>-1</code>].
+ * If clamped value matches either range endpoint, timeouts will be disabled.
+ *
+ * @private
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout#Maximum_delay_value}
+ * @param {number|string} ms - Timeout threshold value.
+ * @returns {Runnable} this
+ * @chainable
  */
-Runnable.prototype.timeout = function (ms) {
+Runnable.prototype.timeout = function(ms) {
   if (!arguments.length) {
     return this._timeout;
   }
-  // see #1652 for reasoning
-  if (ms === 0 || ms > Math.pow(2, 31)) {
-    this._enableTimeouts = false;
-  }
   if (typeof ms === 'string') {
     ms = milliseconds(ms);
   }
+
+  // Clamp to range
+  var INT_MAX = Math.pow(2, 31) - 1;
+  var range = [0, INT_MAX];
+  ms = utils.clamp(ms, range);
+
+  // see #1652 for reasoning
+  if (ms === range[0] || ms === range[1]) {
+    this._enableTimeouts = false;
+  }
   debug('timeout %d', ms);
   this._timeout = ms;
   if (this.timer) {
@@ -93,11 +96,11 @@ Runnable.prototype.timeout = function (ms) {
 /**
  * Set or get slow `ms`.
  *
- * @api private
+ * @private
  * @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;
   }
@@ -112,11 +115,11 @@ Runnable.prototype.slow = function (ms) {
 /**
  * Set and get whether timeout is `enabled`.
  *
- * @api private
+ * @private
  * @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;
   }
@@ -130,18 +133,17 @@ Runnable.prototype.enableTimeouts = function (enabled) {
  *
  * @memberof Mocha.Runnable
  * @public
- * @api public
  */
-Runnable.prototype.skip = function () {
+Runnable.prototype.skip = function() {
   throw new Pending('sync skip');
 };
 
 /**
  * Check if this runnable or its parent suite is marked as pending.
  *
- * @api private
+ * @private
  */
-Runnable.prototype.isPending = function () {
+Runnable.prototype.isPending = function() {
   return this.pending || (this.parent && this.parent.isPending());
 };
 
@@ -150,8 +152,8 @@ Runnable.prototype.isPending = function () {
  * @return {boolean}
  * @private
  */
-Runnable.prototype.isFailed = function () {
-  return !this.isPending() && this.state === 'failed';
+Runnable.prototype.isFailed = function() {
+  return !this.isPending() && this.state === constants.STATE_FAILED;
 };
 
 /**
@@ -159,16 +161,16 @@ Runnable.prototype.isFailed = function () {
  * @return {boolean}
  * @private
  */
-Runnable.prototype.isPassed = function () {
-  return !this.isPending() && this.state === 'passed';
+Runnable.prototype.isPassed = function() {
+  return !this.isPending() && this.state === constants.STATE_PASSED;
 };
 
 /**
  * Set or get number of retries.
  *
- * @api private
+ * @private
  */
-Runnable.prototype.retries = function (n) {
+Runnable.prototype.retries = function(n) {
   if (!arguments.length) {
     return this._retries;
   }
@@ -178,9 +180,9 @@ Runnable.prototype.retries = function (n) {
 /**
  * Set or get current retry
  *
- * @api private
+ * @private
  */
-Runnable.prototype.currentRetry = function (n) {
+Runnable.prototype.currentRetry = function(n) {
   if (!arguments.length) {
     return this._currentRetry;
   }
@@ -193,10 +195,9 @@ Runnable.prototype.currentRetry = function (n) {
  *
  * @memberof Mocha.Runnable
  * @public
- * @api public
  * @return {string}
  */
-Runnable.prototype.fullTitle = function () {
+Runnable.prototype.fullTitle = function() {
   return this.titlePath().join(' ');
 };
 
@@ -205,49 +206,52 @@ Runnable.prototype.fullTitle = function () {
  *
  * @memberof Mocha.Runnable
  * @public
- * @api public
  * @return {string}
  */
-Runnable.prototype.titlePath = function () {
+Runnable.prototype.titlePath = function() {
   return this.parent.titlePath().concat([this.title]);
 };
 
 /**
  * Clear the timeout.
  *
- * @api private
+ * @private
  */
-Runnable.prototype.clearTimeout = function () {
+Runnable.prototype.clearTimeout = function() {
   clearTimeout(this.timer);
 };
 
 /**
  * Inspect the runnable void of private properties.
  *
- * @api private
+ * @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
+  );
 };
 
 /**
  * Reset the timeout.
  *
- * @api private
+ * @private
  */
-Runnable.prototype.resetTimeout = function () {
+Runnable.prototype.resetTimeout = function() {
   var self = this;
   var ms = this.timeout() || 1e9;
 
@@ -255,7 +259,7 @@ Runnable.prototype.resetTimeout = function () {
     return;
   }
   this.clearTimeout();
-  this.timer = setTimeout(function () {
+  this.timer = setTimeout(function() {
     if (!self._enableTimeouts) {
       return;
     }
@@ -267,10 +271,10 @@ Runnable.prototype.resetTimeout = function () {
 /**
  * Set or get a list of whitelisted globals for this test run.
  *
- * @api private
+ * @private
  * @param {string[]} globals
  */
-Runnable.prototype.globals = function (globals) {
+Runnable.prototype.globals = function(globals) {
   if (!arguments.length) {
     return this._allowedGlobals;
   }
@@ -281,9 +285,9 @@ Runnable.prototype.globals = function (globals) {
  * Run the test and invoke `fn(err)`.
  *
  * @param {Function} fn
- * @api private
+ * @private
  */
-Runnable.prototype.run = function (fn) {
+Runnable.prototype.run = function(fn) {
   var self = this;
   var start = new Date();
   var ctx = this.ctx;
@@ -296,7 +300,7 @@ Runnable.prototype.run = function (fn) {
   }
 
   // called multiple times
-  function multiple (err) {
+  function multiple(err) {
     if (emitted) {
       return;
     }
@@ -311,7 +315,7 @@ Runnable.prototype.run = function (fn) {
   }
 
   // finished
-  function done (err) {
+  function done(err) {
     var ms = self.timeout();
     if (self.timedOut) {
       return;
@@ -338,7 +342,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
@@ -353,7 +357,7 @@ Runnable.prototype.run = function (fn) {
       callFnAsync(this.fn);
     } catch (err) {
       emitted = true;
-      done(utils.getError(err));
+      done(Runnable.toValueOrError(err));
     }
     return;
   }
@@ -376,46 +380,56 @@ Runnable.prototype.run = function (fn) {
     }
   } catch (err) {
     emitted = true;
-    done(utils.getError(err));
+    done(Runnable.toValueOrError(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();
@@ -430,10 +444,53 @@ Runnable.prototype.run = function (fn) {
  * @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.';
+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);
 };
+
+var constants = utils.defineConstants(
+  /**
+   * {@link Runnable}-related constants.
+   * @public
+   * @memberof Runnable
+   * @readonly
+   * @static
+   * @alias constants
+   * @enum {string}
+   */
+  {
+    /**
+     * Value of `state` prop when a `Runnable` has failed
+     */
+    STATE_FAILED: 'failed',
+    /**
+     * Value of `state` prop when a `Runnable` has passed
+     */
+    STATE_PASSED: 'passed'
+  }
+);
+
+/**
+ * Given `value`, return identity if truthy, otherwise create an "invalid exception" error and return that.
+ * @param {*} [value] - Value to return, if present
+ * @returns {*|Error} `value`, otherwise an `Error`
+ * @private
+ */
+Runnable.toValueOrError = function(value) {
+  return (
+    value ||
+    createInvalidExceptionError(
+      'Runnable failed with falsy or undefined exception. Please throw an Error instead.',
+      value
+    )
+  );
+};
+
+Runnable.constants = constants;