mocha 6.2.2 → 7.0.1

package/lib/mocha.js

@@ -69,18 +69,18 @@ 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|constructor} [options.reporter] - Reporter name or constructor.
@@ -89,8 +89,6 @@ exports.Test = require('./test');
  * @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,15 @@ 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 || options.reporterOptions // reporterOptions was previously the only way to specify options to reporter
+    )
     .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 +116,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 +141,13 @@ function Mocha(options) {
  * Enables or disables bailing on the first failure.
  *
  * @public
- * @see {@link /#-bail-b|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 +159,7 @@ Mocha.prototype.bail = function(bail) {
  * Useful for generic setup code that must be included within test suite.
  *
  * @public
- * @see {@link /#-file-filedirectoryglob|CLI option}
+ * @see [CLI option](../#-file-filedirectoryglob)
  * @param {string} file - Pathname of file to be loaded.
  * @returns {Mocha} this
  * @chainable
@@ -198,8 +173,8 @@ Mocha.prototype.addFile = function(file) {
  * Sets reporter to `reporter`, defaults to "spec".
  *
  * @public
- * @see {@link /#-reporter-name-r-name|CLI option}
- * @see {@link /#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 +232,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 +242,8 @@ Mocha.prototype.reporter = function(reporter, reporterOptions) {
  * Sets test UI `name`, defaults to "bdd".
  *
  * @public
- * @see {@link /#-ui-name-u-name|CLI option}
- * @see {@link /#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 +336,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 +379,7 @@ Mocha.prototype.fgrep = function(str) {
  * <strong>Previous filter value will be overwritten on each call!</strong>
  *
  * @public
- * @see {@link /#grep-regexp-g-regexp|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 +430,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 /#-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 +463,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 +477,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 +520,121 @@ Mocha.prototype._growl = growl.notify;
  * Specifies whitelist of variable names to be expected in global scope.
  *
  * @public
- * @see {@link /#-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,8 +647,8 @@ Mocha.prototype.hideDiff = function(hideDiff) {
  * If the value is `0`, timeouts will be disabled.
  *
  * @public
- * @see {@link /#-timeout-ms-t-ms|CLI option}
- * @see {@link /#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
@@ -639,7 +671,8 @@ Mocha.prototype.timeout = function(msecs) {
  * Sets the number of times to retry failed tests.
  *
  * @public
- * @see {@link /#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
@@ -657,7 +690,7 @@ Mocha.prototype.retries = function(n) {
  * Sets slowness threshold value.
  *
  * @public
- * @see {@link /#-slow-ms-s-ms|CLI option}
+ * @see [CLI option](../#-slow-ms-s-ms)
  * @param {number} msecs - Slowness threshold value.
  * @return {Mocha} this
  * @chainable
@@ -679,7 +712,7 @@ Mocha.prototype.slow = function(msecs) {
  * Enables or disables timeouts.
  *
  * @public
- * @see {@link /#-timeout-ms-t-ms|CLI option}
+ * @see [CLI option](../#-timeout-ms-t-ms)
  * @param {boolean} enableTimeouts - Whether to enable timeouts.
  * @return {Mocha} this
  * @chainable
@@ -695,11 +728,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;
 };
 
@@ -716,14 +751,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;
 };
 
@@ -735,7 +772,7 @@ Mocha.prototype.allowUncaught = function() {
  * Used to perform asynch operations before any suites are run.
  *
  * @public
- * @see {@link /#delayed-root-suite|delayed root suite}
+ * @see [delayed root suite](../#delayed-root-suite)
  * @returns {Mocha} this
  * @chainable
  */
@@ -748,11 +785,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;
 };
 
@@ -760,11 +799,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;
 };
 
@@ -798,7 +839,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.
@@ -814,8 +854,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;
@@ -823,17 +863,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;
+  }
 });
 
 /**

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',

package/lib/runnable.js

@@ -135,7 +135,8 @@ Runnable.prototype.enableTimeouts = function(enabled) {
  * @public
  */
 Runnable.prototype.skip = function() {
-  throw new Pending('sync skip');
+  this.pending = true;
+  throw new Pending('sync skip; aborting execution');
 };
 
 /**
@@ -334,43 +335,45 @@ Runnable.prototype.run = function(fn) {
     fn(err);
   }
 
-  // for .resetTimeout()
+  // for .resetTimeout() and Runner#uncaught()
   this.callback = done;
 
+  if (this.fn && typeof this.fn.call !== 'function') {
+    done(
+      new TypeError(
+        'A runnable must be passed a function as its second argument.'
+      )
+    );
+    return;
+  }
+
   // explicit async with `done` argument
   if (this.async) {
     this.resetTimeout();
 
     // allows skip() to be used in an explicit async context
     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
-      // the failure.
+      this.pending = true;
+      done();
+      // halt execution, the uncaught handler will ignore the failure.
       throw new Pending('async skip; aborting execution');
     };
 
-    if (this.allowUncaught) {
-      return callFnAsync(this.fn);
-    }
     try {
       callFnAsync(this.fn);
     } catch (err) {
+      // handles async runnables which actually run synchronously
       emitted = true;
+      if (err instanceof Pending) {
+        return; // done() is already called in this.skip()
+      } else if (this.allowUncaught) {
+        throw err;
+      }
       done(Runnable.toValueOrError(err));
     }
     return;
   }
 
-  if (this.allowUncaught) {
-    if (this.isPending()) {
-      done();
-    } else {
-      callFn(this.fn);
-    }
-    return;
-  }
-
   // sync or promise-returning
   try {
     if (this.isPending()) {
@@ -380,6 +383,11 @@ Runnable.prototype.run = function(fn) {
     }
   } catch (err) {
     emitted = true;
+    if (err instanceof Pending) {
+      return done();
+    } else if (this.allowUncaught) {
+      throw err;
+    }
     done(Runnable.toValueOrError(err));
   }