mocha 8.0.0 → 8.1.2

package/lib/mocha.js

@@ -35,23 +35,28 @@ exports = module.exports = Mocha;
 /**
  * A Mocha instance is a finite state machine.
  * These are the states it can be in.
+ * @private
  */
 var mochaStates = utils.defineConstants({
   /**
    * Initial state of the mocha instance
+   * @private
    */
   INIT: 'init',
   /**
    * Mocha instance is running tests
+   * @private
    */
   RUNNING: 'running',
   /**
    * Mocha instance is done running tests and references to test functions and hooks are cleaned.
    * You can reset this state by unloading the test files.
+   * @private
    */
   REFERENCES_CLEANED: 'referencesCleaned',
   /**
    * Mocha instance is disposed and can no longer be used.
+   * @private
    */
   DISPOSED: 'disposed'
 });
@@ -67,6 +72,7 @@ if (!utils.isBrowser() && typeof module.paths !== 'undefined') {
 
 /**
  * Expose internals.
+ * @private
  */
 
 exports.utils = utils;
@@ -246,7 +252,7 @@ Mocha.prototype.addFile = function(file) {
  * @public
  * @see [CLI option](../#-reporter-name-r-name)
  * @see [Reporters](../#reporters)
- * @param {String|Function} reporter - Reporter name or constructor.
+ * @param {String|Function} reporterName - Reporter name or constructor.
  * @param {Object} [reporterOptions] - Options used to configure the reporter.
  * @returns {Mocha} this
  * @chainable
@@ -769,8 +775,8 @@ Mocha.prototype.timeout = function(msecs) {
  * // Allow any failed test to retry one more time
  * mocha.retries(1);
  */
-Mocha.prototype.retries = function(n) {
-  this.suite.retries(n);
+Mocha.prototype.retries = function(retry) {
+  this.suite.retries(retry);
   return this;
 };
 
@@ -801,7 +807,7 @@ Mocha.prototype.slow = function(msecs) {
  *
  * @public
  * @see [CLI option](../#-async-only-a)
- * @param {boolean} [asyncOnly=true] - Wether to force `done` callback or promise.
+ * @param {boolean} [asyncOnly=true] - Whether to force `done` callback or promise.
  * @return {Mocha} this
  * @chainable
  */
@@ -841,7 +847,7 @@ Mocha.prototype.allowUncaught = function(allowUncaught) {
  * Delays root suite execution.
  *
  * @description
- * Used to perform asynch operations before any suites are run.
+ * Used to perform async operations before any suites are run.
  *
  * @public
  * @see [delayed root suite](../#delayed-root-suite)
@@ -921,6 +927,7 @@ Object.defineProperty(Mocha.prototype, 'version', {
 /**
  * Callback to be invoked when test execution is complete.
  *
+ * @private
  * @callback DoneCB
  * @param {number} failures - Number of failures that occurred.
  */
@@ -1091,6 +1098,7 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
 
 /**
  * An alternative way to define root hooks that works with parallel runs.
+ * @private
  * @typedef {Object} MochaRootHookObject
  * @property {Function|Function[]} [beforeAll] - "Before all" hook(s)
  * @property {Function|Function[]} [beforeEach] - "Before each" hook(s)
@@ -1100,6 +1108,7 @@ Mocha.prototype.lazyLoadFiles = function lazyLoadFiles(enable) {
 
 /**
  * An function that returns a {@link MochaRootHookObject}, either sync or async.
+ * @private
  * @callback MochaRootHookFunction
  * @returns {MochaRootHookObject|Promise<MochaRootHookObject>}
  */

package/lib/nodejs/parallel-buffered-runner.js

@@ -281,12 +281,14 @@ module.exports = ParallelBufferedRunner;
 
 /**
  * Listener function intended to be bound to `Process.SIGINT` event
+ * @private
  * @callback SigIntListener
  * @returns {Promise<void>}
  */
 
 /**
  * A function accepting a test file path and returning the results of a test run
+ * @private
  * @callback FileRunner
  * @param {string} filename - File to run
  * @returns {Promise<SerializedWorkerResult>}

package/lib/nodejs/serializer.js

@@ -56,7 +56,7 @@ class SerializableWorkerResult {
   /**
    * Instantiates a new {@link SerializableWorkerResult}.
    * @param {...any} args - Args to constructor
-   * @returns {SerilizableWorkerResult}
+   * @returns {SerializableWorkerResult}
    */
   static create(...args) {
     return new SerializableWorkerResult(...args);
@@ -387,6 +387,7 @@ exports.SerializableWorkerResult = SerializableWorkerResult;
 /**
  * The result of calling `SerializableEvent.serialize`, as received
  * by the deserializer.
+ * @private
  * @typedef {Object} SerializedEvent
  * @property {object?} data - Optional serialized data
  * @property {object?} error - Optional serialized `Error`
@@ -395,6 +396,7 @@ exports.SerializableWorkerResult = SerializableWorkerResult;
 /**
  * The result of calling `SerializableWorkerResult.serialize` as received
  * by the deserializer.
+ * @private
  * @typedef {Object} SerializedWorkerResult
  * @property {number} failureCount - Number of failures
  * @property {SerializedEvent[]} events - Serialized events

package/lib/pending.js

@@ -1,5 +1,9 @@
 'use strict';
 
+/**
+ @module Pending
+*/
+
 module.exports = Pending;
 
 /**

package/lib/reporters/base.js

@@ -6,15 +6,24 @@
  * Module dependencies.
  */
 
-var tty = require('tty');
 var diff = require('diff');
 var milliseconds = require('ms');
 var utils = require('../utils');
-var supportsColor = utils.isBrowser() ? null : require('supports-color');
+var supportsColor = require('supports-color');
 var constants = require('../runner').constants;
 var EVENT_TEST_PASS = constants.EVENT_TEST_PASS;
 var EVENT_TEST_FAIL = constants.EVENT_TEST_FAIL;
 
+const isBrowser = utils.isBrowser();
+
+function getBrowserWindowSize() {
+  if ('innerHeight' in global) {
+    return [global.innerHeight, global.innerWidth];
+  }
+  // In a Web Worker, the DOM Window is not available.
+  return [640, 480];
+}
+
 /**
  * Expose `Base`.
  */
@@ -25,7 +34,7 @@ exports = module.exports = Base;
  * Check if both stdio streams are associated with a tty.
  */
 
-var isatty = process.stdout.isTTY && process.stderr.isTTY;
+var isatty = isBrowser || (process.stdout.isTTY && process.stderr.isTTY);
 
 /**
  * Save log references to avoid tests interfering (see GH-3604).
@@ -37,7 +46,7 @@ var consoleLog = console.log;
  */
 
 exports.useColors =
-  !utils.isBrowser() &&
+  !isBrowser &&
   (supportsColor.stdout || process.env.MOCHA_COLORS !== undefined);
 
 /**
@@ -69,7 +78,9 @@ exports.colors = {
   light: 90,
   'diff gutter': 90,
   'diff added': 32,
-  'diff removed': 31
+  'diff removed': 31,
+  'diff added inline': '30;42',
+  'diff removed inline': '30;41'
 };
 
 /**
@@ -118,9 +129,11 @@ exports.window = {
 };
 
 if (isatty) {
-  exports.window.width = process.stdout.getWindowSize
-    ? process.stdout.getWindowSize(1)[0]
-    : tty.getWindowSize()[1];
+  if (isBrowser) {
+    exports.window.width = getBrowserWindowSize()[1];
+  } else {
+    exports.window.width = process.stdout.getWindowSize(1)[0];
+  }
 }
 
 /**
@@ -406,9 +419,9 @@ function inlineDiff(actual, expected) {
   // legend
   msg =
     '\n' +
-    color('diff removed', 'actual') +
+    color('diff removed inline', 'actual') +
     ' ' +
-    color('diff added', 'expected') +
+    color('diff added inline', 'expected') +
     '\n\n' +
     msg +
     '\n';
@@ -474,10 +487,10 @@ function errorDiff(actual, expected) {
     .diffWordsWithSpace(actual, expected)
     .map(function(str) {
       if (str.added) {
-        return colorLines('diff added', str.value);
+        return colorLines('diff added inline', str.value);
       }
       if (str.removed) {
-        return colorLines('diff removed', str.value);
+        return colorLines('diff removed inline', str.value);
       }
       return str.value;
     })

package/lib/runnable.js

@@ -11,6 +11,7 @@ var createMultipleDoneError = errors.createMultipleDoneError;
 
 /**
  * Save timer references to avoid Sinon interfering (see GH-237).
+ * @private
  */
 var Date = global.Date;
 var setTimeout = global.setTimeout;

package/lib/runner.js

@@ -2,6 +2,7 @@
 
 /**
  * Module dependencies.
+ * @private
  */
 var util = require('util');
 var EventEmitter = require('events').EventEmitter;
@@ -31,6 +32,7 @@ var createFatalError = errors.createFatalError;
 
 /**
  * Non-enumerable globals.
+ * @private
  * @readonly
  */
 var globals = [
@@ -204,7 +206,7 @@ Runner.prototype._addEventListener = function(target, eventName, listener) {
 /**
  * Replacement for `target.removeListener(eventName, listener)` that also updates the bookkeeping.
  * @param {EventEmitter} target - The `EventEmitter`
- * @param {string} eventName - The event anme
+ * @param {string} eventName - The event name
  * @param {function} listener - Listener function
  * @private
  */
@@ -358,6 +360,19 @@ Runner.prototype.checkGlobals = function(test) {
 /**
  * Fail the given `test`.
  *
+ * If `test` is a hook, failures work in the following pattern:
+ * - If bail, run corresponding `after each` and `after` hooks,
+ *   then exit
+ * - Failed `before` hook skips all tests in a suite and subsuites,
+ *   but jumps to corresponding `after` hook
+ * - Failed `before each` hook skips remaining tests in a
+ *   suite and jumps to corresponding `after each` hook,
+ *   which is run only once
+ * - Failed `after` hook does not alter execution order
+ * - Failed `after each` hook skips remaining tests in a
+ *   suite and subsuites, but executes other `after each`
+ *   hooks
+ *
  * @private
  * @param {Runnable} test
  * @param {Error} err
@@ -396,44 +411,6 @@ Runner.prototype.fail = function(test, err, force) {
   this.emit(constants.EVENT_TEST_FAIL, test, err);
 };
 
-/**
- * Fail the given `hook` with `err`.
- *
- * Hook failures work in the following pattern:
- * - If bail, run corresponding `after each` and `after` hooks,
- *   then exit
- * - Failed `before` hook skips all tests in a suite and subsuites,
- *   but jumps to corresponding `after` hook
- * - Failed `before each` hook skips remaining tests in a
- *   suite and jumps to corresponding `after each` hook,
- *   which is run only once
- * - Failed `after` hook does not alter execution order
- * - Failed `after each` hook skips remaining tests in a
- *   suite and subsuites, but executes other `after each`
- *   hooks
- *
- * @private
- * @param {Hook} hook
- * @param {Error} err
- */
-Runner.prototype.failHook = function(hook, err) {
-  hook.originalTitle = hook.originalTitle || hook.title;
-  if (hook.ctx && hook.ctx.currentTest) {
-    hook.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);
-};
-
 /**
  * Run hook `name` callbacks and then invoke `fn()`.
  *
@@ -462,13 +439,15 @@ Runner.prototype.hook = function(name, fn) {
       hook.ctx.currentTest = self.test;
     }
 
+    setHookTitle(hook);
+
     hook.allowUncaught = self.allowUncaught;
 
     self.emit(constants.EVENT_HOOK_BEGIN, hook);
 
     if (!hook.listeners('error').length) {
       self._addEventListener(hook, 'error', function(err) {
-        self.failHook(hook, err);
+        self.fail(hook, err);
       });
     }
 
@@ -502,18 +481,35 @@ Runner.prototype.hook = function(name, fn) {
         } else {
           hook.pending = false;
           var errForbid = createUnsupportedError('`this.skip` forbidden');
-          self.failHook(hook, errForbid);
+          self.fail(hook, errForbid);
           return fn(errForbid);
         }
       } else if (err) {
-        self.failHook(hook, err);
+        self.fail(hook, err);
         // stop executing hooks, notify callee of hook err
         return fn(err);
       }
       self.emit(constants.EVENT_HOOK_END, hook);
       delete hook.ctx.currentTest;
+      setHookTitle(hook);
       next(++i);
     });
+
+    function setHookTitle(hook) {
+      hook.originalTitle = hook.originalTitle || hook.title;
+      if (hook.ctx && hook.ctx.currentTest) {
+        hook.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);
+      }
+    }
   }
 
   Runner.immediately(function() {

package/lib/suite.js

@@ -2,6 +2,7 @@
 
 /**
  * Module dependencies.
+ * @private
  */
 var EventEmitter = require('events').EventEmitter;
 var Hook = require('./hook');

package/lib/utils.js

@@ -9,14 +9,9 @@
  * Module dependencies.
  */
 
-var fs = require('fs');
 var path = require('path');
 var util = require('util');
-var glob = require('glob');
 var he = require('he');
-var errors = require('./errors');
-var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;
-var createMissingArgumentError = errors.createMissingArgumentError;
 
 var assign = (exports.assign = require('object.assign').getPolyfill());
 
@@ -96,67 +91,6 @@ exports.clean = function(str) {
   return str.trim();
 };
 
-/**
- * Parse the given `qs`.
- *
- * @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;
-    }, {});
-};
-
-/**
- * Highlight the given string of `js`.
- *
- * @private
- * @param {string} js
- * @return {string}
- */
-function highlight(js) {
-  return js
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/\/\/(.*)/gm, '<span class="comment">//$1</span>')
-    .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>'
-    );
-}
-
-/**
- * Highlight the contents of tag `name`.
- *
- * @private
- * @param {string} 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);
-  }
-};
-
 /**
  * If a value could have properties, and has none, this function is called,
  * which returns a string representation of the empty value.
@@ -444,140 +378,6 @@ exports.canonicalize = function canonicalize(value, stack, typeHint) {
   return canonicalizedObj;
 };
 
-/**
- * Determines if pathname has a matching file extension.
- *
- * @private
- * @param {string} pathname - Pathname to check for match.
- * @param {string[]} exts - List of file extensions (sans period).
- * @return {boolean} whether file extension matches.
- * @example
- * hasMatchingExtname('foo.html', ['js', 'css']); // => false
- */
-function hasMatchingExtname(pathname, exts) {
-  var suffix = path.extname(pathname).slice(1);
-  return exts.some(function(element) {
-    return suffix === element;
-  });
-}
-
-/**
- * Determines if pathname would be a "hidden" file (or directory) on UN*X.
- *
- * @description
- * On UN*X, pathnames beginning with a full stop (aka dot) are hidden during
- * typical usage. Dotfiles, plain-text configuration files, are prime examples.
- *
- * @see {@link http://xahlee.info/UnixResource_dir/writ/unix_origin_of_dot_filename.html|Origin of Dot File Names}
- *
- * @private
- * @param {string} pathname - Pathname to check for match.
- * @return {boolean} whether pathname would be considered a hidden file.
- * @example
- * isHiddenOnUnix('.profile'); // => true
- */
-function isHiddenOnUnix(pathname) {
-  return path.basename(pathname)[0] === '.';
-}
-
-/**
- * Lookup file names at the given `path`.
- *
- * @description
- * Filenames are returned in _traversal_ order by the OS/filesystem.
- * **Make no assumption that the names will be sorted in any fashion.**
- *
- * @public
- * @param {string} filepath - Base path to start searching from.
- * @param {string[]} [extensions=[]] - File extensions to look for.
- * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
- * @return {string[]} An array of paths.
- * @throws {Error} if no files match pattern.
- * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
- */
-exports.lookupFiles = function lookupFiles(filepath, extensions, recursive) {
-  extensions = extensions || [];
-  recursive = recursive || false;
-  var files = [];
-  var stat;
-
-  if (!fs.existsSync(filepath)) {
-    var pattern;
-    if (glob.hasMagic(filepath)) {
-      // Handle glob as is without extensions
-      pattern = filepath;
-    } else {
-      // glob pattern e.g. 'filepath+(.js|.ts)'
-      var strExtensions = extensions
-        .map(function(v) {
-          return '.' + v;
-        })
-        .join('|');
-      pattern = filepath + '+(' + strExtensions + ')';
-    }
-    files = glob.sync(pattern, {nodir: true});
-    if (!files.length) {
-      throw createNoFilesMatchPatternError(
-        'Cannot find any files matching pattern ' + exports.dQuote(filepath),
-        filepath
-      );
-    }
-    return files;
-  }
-
-  // Handle file
-  try {
-    stat = fs.statSync(filepath);
-    if (stat.isFile()) {
-      return filepath;
-    }
-  } catch (err) {
-    // ignore error
-    return;
-  }
-
-  // Handle directory
-  fs.readdirSync(filepath).forEach(function(dirent) {
-    var pathname = path.join(filepath, dirent);
-    var stat;
-
-    try {
-      stat = fs.statSync(pathname);
-      if (stat.isDirectory()) {
-        if (recursive) {
-          files = files.concat(lookupFiles(pathname, extensions, recursive));
-        }
-        return;
-      }
-    } catch (err) {
-      // ignore error
-      return;
-    }
-    if (!extensions.length) {
-      throw createMissingArgumentError(
-        util.format(
-          'Argument %s required when argument %s is a directory',
-          exports.sQuote('extensions'),
-          exports.sQuote('filepath')
-        ),
-        'extensions',
-        'array'
-      );
-    }
-
-    if (
-      !stat.isFile() ||
-      !hasMatchingExtname(pathname, extensions) ||
-      isHiddenOnUnix(pathname)
-    ) {
-      return;
-    }
-    files.push(pathname);
-  });
-
-  return files;
-};
-
 /**
  * process.emitWarning or a polyfill
  * @see https://nodejs.org/api/process.html#process_process_emitwarning_warning_options
@@ -708,7 +508,7 @@ exports.isPromise = function isPromise(value) {
  * 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.
+ * @param {number[]} range - Two element array specifying [min, max] range.
  * @returns {number} clamped value
  */
 exports.clamp = function clamp(value, range) {
@@ -768,9 +568,9 @@ exports.noop = function() {};
  * doesn't support it. Recommended for use in Mocha's public APIs.
  *
  * @public
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map|MDN:Map}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map#Custom_and_Null_objects|MDN:Map}
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/create#Custom_and_Null_objects|MDN:Object.create - Custom objects}
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign|MDN:Object.assign}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/assign#Custom_and_Null_objects|MDN:Object.assign}
  * @param {...*} [obj] - Arguments to `Object.assign()`.
  * @returns {Object} An object with no prototype, having `...obj` properties
  */
@@ -804,7 +604,7 @@ exports.defineConstants = function(obj) {
  * Whether current version of Node support ES modules
  *
  * @description
- * Versions prior to 10 did not support ES Modules, and version 10 has an old incompatibile version of ESM.
+ * Versions prior to 10 did not support ES Modules, and version 10 has an old incompatible version of ESM.
  * This function returns whether Node.JS has ES Module supports that is compatible with Mocha's needs,
  * which is version >=12.11.
  *