mocha 6.2.1 → 7.0.0

package/lib/mocha.js

@@ -69,28 +69,26 @@ exports.Test = require('./test');
  * @param {boolean} [options.allowUncaught] - Propagate uncaught errors?
  * @param {boolean} [options.asyncOnly] - Force `done` callback or promise?
  * @param {boolean} [options.bail] - Bail after first test failure?
- * @param {boolean} [options.checkLeaks] - If true, check leaks.
+ * @param {boolean} [options.checkLeaks] - Check for global variable leaks?
+ * @param {boolean} [options.color] - Color TTY output from reporter?
  * @param {boolean} [options.delay] - Delay root suite execution?
- * @param {boolean} [options.enableTimeouts] - Enable timeouts?
+ * @param {boolean} [options.diff] - Show diff on failure?
  * @param {string} [options.fgrep] - Test filter given string.
  * @param {boolean} [options.forbidOnly] - Tests marked `only` fail the suite?
  * @param {boolean} [options.forbidPending] - Pending tests fail the suite?
- * @param {boolean} [options.fullStackTrace] - Full stacktrace upon failure?
+ * @param {boolean} [options.fullTrace] - Full stacktrace upon failure?
  * @param {string[]} [options.global] - Variables expected in global scope.
  * @param {RegExp|string} [options.grep] - Test filter given regular expression.
  * @param {boolean} [options.growl] - Enable desktop notifications?
- * @param {boolean} [options.hideDiff] - Suppress diffs from failures?
- * @param {boolean} [options.ignoreLeaks] - Ignore global leaks?
+ * @param {boolean} [options.inlineDiffs] - Display inline diffs?
  * @param {boolean} [options.invert] - Invert test filter matches?
  * @param {boolean} [options.noHighlighting] - Disable syntax highlighting?
- * @param {string} [options.reporter] - Reporter name.
+ * @param {string|constructor} [options.reporter] - Reporter name or constructor.
  * @param {Object} [options.reporterOption] - Reporter settings object.
  * @param {number} [options.retries] - Number of times to retry failed tests.
  * @param {number} [options.slow] - Slow threshold value.
  * @param {number|string} [options.timeout] - Timeout threshold value.
  * @param {string} [options.ui] - Interface name.
