mocha 5.1.0 → 6.0.0-1

package/lib/utils.js

@@ -14,6 +14,10 @@ var glob = require('glob');
 var path = require('path');
 var join = path.join;
 var he = require('he');
+var errors = require('./errors');
+var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;
+var createMissingArgumentError = errors.createMissingArgumentError;
+var createUndefinedError = errors.createUndefinedError;
 
 /**
  * Ignored directories.
@@ -26,22 +30,22 @@ exports.inherits = require('util').inherits;
 /**
  * Escape special characters in the given string of html.
  *
- * @api private
+ * @private
  * @param  {string} html
  * @return {string}
  */
-exports.escape = function (html) {
-  return he.encode(String(html), { useNamedReferences: false });
+exports.escape = function(html) {
+  return he.encode(String(html), {useNamedReferences: false});
 };
 
 /**
  * Test if the given obj is type of string.
  *
- * @api private
+ * @private
  * @param {Object} obj
  * @return {boolean}
  */
-exports.isString = function (obj) {
+exports.isString = function(obj) {
   return typeof obj === 'string';
 };
 
@@ -49,15 +53,15 @@ exports.isString = function (obj) {
  * Watch the given `files` for changes
  * and invoke `fn(file)` on modification.
  *
- * @api private
+ * @private
  * @param {Array} files
  * @param {Function} fn
  */
-exports.watch = function (files, fn) {
-  var options = { interval: 100 };
-  files.forEach(function (file) {
+exports.watch = function(files, fn) {
+  var options = {interval: 100};
+  files.forEach(function(file) {
     debug('file %s', file);
-    fs.watchFile(file, options, function (curr, prev) {
+    fs.watchFile(file, options, function(curr, prev) {
       if (prev.mtime < curr.mtime) {
         fn(file);
       }
@@ -68,24 +72,24 @@ exports.watch = function (files, fn) {
 /**
  * Ignored files.
  *
- * @api private
+ * @private
  * @param {string} path
  * @return {boolean}
  */
-function ignored (path) {
+function ignored(path) {
   return !~ignore.indexOf(path);
 }
 
 /**
  * Lookup files in the given `dir`.
  *
- * @api private
+ * @private
  * @param {string} dir
  * @param {string[]} [ext=['.js']]
  * @param {Array} [ret=[]]
  * @return {Array}
  */
-exports.files = function (dir, ext, ret) {
+exports.files = function(dir, ext, ret) {
   ret = ret || [];
   ext = ext || ['js'];
 
@@ -93,7 +97,7 @@ exports.files = function (dir, ext, ret) {
 
   fs.readdirSync(dir)
     .filter(ignored)
-    .forEach(function (path) {
+    .forEach(function(path) {
       path = join(dir, path);
       if (fs.lstatSync(path).isDirectory()) {
         exports.files(path, ext, ret);
@@ -108,11 +112,11 @@ exports.files = function (dir, ext, ret) {
 /**
  * Compute a slug from the given `str`.
  *
- * @api private
+ * @private
  * @param {string} str
  * @return {string}
  */
-exports.slug = function (str) {
+exports.slug = function(str) {
   return str
     .toLowerCase()
     .replace(/ +/g, '-')
@@ -125,15 +129,22 @@ exports.slug = function (str) {
  * @param {string} str
  * @return {string}
  */
-exports.clean = function (str) {
+exports.clean = function(str) {
   str = str
-    .replace(/\r\n?|[\n\u2028\u2029]/g, '\n').replace(/^\uFEFF/, '')
+    .replace(/\r\n?|[\n\u2028\u2029]/g, '\n')
+    .replace(/^\uFEFF/, '')
     // (traditional)->  space/name     parameters    body     (lambda)-> parameters       body   multi-statement/single          keep body content
-    .replace(/^function(?:\s*|\s+[^(]*)\([^)]*\)\s*\{((?:.|\n)*?)\s*\}$|^\([^)]*\)\s*=>\s*(?:\{((?:.|\n)*?)\s*\}|((?:.|\n)*))$/, '$1$2$3');
+    .replace(
+      /^function(?:\s*|\s+[^(]*)\([^)]*\)\s*\{((?:.|\n)*?)\s*\}$|^\([^)]*\)\s*=>\s*(?:\{((?:.|\n)*?)\s*\}|((?:.|\n)*))$/,
+      '$1$2$3'
+    );
 
   var spaces = str.match(/^\n?( *)/)[1].length;
   var tabs = str.match(/^\n?(\t*)/)[1].length;
-  var re = new RegExp('^\n?' + (tabs ? '\t' : ' ') + '{' + (tabs || spaces) + '}', 'gm');
+  var re = new RegExp(
+    '^\n?' + (tabs ? '\t' : ' ') + '{' + (tabs || spaces) + '}',
+    'gm'
+  );
 
   str = str.replace(re, '');
 
@@ -143,31 +154,34 @@ exports.clean = function (str) {
 /**
  * Parse the given `qs`.
  *
- * @api private
+ * @private
  * @param {string} qs
  * @return {Object}
  */
-exports.parseQuery = function (qs) {
-  return qs.replace('?', '').split('&').reduce(function (obj, pair) {
-    var i = pair.indexOf('=');
-    var key = pair.slice(0, i);
-    var val = pair.slice(++i);
-
-    // Due to how the URLSearchParams API treats spaces
-    obj[key] = decodeURIComponent(val.replace(/\+/g, '%20'));
-
-    return obj;
-  }, {});
+exports.parseQuery = function(qs) {
+  return qs
+    .replace('?', '')
+    .split('&')
+    .reduce(function(obj, pair) {
+      var i = pair.indexOf('=');
+      var key = pair.slice(0, i);
+      var val = pair.slice(++i);
+
+      // Due to how the URLSearchParams API treats spaces
+      obj[key] = decodeURIComponent(val.replace(/\+/g, '%20'));
+
+      return obj;
+    }, {});
 };
 
 /**
  * Highlight the given string of `js`.
  *
- * @api private
+ * @private
  * @param {string} js
  * @return {string}
  */
-function highlight (js) {
+function highlight(js) {
   return js
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
@@ -175,17 +189,23 @@ function highlight (js) {
     .replace(/('.*?')/gm, '<span class="string">$1</span>')
     .replace(/(\d+\.\d+)/gm, '<span class="number">$1</span>')
     .replace(/(\d+)/gm, '<span class="number">$1</span>')
-    .replace(/\bnew[ \t]+(\w+)/gm, '<span class="keyword">new</span> <span class="init">$1</span>')
-    .replace(/\b(function|new|throw|return|var|if|else)\b/gm, '<span class="keyword">$1</span>');
+    .replace(
+      /\bnew[ \t]+(\w+)/gm,
+      '<span class="keyword">new</span> <span class="init">$1</span>'
+    )
+    .replace(
+      /\b(function|new|throw|return|var|if|else)\b/gm,
+      '<span class="keyword">$1</span>'
+    );
 }
 
 /**
  * Highlight the contents of tag `name`.
  *
- * @api private
+ * @private
  * @param {string} name
  */
-exports.highlightTags = function (name) {
+exports.highlightTags = function(name) {
   var code = document.getElementById('mocha').getElementsByTagName(name);
   for (var i = 0, len = code.length; i < len; ++i) {
     code[i].innerHTML = highlight(code[i].innerHTML);
@@ -201,12 +221,12 @@ exports.highlightTags = function (name) {
  * Objects w/ no properties return `'{}'`
  * All else: return result of `value.toString()`
  *
- * @api private
+ * @private
  * @param {*} value The value to inspect.
  * @param {string} typeHint The type of the value
  * @returns {string}
  */
-function emptyRepresentation (value, typeHint) {
+function emptyRepresentation(value, typeHint) {
   switch (typeHint) {
     case 'function':
       return '[Function]';
@@ -223,7 +243,7 @@ function emptyRepresentation (value, typeHint) {
  * Takes some variable and asks `Object.prototype.toString()` what it thinks it
  * is.
  *
- * @api private
+ * @private
  * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString
  * @param {*} value The value to test.
  * @returns {string} Computed type
@@ -240,7 +260,7 @@ function emptyRepresentation (value, typeHint) {
  * type(global) // 'global'
  * type(new String('foo') // 'object'
  */
-var type = exports.type = function type (value) {
+var type = (exports.type = function type(value) {
   if (value === undefined) {
     return 'undefined';
   } else if (value === null) {
@@ -248,10 +268,11 @@ var type = exports.type = function type (value) {
   } else if (Buffer.isBuffer(value)) {
     return 'buffer';
   }
-  return Object.prototype.toString.call(value)
+  return Object.prototype.toString
+    .call(value)
     .replace(/^\[.+\s(.+?)]$/, '$1')
     .toLowerCase();
-};
+});
 
 /**
  * Stringify `value`. Different behavior depending on type of value:
@@ -263,26 +284,28 @@ var type = exports.type = function type (value) {
  * - If `value` has properties, call {@link exports.canonicalize} on it, then return result of
  *   JSON.stringify().
  *
- * @api private
+ * @private
  * @see exports.type
  * @param {*} value
  * @return {string}
  */
-exports.stringify = function (value) {
+exports.stringify = function(value) {
   var typeHint = type(value);
 
   if (!~['object', 'array', 'function'].indexOf(typeHint)) {
     if (typeHint === 'buffer') {
       var json = Buffer.prototype.toJSON.call(value);
       // Based on the toJSON result
-      return jsonStringify(json.data && json.type ? json.data : json, 2)
-        .replace(/,(\n|$)/g, '$1');
+      return jsonStringify(
+        json.data && json.type ? json.data : json,
+        2
+      ).replace(/,(\n|$)/g, '$1');
     }
 
     // IE7/IE8 has a bizarre String constructor; needs to be coerced
     // into an array and back to obj.
     if (typeHint === 'string' && typeof value === 'object') {
-      value = value.split('').reduce(function (acc, char, idx) {
+      value = value.split('').reduce(function(acc, char, idx) {
         acc[idx] = char;
         return acc;
       }, {});
@@ -294,7 +317,10 @@ exports.stringify = function (value) {
 
   for (var prop in value) {
     if (Object.prototype.hasOwnProperty.call(value, prop)) {
-      return jsonStringify(exports.canonicalize(value, null, typeHint), 2).replace(/,(\n|$)/g, '$1');
+      return jsonStringify(
+        exports.canonicalize(value, null, typeHint),
+        2
+      ).replace(/,(\n|$)/g, '$1');
     }
   }
 
@@ -304,13 +330,13 @@ exports.stringify = function (value) {
 /**
  * like JSON.stringify but more sense.
  *
- * @api private
+ * @private
  * @param {Object}  object
  * @param {number=} spaces
  * @param {number=} depth
  * @returns {*}
  */
-function jsonStringify (object, spaces, depth) {
+function jsonStringify(object, spaces, depth) {
   if (typeof spaces === 'undefined') {
     // primitive types
     return _stringify(object);
@@ -320,13 +346,16 @@ function jsonStringify (object, spaces, depth) {
   var space = spaces * depth;
   var str = Array.isArray(object) ? '[' : '{';
   var end = Array.isArray(object) ? ']' : '}';
-  var length = typeof object.length === 'number' ? object.length : Object.keys(object).length;
+  var length =
+    typeof object.length === 'number'
+      ? object.length
+      : Object.keys(object).length;
   // `.repeat()` polyfill
-  function repeat (s, n) {
+  function repeat(s, n) {
     return new Array(n).join(s);
   }
 
-  function _stringify (val) {
+  function _stringify(val) {
     switch (type(val)) {
       case 'null':
       case 'undefined':
@@ -340,9 +369,10 @@ function jsonStringify (object, spaces, depth) {
       case 'regexp':
       case 'symbol':
       case 'number':
-        val = val === 0 && (1 / val) === -Infinity // `-0`
-          ? '-0'
-          : val.toString();
+        val =
+          val === 0 && 1 / val === -Infinity // `-0`
+            ? '-0'
+            : val.toString();
         break;
       case 'date':
         var sDate = isNaN(val.getTime()) ? val.toString() : val.toISOString();
@@ -355,9 +385,10 @@ function jsonStringify (object, spaces, depth) {
         val = '[Buffer: ' + jsonStringify(json, 2, depth + 1) + ']';
         break;
       default:
-        val = (val === '[Function]' || val === '[Circular]')
-          ? val
-          : JSON.stringify(val); // string
+        val =
+          val === '[Function]' || val === '[Circular]'
+            ? val
+            : JSON.stringify(val); // string
     }
     return val;
   }
@@ -367,15 +398,19 @@ function jsonStringify (object, spaces, depth) {
       continue; // not my business
     }
     --length;
-    str += '\n ' + repeat(' ', space) +
+    str +=
+      '\n ' +
+      repeat(' ', space) +
       (Array.isArray(object) ? '' : '"' + i + '": ') + // key
       _stringify(object[i]) + // value
       (length ? ',' : ''); // comma
   }
 
-  return str +
+  return (
+    str +
     // [], {}
-    (str.length !== 1 ? '\n' + repeat(' ', --space) + end : end);
+    (str.length !== 1 ? '\n' + repeat(' ', --space) + end : end)
+  );
 }
 
 /**
@@ -390,20 +425,20 @@ function jsonStringify (object, spaces, depth) {
  * - is a non-empty `Array`, `Object`, or `Function`, return the result of calling this function again.
  * - is an empty `Array`, `Object`, or `Function`, return the result of calling `emptyRepresentation()`
  *
- * @api private
+ * @private
  * @see {@link exports.stringify}
  * @param {*} value Thing to inspect.  May or may not have properties.
  * @param {Array} [stack=[]] Stack of seen values
  * @param {string} [typeHint] Type hint
  * @return {(Object|Array|Function|string|undefined)}
  */
-exports.canonicalize = function canonicalize (value, stack, typeHint) {
+exports.canonicalize = function canonicalize(value, stack, typeHint) {
   var canonicalizedObj;
   /* eslint-disable no-unused-vars */
   var prop;
   /* eslint-enable no-unused-vars */
   typeHint = typeHint || type(value);
-  function withStack (value, fn) {
+  function withStack(value, fn) {
     stack.push(value);
     fn();
     stack.pop();
@@ -422,8 +457,8 @@ exports.canonicalize = function canonicalize (value, stack, typeHint) {
       canonicalizedObj = value;
       break;
     case 'array':
-      withStack(value, function () {
-        canonicalizedObj = value.map(function (item) {
+      withStack(value, function() {
+        canonicalizedObj = value.map(function(item) {
           return exports.canonicalize(item, stack);
         });
       });
@@ -442,10 +477,12 @@ exports.canonicalize = function canonicalize (value, stack, typeHint) {
     /* falls through */
     case 'object':
       canonicalizedObj = canonicalizedObj || {};
-      withStack(value, function () {
-        Object.keys(value).sort().forEach(function (key) {
-          canonicalizedObj[key] = exports.canonicalize(value[key], stack);
-        });
+      withStack(value, function() {
+        Object.keys(value)
+          .sort()
+          .forEach(function(key) {
+            canonicalizedObj[key] = exports.canonicalize(value[key], stack);
+          });
       });
       break;
     case 'date':
@@ -467,13 +504,13 @@ exports.canonicalize = function canonicalize (value, stack, typeHint) {
  *
  * @memberof Mocha.utils
  * @public
- * @api public
  * @param {string} filepath Base path to start searching from.
  * @param {string[]} extensions File extensions to look for.
  * @param {boolean} recursive Whether or not to recurse into subdirectories.
+ * @todo Fix extension handling
  * @return {string[]} An array of paths.
  */
-exports.lookupFiles = function lookupFiles (filepath, extensions, recursive) {
+exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {
   var files = [];
 
   if (!fs.existsSync(filepath)) {
@@ -482,7 +519,10 @@ exports.lookupFiles = function lookupFiles (filepath, extensions, recursive) {
     } else {
       files = glob.sync(filepath);
       if (!files.length) {
-        throw new Error("cannot resolve path (or pattern) '" + filepath + "'");
+        throw createNoFilesMatchPatternError(
+          'cannot find any files matching pattern "' + filepath + '"',
+          filepath
+        );
       }
       return files;
     }
@@ -498,7 +538,7 @@ exports.lookupFiles = function lookupFiles (filepath, extensions, recursive) {
     return;
   }
 
-  fs.readdirSync(filepath).forEach(function (file) {
+  fs.readdirSync(filepath).forEach(function(file) {
     file = path.join(filepath, file);
     try {
       var stat = fs.statSync(file);
@@ -512,6 +552,13 @@ exports.lookupFiles = function lookupFiles (filepath, extensions, recursive) {
       // ignore error
       return;
     }
+    if (!extensions) {
+      throw createMissingArgumentError(
+        'Argument "extensions" required when argument "filepath" is a directory',
+        'extensions',
+        'array'
+      );
+    }
     var re = new RegExp('\\.(?:' + extensions.join('|') + ')$');
     if (!stat.isFile() || !re.test(file) || path.basename(file)[0] === '.') {
       return;
@@ -528,8 +575,10 @@ exports.lookupFiles = function lookupFiles (filepath, extensions, recursive) {
  * @return {Error}
  */
 
-exports.undefinedError = function () {
-  return new Error('Caught undefined error, did you throw without specifying what?');
+exports.undefinedError = function() {
+  return createUndefinedError(
+    'Caught undefined error, did you throw without specifying what?'
+  );
 };
 
 /**
@@ -539,10 +588,30 @@ exports.undefinedError = function () {
  * @return {Error}
  */
 
-exports.getError = function (err) {
+exports.getError = function(err) {
   return err || exports.undefinedError();
 };
 
+/**
+ * Show a deprecation warning. Each distinct message is only displayed once.
+ *
+ * @param {string} msg
+ */
+exports.deprecate = function deprecate(msg) {
+  msg = String(msg);
+  if (msg && !deprecate.cache[msg]) {
+    deprecate.cache[msg] = true;
+    if (process.emitWarning) {
+      process.emitWarning(msg, 'DeprecationWarning');
+    } else {
+      process.nextTick(function() {
+        console.warn(msg);
+      });
+    }
+  }
+};
+exports.deprecate.cache = {};
+
 /**
  * @summary
  * This Filter based on `mocha-clean` module.(see: `github.com/rstacruz/mocha-clean`)
@@ -552,9 +621,9 @@ exports.getError = function (err) {
  * (i.e: strip Mocha and internal node functions from stack trace).
  * @returns {Function}
  */
-exports.stackTraceFilter = function () {
+exports.stackTraceFilter = function() {
   // TODO: Replace with `process.browser`
-  var is = typeof document === 'undefined' ? { node: true } : { browser: true };
+  var is = typeof document === 'undefined' ? {node: true} : {browser: true};
   var slash = path.sep;
   var cwd;
   if (is.node) {
@@ -562,30 +631,35 @@ exports.stackTraceFilter = function () {
   } else {
     cwd = (typeof location === 'undefined'
       ? window.location
-      : location).href.replace(/\/[^/]*$/, '/');
+      : location
+    ).href.replace(/\/[^/]*$/, '/');
     slash = '/';
   }
 
-  function isMochaInternal (line) {
-    return (~line.indexOf('node_modules' + slash + 'mocha' + slash)) ||
-      (~line.indexOf('node_modules' + slash + 'mocha.js')) ||
-      (~line.indexOf('bower_components' + slash + 'mocha.js')) ||
-      (~line.indexOf(slash + 'mocha.js'));
+  function isMochaInternal(line) {
+    return (
+      ~line.indexOf('node_modules' + slash + 'mocha' + slash) ||
+      ~line.indexOf('node_modules' + slash + 'mocha.js') ||
+      ~line.indexOf('bower_components' + slash + 'mocha.js') ||
+      ~line.indexOf(slash + 'mocha.js')
+    );
   }
 
-  function isNodeInternal (line) {
-    return (~line.indexOf('(timers.js:')) ||
-      (~line.indexOf('(events.js:')) ||
-      (~line.indexOf('(node.js:')) ||
-      (~line.indexOf('(module.js:')) ||
-      (~line.indexOf('GeneratorFunctionPrototype.next (native)')) ||
-      false;
+  function isNodeInternal(line) {
+    return (
+      ~line.indexOf('(timers.js:') ||
+      ~line.indexOf('(events.js:') ||
+      ~line.indexOf('(node.js:') ||
+      ~line.indexOf('(module.js:') ||
+      ~line.indexOf('GeneratorFunctionPrototype.next (native)') ||
+      false
+    );
   }
 
-  return function (stack) {
+  return function(stack) {
     stack = stack.split('\n');
 
-    stack = stack.reduce(function (list, line) {
+    stack = stack.reduce(function(list, line) {
       if (isMochaInternal(line)) {
         return list;
       }
@@ -609,16 +683,31 @@ exports.stackTraceFilter = function () {
 
 /**
  * Crude, but effective.
- * @api
+ * @public
  * @param {*} value
  * @returns {boolean} Whether or not `value` is a Promise
  */
-exports.isPromise = function isPromise (value) {
-  return typeof value === 'object' && typeof value.then === 'function';
+exports.isPromise = function isPromise(value) {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof value.then === 'function'
+  );
+};
+
+/**
+ * Clamps a numeric value to an inclusive range.
+ *
+ * @param {number} value - Value to be clamped.
+ * @param {numer[]} range - Two element array specifying [min, max] range.
+ * @returns {number} clamped value
+ */
+exports.clamp = function clamp(value, range) {
+  return Math.min(Math.max(value, range[0]), range[1]);
 };
 
 /**
  * It's a noop.
- * @api
+ * @public
  */
-exports.noop = function () {};
+exports.noop = function() {};