- * @param {boolean} [options.color] - Color TTY output from reporter?
- * @param {boolean} [options.useInlineDiffs] - Use inline diffs?
  */
 function Mocha(options) {
   options = utils.assign({}, mocharc, options || {});
@@ -99,35 +97,12 @@ function Mocha(options) {
   // root suite
   this.suite = new exports.Suite('', new exports.Context(), true);
 
-  if ('useColors' in options) {
-    utils.deprecate(
-      'useColors is DEPRECATED and will be removed from a future version of Mocha. Instead, use the "color" option'
-    );
-    options.color = 'color' in options ? options.color : options.useColors;
-  }
-
-  // Globals are passed in as options.global, with options.globals for backward compatibility.
-  options.globals = options.global || options.globals || [];
-  delete options.global;
-
   this.grep(options.grep)
     .fgrep(options.fgrep)
     .ui(options.ui)
-    .bail(options.bail)
-    .reporter(options.reporter, options.reporterOptions)
-    .useColors(options.color)
+    .reporter(options.reporter, options.reporterOption)
     .slow(options.slow)
-    .useInlineDiffs(options.inlineDiffs)
-    .globals(options.globals);
-
-  if ('enableTimeouts' in options) {
-    utils.deprecate(
-      'enableTimeouts is DEPRECATED and will be removed from a future version of Mocha. Instead, use "timeout: false" to disable timeouts.'
-    );
-    if (options.enableTimeouts === false) {
-      this.timeout(0);
-    }
-  }
+    .global(options.global);
 
   // this guard exists because Suite#timeout does not consider `undefined` to be valid input
   if (typeof options.timeout !== 'undefined') {
@@ -138,19 +113,19 @@ function Mocha(options) {
     this.retries(options.retries);
   }
 
-  if ('diff' in options) {
-    this.hideDiff(!options.diff);
-  }
-
   [
     'allowUncaught',
     'asyncOnly',
+    'bail',
     'checkLeaks',
+    'color',
     'delay',
+    'diff',
     'forbidOnly',
     'forbidPending',
     'fullTrace',
     'growl',
+    'inlineDiffs',
     'invert'
   ].forEach(function(opt) {
     if (options[opt]) {
@@ -163,16 +138,13 @@ function Mocha(options) {
  * Enables or disables bailing on the first failure.
  *
  * @public
- * @see {@link https://mochajs.org/#-b---bail|CLI option}
+ * @see [CLI option](../#-bail-b)
  * @param {boolean} [bail=true] - Whether to bail on first error.
  * @returns {Mocha} this
  * @chainable
  */
 Mocha.prototype.bail = function(bail) {
-  if (!arguments.length) {
-    bail = true;
-  }
-  this.suite.bail(bail);
+  this.suite.bail(bail !== false);
   return this;
 };
 
@@ -184,7 +156,7 @@ Mocha.prototype.bail = function(bail) {
  * Useful for generic setup code that must be included within test suite.
  *
  * @public
- * @see {@link https://mochajs.org/#--file-file|CLI option}
+ * @see [CLI option](../#-file-filedirectoryglob)
  * @param {string} file - Pathname of file to be loaded.
  * @returns {Mocha} this
  * @chainable
@@ -198,8 +170,8 @@ Mocha.prototype.addFile = function(file) {
  * Sets reporter to `reporter`, defaults to "spec".
  *
  * @public
- * @see {@link https://mochajs.org/#-r---reporter-name|CLI option}
- * @see {@link https://mochajs.org/#reporters|Reporters}
+ * @see [CLI option](../#-reporter-name-r-name)
+ * @see [Reporters](../#reporters)
  * @param {String|Function} reporter - Reporter name or constructor.
  * @param {Object} [reporterOptions] - Options used to configure the reporter.
  * @returns {Mocha} this
@@ -257,6 +229,8 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
     }
     this._reporter = _reporter;
   }
+  this.options.reporterOption = reporterOptions;
+  // alias option name is used in public reporters xunit/tap/progress
   this.options.reporterOptions = reporterOptions;
   return this;
 };
@@ -265,8 +239,8 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
  * Sets test UI `name`, defaults to "bdd".
  *
  * @public
- * @see {@link https://mochajs.org/#-u---ui-name|CLI option}
- * @see {@link https://mochajs.org/#interfaces|Interface DSLs}
+ * @see [CLI option](../#-ui-name-u-name)
+ * @see [Interface DSLs](../#interfaces)
  * @param {string|Function} [ui=bdd] - Interface name or class.
  * @returns {Mocha} this
  * @chainable
@@ -359,8 +333,6 @@ Mocha.unloadFile = function(file) {
  * <strong>Intended for consumers &mdash; not used internally</strong>
  *
  * @public
- * @see {@link Mocha.unloadFile}
- * @see {@link Mocha#loadFiles}
  * @see {@link Mocha#run}
  * @returns {Mocha} this
  * @chainable
@@ -404,7 +376,7 @@ Mocha.prototype.fgrep = function(str) {
  * <strong>Previous filter value will be overwritten on each call!</strong>
  *
  * @public
- * @see {@link https://mochajs.org/#-g---grep-pattern|CLI option}
+ * @see [CLI option](../#-grep-regexp-g-regexp)
  * @see {@link Mocha#fgrep}
  * @see {@link Mocha#invert}
  * @param {RegExp|String} re - Regular expression used to select tests.
@@ -455,32 +427,32 @@ Mocha.prototype.invert = function() {
 /**
  * Enables or disables ignoring global leaks.
  *
+ * @deprecated since v7.0.0
  * @public
  * @see {@link Mocha#checkLeaks}
- * @param {boolean} ignoreLeaks - Whether to ignore global leaks.
+ * @param {boolean} [ignoreLeaks=false] - Whether to ignore global leaks.
  * @return {Mocha} this
  * @chainable
- * @example
- *
- * // Ignore global leaks
- * mocha.ignoreLeaks(true);
  */
 Mocha.prototype.ignoreLeaks = function(ignoreLeaks) {
-  this.options.ignoreLeaks = Boolean(ignoreLeaks);
+  utils.deprecate(
+    '"ignoreLeaks()" is DEPRECATED, please use "checkLeaks()" instead.'
+  );
+  this.options.checkLeaks = !ignoreLeaks;
   return this;
 };
 
 /**
- * Enables checking for global variables leaked while running tests.
+ * Enables or disables checking for global variables leaked while running tests.
  *
  * @public
- * @see {@link https://mochajs.org/#--check-leaks|CLI option}
- * @see {@link Mocha#ignoreLeaks}
+ * @see [CLI option](../#-check-leaks)
+ * @param {boolean} [checkLeaks=true] - Whether to check for global variable leaks.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.checkLeaks = function() {
-  this.options.ignoreLeaks = false;
+Mocha.prototype.checkLeaks = function(checkLeaks) {
+  this.options.checkLeaks = checkLeaks !== false;
   return this;
 };
 
@@ -488,11 +460,13 @@ Mocha.prototype.checkLeaks = function() {
  * Displays full stack trace upon test failure.
  *
  * @public
+ * @see [CLI option](../#-full-trace)
+ * @param {boolean} [fullTrace=true] - Whether to print full stacktrace upon failure.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.fullTrace = function() {
-  this.options.fullStackTrace = true;
+Mocha.prototype.fullTrace = function(fullTrace) {
+  this.options.fullTrace = fullTrace !== false;
   return this;
 };
 
@@ -500,8 +474,7 @@ Mocha.prototype.fullTrace = function() {
  * Enables desktop notification support if prerequisite software installed.
  *
  * @public
- * @see {@link Mocha#isGrowlCapable}
- * @see {@link Mocha#_growl}
+ * @see [CLI option](../#-growl-g)
  * @return {Mocha} this
  * @chainable
  */
@@ -544,65 +517,121 @@ Mocha.prototype._growl = growl.notify;
  * Specifies whitelist of variable names to be expected in global scope.
  *
  * @public
- * @see {@link https://mochajs.org/#-global-variable-name|CLI option}
+ * @see [CLI option](../#-global-variable-name)
  * @see {@link Mocha#checkLeaks}
- * @param {String[]|String} globals - Accepted global variable name(s).
+ * @param {String[]|String} global - Accepted global variable name(s).
  * @return {Mocha} this
  * @chainable
  * @example
  *
  * // Specify variables to be expected in global scope
- * mocha.globals(['jQuery', 'MyLib']);
+ * mocha.global(['jQuery', 'MyLib']);
  */
-Mocha.prototype.globals = function(globals) {
-  this.options.globals = this.options.globals
-    .concat(globals)
+Mocha.prototype.global = function(global) {
+  this.options.global = (this.options.global || [])
+    .concat(global)
     .filter(Boolean)
     .filter(function(elt, idx, arr) {
       return arr.indexOf(elt) === idx;
     });
   return this;
 };
+// for backwards compability, 'globals' is an alias of 'global'
+Mocha.prototype.globals = Mocha.prototype.global;
 
 /**
  * Enables or disables TTY color output by screen-oriented reporters.
  *
+ * @deprecated since v7.0.0
  * @public
+ * @see {@link Mocha#color}
  * @param {boolean} colors - Whether to enable color output.
  * @return {Mocha} this
  * @chainable
  */
 Mocha.prototype.useColors = function(colors) {
+  utils.deprecate('"useColors()" is DEPRECATED, please use "color()" instead.');
   if (colors !== undefined) {
-    this.options.useColors = colors;
+    this.options.color = colors;
   }
   return this;
 };
 
+/**
+ * Enables or disables TTY color output by screen-oriented reporters.
+ *
+ * @public
+ * @see [CLI option](../#-color-c-colors)
+ * @param {boolean} [color=true] - Whether to enable color output.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.color = function(color) {
+  this.options.color = color !== false;
+  return this;
+};
+
 /**
  * Determines if reporter should use inline diffs (rather than +/-)
  * in test failure output.
  *
+ * @deprecated since v7.0.0
  * @public
- * @param {boolean} inlineDiffs - Whether to use inline diffs.
+ * @see {@link Mocha#inlineDiffs}
+ * @param {boolean} [inlineDiffs=false] - Whether to use inline diffs.
  * @return {Mocha} this
  * @chainable
  */
 Mocha.prototype.useInlineDiffs = function(inlineDiffs) {
-  this.options.useInlineDiffs = inlineDiffs !== undefined && inlineDiffs;
+  utils.deprecate(
+    '"useInlineDiffs()" is DEPRECATED, please use "inlineDiffs()" instead.'
+  );
+  this.options.inlineDiffs = inlineDiffs !== undefined && inlineDiffs;
+  return this;
+};
+
+/**
+ * Enables or disables reporter to use inline diffs (rather than +/-)
+ * in test failure output.
+ *
+ * @public
+ * @see [CLI option](../#-inline-diffs)
+ * @param {boolean} [inlineDiffs=true] - Whether to use inline diffs.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.inlineDiffs = function(inlineDiffs) {
+  this.options.inlineDiffs = inlineDiffs !== false;
   return this;
 };
 
 /**
  * Determines if reporter should include diffs in test failure output.
  *
+ * @deprecated since v7.0.0
  * @public
- * @param {boolean} hideDiff - Whether to hide diffs.
+ * @see {@link Mocha#diff}
+ * @param {boolean} [hideDiff=false] - Whether to hide diffs.
  * @return {Mocha} this
  * @chainable
  */
 Mocha.prototype.hideDiff = function(hideDiff) {
-  this.options.hideDiff = hideDiff !== undefined && hideDiff;
+  utils.deprecate('"hideDiff()" is DEPRECATED, please use "diff()" instead.');
+  this.options.diff = !(hideDiff === true);
+  return this;
+};
+
+/**
+ * Enables or disables reporter to include diff in test failure output.
+ *
+ * @public
+ * @see [CLI option](../#-diff)
+ * @param {boolean} [diff=true] - Whether to show diff on failure.
+ * @return {Mocha} this
+ * @chainable
+ */
+Mocha.prototype.diff = function(diff) {
+  this.options.diff = diff !== false;
   return this;
 };
 
@@ -615,9 +644,8 @@ Mocha.prototype.hideDiff = function(hideDiff) {
  * If the value is `0`, timeouts will be disabled.
  *
  * @public
- * @see {@link https://mochajs.org/#-t---timeout-ms|CLI option}
- * @see {@link https://mochajs.org/#--no-timeouts|CLI option}
- * @see {@link https://mochajs.org/#timeouts|Timeouts}
+ * @see [CLI option](../#-timeout-ms-t-ms)
+ * @see [Timeouts](../#timeouts)
  * @see {@link Mocha#enableTimeouts}
  * @param {number|string} msecs - Timeout threshold value.
  * @return {Mocha} this
@@ -640,7 +668,8 @@ Mocha.prototype.timeout = function(msecs) {
  * Sets the number of times to retry failed tests.
  *
  * @public
- * @see {@link https://mochajs.org/#retry-tests|Retry Tests}
+ * @see [CLI option](../#-retries-n)
+ * @see [Retry Tests](../#retry-tests)
  * @param {number} retry - Number of times to retry failed tests.
  * @return {Mocha} this
  * @chainable
@@ -658,7 +687,7 @@ Mocha.prototype.retries = function(n) {
  * Sets slowness threshold value.
  *
  * @public
- * @see {@link https://mochajs.org/#-s---slow-ms|CLI option}
+ * @see [CLI option](../#-slow-ms-s-ms)
  * @param {number} msecs - Slowness threshold value.
  * @return {Mocha} this
  * @chainable
@@ -680,8 +709,7 @@ Mocha.prototype.slow = function(msecs) {
  * Enables or disables timeouts.
  *
  * @public
- * @see {@link https://mochajs.org/#-t---timeout-ms|CLI option}
- * @see {@link https://mochajs.org/#--no-timeouts|CLI option}
+ * @see [CLI option](../#-timeout-ms-t-ms)
  * @param {boolean} enableTimeouts - Whether to enable timeouts.
  * @return {Mocha} this
  * @chainable
@@ -697,11 +725,13 @@ Mocha.prototype.enableTimeouts = function(enableTimeouts) {
  * Forces all tests to either accept a `done` callback or return a promise.
  *
  * @public
+ * @see [CLI option](../#-async-only-a)
+ * @param {boolean} [asyncOnly=true] - Wether to force `done` callback or promise.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.asyncOnly = function() {
-  this.options.asyncOnly = true;
+Mocha.prototype.asyncOnly = function(asyncOnly) {
+  this.options.asyncOnly = asyncOnly !== false;
   return this;
 };
 
@@ -718,14 +748,16 @@ Mocha.prototype.noHighlighting = function() {
 };
 
 /**
- * Enables uncaught errors to propagate (in browser).
+ * Enables or disables uncaught errors to propagate.
  *
  * @public
+ * @see [CLI option](../#-allow-uncaught)
+ * @param {boolean} [allowUncaught=true] - Whether to propagate uncaught errors.
  * @return {Mocha} this
  * @chainable
  */
-Mocha.prototype.allowUncaught = function() {
-  this.options.allowUncaught = true;
+Mocha.prototype.allowUncaught = function(allowUncaught) {
+  this.options.allowUncaught = allowUncaught !== false;
   return this;
 };
 
@@ -737,7 +769,7 @@ Mocha.prototype.allowUncaught = function() {
  * Used to perform asynch operations before any suites are run.
  *
  * @public
- * @see {@link https://mochajs.org/#delayed-root-suite|delayed root suite}
+ * @see [delayed root suite](../#delayed-root-suite)
  * @returns {Mocha} this
  * @chainable
  */
@@ -750,11 +782,13 @@ Mocha.prototype.delay = function delay() {
  * Causes tests marked `only` to fail the suite.
  *
  * @public
+ * @see [CLI option](../#-forbid-only)
+ * @param {boolean} [forbidOnly=true] - Whether tests marked `only` fail the suite.
  * @returns {Mocha} this
  * @chainable
  */
-Mocha.prototype.forbidOnly = function() {
-  this.options.forbidOnly = true;
+Mocha.prototype.forbidOnly = function(forbidOnly) {
+  this.options.forbidOnly = forbidOnly !== false;
   return this;
 };
 
@@ -762,11 +796,13 @@ Mocha.prototype.forbidOnly = function() {
  * Causes pending tests and tests marked `skip` to fail the suite.
  *
  * @public
+ * @see [CLI option](../#-forbid-pending)
+ * @param {boolean} [forbidPending=true] - Whether pending tests fail the suite.
  * @returns {Mocha} this
  * @chainable
  */
-Mocha.prototype.forbidPending = function() {
-  this.options.forbidPending = true;
+Mocha.prototype.forbidPending = function(forbidPending) {
+  this.options.forbidPending = forbidPending !== false;
   return this;
 };
 
@@ -800,7 +836,6 @@ Object.defineProperty(Mocha.prototype, 'version', {
  * the cache first!
  *
  * @public
- * @see {@link Mocha#loadFiles}
  * @see {@link Mocha#unloadFiles}
  * @see {@link Runner#run}
  * @param {DoneCB} [fn] - Callback invoked when test execution completed.
@@ -816,8 +851,8 @@ Mocha.prototype.run = function(fn) {
   var runner = new exports.Runner(suite, options.delay);
   createStatsCollector(runner);
   var reporter = new this._reporter(runner, options);
-  runner.ignoreLeaks = options.ignoreLeaks !== false;
-  runner.fullStackTrace = options.fullStackTrace;
+  runner.checkLeaks = options.checkLeaks === true;
+  runner.fullStackTrace = options.fullTrace;
   runner.asyncOnly = options.asyncOnly;
   runner.allowUncaught = options.allowUncaught;
   runner.forbidOnly = options.forbidOnly;
@@ -825,17 +860,17 @@ Mocha.prototype.run = function(fn) {
   if (options.grep) {
     runner.grep(options.grep, options.invert);
   }
-  if (options.globals) {
-    runner.globals(options.globals);
+  if (options.global) {
+    runner.globals(options.global);
   }
   if (options.growl) {
     this._growl(runner);
   }
-  if (options.useColors !== undefined) {
-    exports.reporters.Base.useColors = options.useColors;
+  if (options.color !== undefined) {
+    exports.reporters.Base.useColors = options.color;
   }
-  exports.reporters.Base.inlineDiffs = options.useInlineDiffs;
-  exports.reporters.Base.hideDiff = options.hideDiff;
+  exports.reporters.Base.inlineDiffs = options.inlineDiffs;
+  exports.reporters.Base.hideDiff = !options.diff;
 
   function done(failures) {
     fn = fn || utils.noop;

package/lib/mocharc.json

@@ -6,5 +6,6 @@
   "reporter": "spec",
   "slow": 75,
   "timeout": 2000,
-  "ui": "bdd"
+  "ui": "bdd",
+  "watch-ignore": ["node_modules", ".git"]
 }

package/lib/reporters/base.js

@@ -154,14 +154,14 @@ exports.cursor = {
   }
 };
 
-function showDiff(err) {
+var showDiff = (exports.showDiff = function(err) {
   return (
     err &&
     err.showDiff !== false &&
     sameType(err.actual, err.expected) &&
     err.expected !== undefined
   );
-}
+});
 
 function stringifyDiffObjs(err) {
   if (!utils.isString(err.actual) || !utils.isString(err.expected)) {
@@ -182,9 +182,19 @@ function stringifyDiffObjs(err) {
  * @return {string} Diff
  */
 var generateDiff = (exports.generateDiff = function(actual, expected) {
-  return exports.inlineDiffs
-    ? inlineDiff(actual, expected)
-    : unifiedDiff(actual, expected);
+  try {
+    return exports.inlineDiffs
+      ? inlineDiff(actual, expected)
+      : unifiedDiff(actual, expected);
+  } catch (err) {
+    var msg =
+      '\n      ' +
+      color('diff added', '+ expected') +
+      ' ' +
+      color('diff removed', '- actual:  failed to generate Mocha diff') +
+      '\n';
+    return msg;
+  }
 });
 
 /**
@@ -197,6 +207,7 @@ var generateDiff = (exports.generateDiff = function(actual, expected) {
  *     Error property
  */
 exports.list = function(failures) {
+  var multipleErr, multipleTest;
   Base.consoleLog();
   failures.forEach(function(test, i) {
     // format
@@ -207,7 +218,16 @@ exports.list = function(failures) {
 
     // msg
     var msg;
-    var err = test.err;
+    var err;
+    if (test.err && test.err.multiple) {
+      if (multipleTest !== test) {
+        multipleTest = test;
+        multipleErr = [test.err].concat(test.err.multiple);
+      }
+      err = multipleErr.shift();
+    } else {
+      err = test.err;
+    }
     var message;
     if (err.message && typeof err.message.toString === 'function') {
       message = err.message + '';
@@ -298,7 +318,12 @@ function Base(runner, options) {
     if (showDiff(err)) {
       stringifyDiffObjs(err);
     }
-    test.err = err;
+    // more than one error per test
+    if (test.err && err instanceof Error) {
+      test.err.multiple = (test.err.multiple || []).concat(err);
+    } else {
+      test.err = err;
+    }
     failures.push(test);
   });
 }
@@ -307,7 +332,7 @@ function Base(runner, options) {
  * Outputs common epilogue used by many of the bundled reporters.
  *
  * @public
- * @memberof Mocha.reporters.Base
+ * @memberof Mocha.reporters
  */
 Base.prototype.epilogue = function() {
   var stats = this.stats;

package/lib/reporters/html.js

@@ -357,8 +357,8 @@ function hideSuitesWithout(classname) {
  */
 function unhide() {
   var els = document.getElementsByClassName('suite hidden');
-  for (var i = 0; i < els.length; ++i) {
-    els[i].className = els[i].className.replace('suite hidden', 'suite');
+  while (els.length > 0) {
+    els[0].className = els[0].className.replace('suite hidden', 'suite');
   }
 }
 

package/lib/reporters/xunit.js

@@ -163,9 +163,9 @@ XUnit.prototype.test = function(test) {
   if (test.state === STATE_FAILED) {
     var err = test.err;
     var diff =
-      Base.hideDiff || !err.actual || !err.expected
-        ? ''
-        : '\n' + Base.generateDiff(err.actual, err.expected);
+      !Base.hideDiff && Base.showDiff(err)
+        ? '\n' + Base.generateDiff(err.actual, err.expected)
+        : '';
     this.write(
       tag(
         'testcase',