mocha - npm Package Compare versions

Comparing version 6.2.2 to 7.0.0

lib/cli/node-flags.js

@@ -17,3 +17,3 @@ 'use strict';
  */
-const debugFlags = new Set(['debug', 'debug-brk', 'inspect', 'inspect-brk']);
+const debugFlags = new Set(['inspect', 'inspect-brk']);
 
@@ -20,0 +20,0 @@ /**

lib/cli/one-and-dones.js

@@ -51,3 +51,3 @@ 'use strict';
    */
-  interfaces: () => {
+  'list-interfaces': () => {
     showKeys(Mocha.interfaces);
@@ -59,3 +59,3 @@ },
    */
-  reporters: () => {
+  'list-reporters': () => {
     showKeys(Mocha.reporters);
@@ -62,0 +62,0 @@ }

lib/cli/options.js

@@ -167,36 +167,2 @@ 'use strict';
 /**
- * Prepends options from run-control file to the command line arguments.
- *
- * @deprecated Deprecated in v6.0.0; This function is no longer used internally and will be removed in a future version.
- * @public
- * @alias module:lib/cli/options
- * @see {@link https://mochajs.org/#mochaopts|mocha.opts}
- */
-module.exports = function getOptions() {
-  deprecate(
-    'getOptions() is DEPRECATED and will be removed from a future version of Mocha.  Use loadOptions() instead'
-  );
-  if (process.argv.length === 3 && ONE_AND_DONE_ARGS.has(process.argv[2])) {
-    return;
-  }
-
-  const optsPath =
-    process.argv.indexOf('--opts') === -1
-      ? mocharc.opts
-      : process.argv[process.argv.indexOf('--opts') + 1];
-
-  try {
-    const options = parseMochaOpts(fs.readFileSync(optsPath, 'utf8'));
-
-    process.argv = process.argv
-      .slice(0, 2)
-      .concat(options.concat(process.argv.slice(2)));
-  } catch (ignore) {
-    // NOTE: should console.error() and throw the error
-  }
-
-  process.env.LOADED_MOCHA_OPTS = true;
-};
-
-/**
  * Given filepath in `args.opts`, attempt to load and parse a `mocha.opts` file.
@@ -235,2 +201,5 @@ * @param {Object} [args] - Arguments object
   if (mochaOpts) {
+    deprecate(
+      'Configuration via mocha.opts is DEPRECATED and will be removed from a future version of Mocha. Use RC files or package.json instead.'
+    );
     result = parse(parseMochaOpts(mochaOpts));
@@ -237,0 +206,0 @@ debug(`${filepath} parsed succesfully`);

lib/cli/run-helpers.js

@@ -121,3 +121,2 @@ 'use strict';
     extension = [],
-    ui = 'bdd',
     exit = false,
@@ -128,3 +127,5 @@ ignore = [],
     sort = false,
-    spec = []
+    spec = [],
+    watchFiles,
+    watchIgnore
   } = options;
@@ -142,3 +143,3 @@
   if (watch) {
-    watchRun(mocha, {ui}, fileCollectParams);
+    watchRun(mocha, {watchFiles, watchIgnore}, fileCollectParams);
   } else {
@@ -145,0 +146,0 @@ exports.singleRun(mocha, {exit}, fileCollectParams);

lib/cli/run-option-metadata.js

@@ -21,5 +21,7 @@ 'use strict';
     'ignore',
+    'reporter-option',
     'require',
-    'reporter-option',
-    'spec'
+    'spec',
+    'watch-files',
+    'watch-ignore'
   ],
@@ -40,7 +42,7 @@ boolean: [
     'inline-diffs',
-    'interfaces',
     'invert',
+    'list-interfaces',
+    'list-reporters',
     'no-colors',
     'recursive',
-    'reporters',
     'sort',
@@ -73,3 +75,2 @@ 'watch'
   color: ['c', 'colors'],
-  extension: ['watch-extensions'],
   fgrep: ['f'],
@@ -76,0 +77,0 @@ global: ['globals'],

lib/cli/run.js

@@ -41,3 +41,3 @@ 'use strict';
 
-exports.command = ['$0 [spec..]', 'debug [spec..]'];
+exports.command = ['$0 [spec..]', 'inspect'];
 
@@ -92,3 +92,3 @@ exports.describe = 'Run tests with Mocha';
         defaultDescription: 'js',
-        description: 'File extension(s) to load and/or watch',
+        description: 'File extension(s) to load',
         group: GROUPS.FILES,
@@ -152,6 +152,2 @@ requiresArg: true,
       },
-      interfaces: {
-        conflicts: Array.from(ONE_AND_DONE_ARGS),
-        description: 'List built-in user interfaces & exit'
-      },
       invert: {
@@ -161,2 +157,10 @@ description: 'Inverts --grep and --fgrep matches',
       },
+      'list-interfaces': {
+        conflicts: Array.from(ONE_AND_DONE_ARGS),
+        description: 'List built-in user interfaces & exit'
+      },
+      'list-reporters': {
+        conflicts: Array.from(ONE_AND_DONE_ARGS),
+        description: 'List built-in reporters & exit'
+      },
       'no-colors': {
@@ -169,3 +173,3 @@ description: 'Force-disable color output',
         default: defaults.opts,
-        description: 'Path to `mocha.opts`',
+        description: 'Path to `mocha.opts` (DEPRECATED)',
         group: GROUPS.CONFIG,
@@ -191,6 +195,2 @@ normalize: true,
       },
-      reporters: {
-        conflicts: Array.from(ONE_AND_DONE_ARGS),
-        description: 'List built-in reporters & exit'
-      },
       'reporter-option': {
@@ -250,2 +250,15 @@ coerce: opts =>
         group: GROUPS.FILES
+      },
+      'watch-files': {
+        description: 'List of paths or globs to watch',
+        group: GROUPS.FILES,
+        requiresArg: true,
+        coerce: list
+      },
+      'watch-ignore': {
+        description: 'List of paths or globs to exclude from watching',
+        group: GROUPS.FILES,
+        requiresArg: true,
+        coerce: list,
+        default: defaults['watch-ignore']
       }
@@ -252,0 +265,0 @@ })

lib/cli/watch-run.js

 'use strict';
 
-const utils = require('../utils');
+const path = require('path');
+const chokidar = require('chokidar');
 const Context = require('../context');
-const Mocha = require('../mocha');
 const collectFiles = require('./collect-files');
@@ -19,32 +19,84 @@
  * @param {Object} opts - Options
- * @param {string} opts.ui - User interface
+ * @param {string[]} [opts.watchFiles] - List of paths and patterns to
+ *   watch. If not provided all files with an extension included in
+ *   `fileColletionParams.extension` are watched. See first argument of
+ *   `chokidar.watch`.
+ * @param {string[]} opts.watchIgnore - List of paths and patterns to
+ *   exclude from watching. See `ignored` option of `chokidar`.
  * @param {Object} fileCollectParams - Parameters that control test
  *   file collection. See `lib/cli/collect-files.js`.
- * @param {string[]} fileCollectParams.extension - List of extensions to watch
+ * @param {string[]} fileCollectParams.extension - List of extensions
+ *   to watch if `opts.watchFiles` is not given.
  * @private
  */
-module.exports = (mocha, {ui}, fileCollectParams) => {
-  let runner;
-  const files = collectFiles(fileCollectParams);
+module.exports = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
+  if (!watchFiles) {
+    watchFiles = fileCollectParams.extension.map(ext => `**/*.${ext}`);
+  }
 
+  const watcher = chokidar.watch(watchFiles, {
+    ignored: watchIgnore,
+    ignoreInitial: true
+  });
+
+  const rerunner = createRerunner(mocha, () => {
+    getWatchedFiles(watcher).forEach(file => {
+      delete require.cache[file];
+    });
+    mocha.files = collectFiles(fileCollectParams);
+  });
+
+  watcher.on('ready', () => {
+    rerunner.run();
+  });
+
+  watcher.on('all', () => {
+    rerunner.scheduleRun();
+  });
+
   console.log();
   hideCursor();
+  process.on('exit', () => {
+    showCursor();
+  });
   process.on('SIGINT', () => {
     showCursor();
     console.log('\n');
-    // By UNIX/Posix convention this indicates that the process was
-    // killed by SIGINT which has portable number 2.
     process.exit(128 + 2);
   });
 
-  const watchFiles = utils.files(process.cwd(), fileCollectParams.extension);
-  let runAgain = false;
+  // Keyboard shortcut for restarting when "rs\n" is typed (ala Nodemon)
+  process.stdin.resume();
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', data => {
+    const str = data
+      .toString()
+      .trim()
+      .toLowerCase();
+    if (str === 'rs') rerunner.scheduleRun();
+  });
+};
 
-  const loadAndRun = () => {
+/**
+ * Create an object that allows you to rerun tests on the mocha
+ * instance. `beforeRun` is called everytime before `mocha.run()` is
+ * called.
+ *
+ * @param {Mocha} mocha - Mocha instance
+ * @param {function} beforeRun - Called just before `mocha.run()`
+ */
+const createRerunner = (mocha, beforeRun) => {
+  // Set to a `Runner` when mocha is running. Set to `null` when mocha is not
+  // running.
+  let runner = null;
+
+  let rerunScheduled = false;
+
+  const run = () => {
     try {
-      mocha.files = files;
-      runAgain = false;
+      beforeRun();
+      resetMocha(mocha);
       runner = mocha.run(() => {
         runner = null;
-        if (runAgain) {
+        if (rerunScheduled) {
           rerun();
@@ -58,28 +110,61 @@ }
 
-  const purge = () => {
-    watchFiles.forEach(Mocha.unloadFile);
+  const scheduleRun = () => {
+    if (rerunScheduled) {
+      return;
+    }
+
+    rerunScheduled = true;
+    if (runner) {
+      runner.abort();
+    } else {
+      rerun();
+    }
   };
 
-  loadAndRun();
-
   const rerun = () => {
-    purge();
+    rerunScheduled = false;
     eraseLine();
-    mocha.suite = mocha.suite.clone();
-    mocha.suite.ctx = new Context();
-    mocha.ui(ui);
-    loadAndRun();
+    run();
   };
 
-  utils.watch(watchFiles, () => {
-    runAgain = true;
-    if (runner) {
-      runner.abort();
-    } else {
-      rerun();
-    }
+  return {
+    scheduleRun,
+    run
+  };
+};
+
+/**
+ * Return the list of absolute paths watched by a chokidar watcher.
+ *
+ * @param watcher - Instance of a chokidar watcher
+ * @return {string[]} - List of absolute paths
+ */
+const getWatchedFiles = watcher => {
+  const watchedDirs = watcher.getWatched();
+  let watchedFiles = [];
+  Object.keys(watchedDirs).forEach(dir => {
+    watchedFiles = watchedFiles.concat(
+      watchedDirs[dir].map(file => path.join(dir, file))
+    );
   });
+  return watchedFiles;
 };
 
 /**
+ * Reset the internal state of the mocha instance so that tests can be rerun.
+ *
+ * @param {Mocha} mocha - Mocha instance
+ * @private
+ */
+const resetMocha = mocha => {
+  mocha.unloadFiles();
+  mocha.suite = mocha.suite.clone();
+  mocha.suite.ctx = new Context();
+  // Registers a callback on `mocha.suite` that wires new context to the DSL
+  // (e.g. `describe`) that is exposed as globals when the test files are
+  // reloaded.
+  mocha.ui(mocha.options.ui);
+};
+
+/**
  * Hide the cursor.
@@ -86,0 +171,0 @@ * @ignore

lib/mocha.js

@@ -72,14 +72,14 @@ 'use strict';
  * @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?
@@ -93,4 +93,2 @@ * @param {boolean} [options.noHighlighting] - Disable syntax highlighting?
  * @param {string} [options.ui] - Interface name.
- * @param {boolean} [options.color] - Color TTY output from reporter?
- * @param {boolean} [options.useInlineDiffs] - Use inline diffs?
  */
@@ -104,32 +102,9 @@ function Mocha(options) {
 
-  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);
+    .global(options.global);
 
-  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);
-    }
-  }
-
   // this guard exists because Suite#timeout does not consider `undefined` to be valid input
@@ -144,11 +119,10 @@ if (typeof options.timeout !== 'undefined') {
 
-  if ('diff' in options) {
-    this.hideDiff(!options.diff);
-  }
-
   [
     'allowUncaught',
     'asyncOnly',
+    'bail',
     'checkLeaks',
+    'color',
     'delay',
+    'diff',
     'forbidOnly',
@@ -158,2 +132,3 @@ 'forbidPending',
     'growl',
+    'inlineDiffs',
     'invert'
@@ -171,3 +146,3 @@ ].forEach(function(opt) {
  * @public
- * @see {@link /#-bail-b|CLI option}
+ * @see [CLI option](../#-bail-b)
  * @param {boolean} [bail=true] - Whether to bail on first error.
@@ -178,6 +153,3 @@ * @returns {Mocha} this
 Mocha.prototype.bail = function(bail) {
-  if (!arguments.length) {
-    bail = true;
-  }
-  this.suite.bail(bail);
+  this.suite.bail(bail !== false);
   return this;
@@ -194,3 +166,3 @@ };
  * @public
- * @see {@link /#-file-filedirectoryglob|CLI option}
+ * @see [CLI option](../#-file-filedirectoryglob)
  * @param {string} file - Pathname of file to be loaded.
@@ -209,4 +181,4 @@ * @returns {Mocha} this
  * @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.
@@ -269,2 +241,4 @@ * @param {Object} [reporterOptions] - Options used to configure the reporter.
   }
+  this.options.reporterOption = reporterOptions;
+  // alias option name is used in public reporters xunit/tap/progress
   this.options.reporterOptions = reporterOptions;
@@ -278,4 +252,4 @@ return this;
  * @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.
@@ -373,4 +347,2 @@ * @returns {Mocha} this
  * @public
- * @see {@link Mocha.unloadFile}
- * @see {@link Mocha#loadFiles}
  * @see {@link Mocha#run}
@@ -419,3 +391,3 @@ * @returns {Mocha} this
  * @public
- * @see {@link /#grep-regexp-g-regexp|CLI option}
+ * @see [CLI option](../#-grep-regexp-g-regexp)
  * @see {@link Mocha#fgrep}
@@ -471,14 +443,14 @@ * @see {@link Mocha#invert}
  *
+ * @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;
@@ -488,12 +460,12 @@ };
 /**
- * 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;
@@ -506,7 +478,9 @@ };
  * @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;
@@ -519,4 +493,3 @@ };
  * @public
- * @see {@link Mocha#isGrowlCapable}
- * @see {@link Mocha#_growl}
+ * @see [CLI option](../#-growl-g)
  * @return {Mocha} this
@@ -564,5 +537,5 @@ * @chainable
  * @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
@@ -573,7 +546,7 @@ * @chainable
  * // 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)
@@ -585,2 +558,4 @@ .filter(function(elt, idx, arr) {
 };
+// for backwards compability, 'globals' is an alias of 'global'
+Mocha.prototype.globals = Mocha.prototype.global;
 
@@ -590,3 +565,5 @@ /**
  *
+ * @deprecated since v7.0.0
  * @public
+ * @see {@link Mocha#color}
  * @param {boolean} colors - Whether to enable color output.
@@ -597,4 +574,5 @@ * @return {Mocha} this
 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;
   }
@@ -605,7 +583,23 @@ 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
@@ -615,3 +609,6 @@ * @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;
@@ -621,6 +618,23 @@ };
 /**
+ * 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
@@ -630,3 +644,4 @@ * @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;
@@ -636,2 +651,16 @@ };
 /**
+ * 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;
+};
+
+/**
  * @summary
@@ -645,4 +674,4 @@ * Sets timeout threshold value.
  * @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}
@@ -670,3 +699,4 @@ * @param {number|string} msecs - Timeout threshold value.
  * @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.
@@ -689,3 +719,3 @@ * @return {Mocha} this
  * @public
- * @see {@link /#-slow-ms-s-ms|CLI option}
+ * @see [CLI option](../#-slow-ms-s-ms)
  * @param {number} msecs - Slowness threshold value.
@@ -712,3 +742,3 @@ * @return {Mocha} this
  * @public
- * @see {@link /#-timeout-ms-t-ms|CLI option}
+ * @see [CLI option](../#-timeout-ms-t-ms)
  * @param {boolean} enableTimeouts - Whether to enable timeouts.
@@ -729,7 +759,9 @@ * @return {Mocha} this
  * @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;
@@ -751,10 +783,12 @@ };
 /**
- * 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;
@@ -771,3 +805,3 @@ };
  * @public
- * @see {@link /#delayed-root-suite|delayed root suite}
+ * @see [delayed root suite](../#delayed-root-suite)
  * @returns {Mocha} this
@@ -785,7 +819,9 @@ * @chainable
  * @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;
@@ -798,7 +834,9 @@ };
  * @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;
@@ -837,3 +875,2 @@ };
  * @public
- * @see {@link Mocha#loadFiles}
  * @see {@link Mocha#unloadFiles}
@@ -854,4 +891,4 @@ * @see {@link Runner#run}
   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;
@@ -864,4 +901,4 @@ runner.allowUncaught = options.allowUncaught;
   }
-  if (options.globals) {
-    runner.globals(options.globals);
+  if (options.global) {
+    runner.globals(options.global);
   }
@@ -871,7 +908,7 @@ if (options.growl) {
   }
-  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;
 
@@ -878,0 +915,0 @@ function done(failures) {

lib/mocharc.json

@@ -9,3 +9,4 @@ {
   "timeout": 2000,
-  "ui": "bdd"
+  "ui": "bdd",
+  "watch-ignore": ["node_modules", ".git"]
 }

lib/reporters/base.js

@@ -157,3 +157,3 @@ 'use strict';
 
-function showDiff(err) {
+var showDiff = (exports.showDiff = function(err) {
   return (
@@ -165,3 +165,3 @@ err &&
   );
-}
+});
 
@@ -187,5 +187,15 @@ function stringifyDiffObjs(err) {
 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;
+  }
 });
@@ -192,0 +202,0 @@

lib/reporters/xunit.js

@@ -166,5 +166,5 @@ 'use strict';
     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(
@@ -171,0 +171,0 @@ tag(

lib/runnable.js

@@ -138,3 +138,4 @@ 'use strict';
 Runnable.prototype.skip = function() {
-  throw new Pending('sync skip');
+  this.pending = true;
+  throw new Pending('sync skip; aborting execution');
 };
@@ -347,16 +348,18 @@
     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));
@@ -367,11 +370,2 @@ }
 
-  if (this.allowUncaught) {
-    if (this.isPending()) {
-      done();
-    } else {
-      callFn(this.fn);
-    }
-    return;
-  }
-
   // sync or promise-returning
@@ -386,2 +380,7 @@ try {
     emitted = true;
+    if (err instanceof Pending) {
+      return done();
+    } else if (this.allowUncaught) {
+      throw err;
+    }
     done(Runnable.toValueOrError(err));
@@ -388,0 +387,0 @@ }

lib/runner.js

@@ -27,4 +27,5 @@ 'use strict';
 var type = utils.type;
-var createInvalidExceptionError = require('./errors')
-  .createInvalidExceptionError;
+var errors = require('./errors');
+var createInvalidExceptionError = errors.createInvalidExceptionError;
+var createUnsupportedError = errors.createUnsupportedError;
 
@@ -248,3 +249,3 @@ /**
 Runner.prototype.checkGlobals = function(test) {
-  if (this.ignoreLeaks) {
+  if (!this.checkLeaks) {
     return;
@@ -320,4 +321,3 @@ }
  *   which is run only once
- * - Failed `after` hook does not alter
- *   execution order
+ * - Failed `after` hook does not alter execution order
  * - Failed `after each` hook skips remaining tests in a
@@ -392,30 +392,33 @@ *   suite and subsuites, but executes other `after each`
       }
-      if (err) {
-        if (err instanceof Pending) {
-          if (name === HOOK_TYPE_AFTER_ALL) {
-            utils.deprecate(
-              'Skipping a test within an "after all" hook is DEPRECATED and will throw an exception in a future version of Mocha. ' +
-                'Use a return statement or other means to abort hook execution.'
-            );
+      // conditional skip
+      if (hook.pending) {
+        if (name === HOOK_TYPE_AFTER_EACH) {
+          // TODO define and implement use case
+          if (self.test) {
+            self.test.pending = true;
           }
-          if (name === HOOK_TYPE_BEFORE_EACH || name === HOOK_TYPE_AFTER_EACH) {
-            if (self.test) {
-              self.test.pending = true;
-            }
-          } else {
-            suite.tests.forEach(function(test) {
-              test.pending = true;
-            });
-            suite.suites.forEach(function(suite) {
-              suite.pending = true;
-            });
-            // a pending hook won't be executed twice.
-            hook.pending = true;
+        } else if (name === HOOK_TYPE_BEFORE_EACH) {
+          if (self.test) {
+            self.test.pending = true;
           }
+          self.emit(constants.EVENT_HOOK_END, hook);
+          hook.pending = false; // activates hook for next test
+          return fn(new Error('abort hookDown'));
+        } else if (name === HOOK_TYPE_BEFORE_ALL) {
+          suite.tests.forEach(function(test) {
+            test.pending = true;
+          });
+          suite.suites.forEach(function(suite) {
+            suite.pending = true;
+          });
         } else {
-          self.failHook(hook, err);
-
-          // stop executing hooks, notify callee of hook err
-          return fn(err);
+          hook.pending = false;
+          var errForbid = createUnsupportedError('`this.skip` forbidden');
+          self.failHook(hook, errForbid);
+          return fn(errForbid);
         }
+      } else if (err) {
+        self.failHook(hook, err);
+        // stop executing hooks, notify callee of hook err
+        return fn(err);
       }
@@ -532,2 +535,5 @@ self.emit(constants.EVENT_HOOK_END, hook);
   test.on('error', function(err) {
+    if (err instanceof Pending) {
+      return;
+    }
     self.fail(test, err);
@@ -628,2 +634,3 @@ });
 
+    // static skip, no hooks are executed
     if (test.isPending()) {
@@ -644,2 +651,3 @@ if (self.forbidPending) {
     self.hookDown(HOOK_TYPE_BEFORE_EACH, function(err, errSuite) {
+      // conditional skip within beforeEach
       if (test.isPending()) {
@@ -654,3 +662,9 @@ if (self.forbidPending) {
         self.emit(constants.EVENT_TEST_END, test);
-        return next();
+        // skip inner afterEach hooks below errSuite level
+        var origSuite = self.suite;
+        self.suite = errSuite;
+        return self.hookUp(HOOK_TYPE_AFTER_EACH, function(e, eSuite) {
+          self.suite = origSuite;
+          next(e, eSuite);
+        });
       }
@@ -663,10 +677,16 @@ if (err) {
         test = self.test;
-        if (err) {
-          var retry = test.currentRetry();
-          if (err instanceof Pending && self.forbidPending) {
+        // conditional skip within it
+        if (test.pending) {
+          if (self.forbidPending) {
+            test.isPending = alwaysFalse;
             self.fail(test, new Error('Pending test forbidden'));
-          } else if (err instanceof Pending) {
-            test.pending = true;
+            delete test.isPending;
+          } else {
             self.emit(constants.EVENT_TEST_PENDING, test);
-          } else if (retry < test.retries()) {
+          }
+          self.emit(constants.EVENT_TEST_END, test);
+          return self.hookUp(HOOK_TYPE_AFTER_EACH, next);
+        } else if (err) {
+          var retry = test.currentRetry();
+          if (retry < test.retries()) {
             var clonedTest = test.clone();
@@ -685,7 +705,2 @@ clonedTest.currentRetry(retry + 1);
           self.emit(constants.EVENT_TEST_END, test);
-
-          if (err instanceof Pending) {
-            return next();
-          }
-
           return self.hookUp(HOOK_TYPE_AFTER_EACH, next);
@@ -807,2 +822,6 @@ }
   }
+  if (this.allowUncaught) {
+    throw err;
+  }
+
   if (err) {
@@ -843,7 +862,13 @@ debug('uncaught exception %O', err);
 
-  // Ignore errors if already failed or pending
-  // See #3226
-  if (runnable.isFailed() || runnable.isPending()) {
+  if (runnable.isFailed()) {
+    // Ignore error if already failed
     return;
+  } else if (runnable.isPending()) {
+    // report 'pending test' retrospectively as failed
+    runnable.isPending = alwaysFalse;
+    this.fail(runnable, err);
+    delete runnable.isPending;
+    return;
   }
+
   // we cannot recover gracefully if a Runnable has already passed
@@ -930,2 +955,8 @@ // then fails asynchronously
     process.removeListener('uncaughtException', uncaught);
+    process.on('uncaughtException', function(err) {
+      if (err instanceof Pending) {
+        return;
+      }
+      throw err;
+    });
     fn(self.failures);
@@ -932,0 +963,0 @@ });

lib/utils.js

@@ -57,76 +57,2 @@ 'use strict';
 /**
- * Watch the given `files` for changes
- * and invoke `fn(file)` on modification.
- *
- * @private
- * @param {Array} files
- * @param {Function} fn
- */
-exports.watch = function(files, fn) {
-  var options = {interval: 100};
-  var debug = require('debug')('mocha:watch');
-  files.forEach(function(file) {
-    debug('file %s', file);
-    fs.watchFile(file, options, function(curr, prev) {
-      if (prev.mtime < curr.mtime) {
-        fn(file);
-      }
-    });
-  });
-};
-
-/**
- * Predicate to screen `pathname` for further consideration.
- *
- * @description
- * Returns <code>false</code> for pathname referencing:
- * <ul>
- *   <li>'npm' package installation directory
- *   <li>'git' version control directory
- * </ul>
- *
- * @private
- * @param {string} pathname - File or directory name to screen
- * @return {boolean} whether pathname should be further considered
- * @example
- * ['node_modules', 'test.js'].filter(considerFurther); // => ['test.js']
- */
-function considerFurther(pathname) {
-  var ignore = ['node_modules', '.git'];
-
-  return !~ignore.indexOf(pathname);
-}
-
-/**
- * Lookup files in the given `dir`.
- *
- * @description
- * Filenames are returned in _traversal_ order by the OS/filesystem.
- * **Make no assumption that the names will be sorted in any fashion.**
- *
- * @private
- * @param {string} dir
- * @param {string[]} [exts=['js']]
- * @param {Array} [ret=[]]
- * @return {Array}
- */
-exports.files = function(dir, exts, ret) {
-  ret = ret || [];
-  exts = exts || ['js'];
-
-  fs.readdirSync(dir)
-    .filter(considerFurther)
-    .forEach(function(dirent) {
-      var pathname = path.join(dir, dirent);
-      if (fs.lstatSync(pathname).isDirectory()) {
-        exports.files(pathname, exts, ret);
-      } else if (hasMatchingExtname(pathname, exts)) {
-        ret.push(pathname);
-      }
-    });
-
-  return ret;
-};
-
-/**
  * Compute a slug from the given `str`.
@@ -133,0 +59,0 @@ *

package.json

 {
   "name": "mocha",
-  "version": "6.2.2",
+  "version": "7.0.0",
   "description": "simple, flexible, fun test framework",
@@ -12,2 +12,6 @@ "keywords": [
   ],
+  "funding": {
+    "type": "opencollective",
+    "url": "https://opencollective.com/mochajs"
+  },
   "author": "TJ Holowaychuk <[e-mail]>",
@@ -197,2 +201,5 @@ "contributors": [
     "Hugo Giraudel <[e-mail]>",
+    "Hugo Kim <[e-mail]>",
+    "HYUNSANG HAN <[e-mail]>",
+    "HyunSangHan <[e-mail]>",
     "Ian Storm Taylor <[e-mail]>",
@@ -221,2 +228,3 @@ "Ian W. Remmel <[e-mail]>",
     "Jan Lehnardt <[e-mail]>",
+    "Jan-Philip Gehrcke <[e-mail]>",
     "Jason Barry <[e-mail]>",
@@ -287,2 +295,3 @@ "Jason Lai <[e-mail]>",
     "Kunal Nagpal <[e-mail]>",
+    "Kyle Fuller <[e-mail]>",
     "Kyle Mitchell <[e-mail]>",
@@ -358,2 +367,3 @@ "lakmeer <[e-mail]>",
     "Panu Horsmalahti <[e-mail]>",
+    "Park Seong-beom <[e-mail]>",
     "Parker Moore <[e-mail]>",
@@ -369,2 +379,3 @@ "Pascal <[e-mail]>",
     "Peter Rust <[e-mail]>",
+    "Peter Schmidt <[e-mail]>",
     "Phil Sung <[e-mail]>",
@@ -382,2 +393,3 @@ "Philip M. White <[e-mail]>",
     "Refael Ackermann <[e-mail]>",
+    "Rens Groothuijsen <[e-mail]>",
     "Rich Trott <[e-mail]>",
@@ -391,2 +403,3 @@ "Richard Dingwall <[e-mail]>",
     "Rob Wu <[e-mail]>",
+    "Robert Kieffer <[e-mail]>",
     "Robert Rossmann <[e-mail]>",
@@ -406,2 +419,3 @@ "Romain Prieto <[e-mail]>",
     "ryym <[e-mail]>",
+    "Saerom Bang <[e-mail]>",
     "Salehen Shovon Rahman <[e-mail]>",
@@ -423,2 +437,3 @@ "Sam Mussell <[e-mail]>",
     "Shawn Krisman <telaviv@github>",
+    "SheetJSDev <[e-mail]>",
     "Shinnosuke Watanabe <[e-mail]>",
@@ -435,2 +450,4 @@ "silentcloud <[e-mail]>",
     "solodynamo <[e-mail]>",
+    "Sona Lee <[e-mail]>",
+    "Soobin Bak <[e-mail]>",
     "Sorin Iclanzan <[e-mail]>",
@@ -523,3 +540,3 @@ "Standa Opichal <[e-mail]>",
   "engines": {
-    "node": ">= 6.0.0"
+    "node": ">= 8.0.0"
   },
@@ -535,2 +552,3 @@ "scripts": {
     "browser-stdout": "1.3.1",
+    "chokidar": "3.3.0",
     "debug": "3.2.6",
@@ -548,3 +566,3 @@ "diff": "3.5.0",
     "ms": "2.1.1",
-    "node-environment-flags": "1.0.5",
+    "node-environment-flags": "1.0.6",
     "object.assign": "4.1.0",
@@ -621,3 +639,3 @@ "strip-json-comments": "2.0.1",
   "files": [
-    "bin/{*mocha,options.js}",
+    "bin/*mocha",
     "assets/growl/*.png",
@@ -639,2 +657,4 @@ "lib/**/*.{js,html,json}",
     "tty": "./lib/browser/tty.js",
+    "./lib/cli/*.js": false,
+    "chokidar": false,
     "fs": false,
@@ -641,0 +661,0 @@ "glob": false,

README.md

@@ -5,3 +5,3 @@ <p align="center">
 
-<p align="center">:coffee: Simple, flexible, fun JavaScript test framework for Node.js & The Browser :coffee:</p>
+<p align="center">☕️ Simple, flexible, fun JavaScript test framework for Node.js & The Browser ☕️</p>
 
@@ -60,3 +60,3 @@ <p align="center"><a href="http://travis-ci.org/mochajs/mocha"><img src="https://api.travis-ci.org/mochajs/mocha.svg?branch=master" alt="Build Status"></a>  <a href="https://coveralls.io/github/mochajs/mocha"><img src="https://coveralls.io/repos/github/mochajs/mocha/badge.svg" alt="Coverage Status"></a>  <a href="https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_shield"><img src="https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=shield" alt="FOSSA Status"></a>  <a href="https://gitter.im/mochajs/mocha?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Gitter"></a>  <a href="https://github.com/mochajs/mocha#backers"><img src="https://opencollective.com/mochajs/backers/badge.svg" alt="OpenCollective"></a>  <a href="https://github.com/mochajs/mocha#sponsors"><img src="https://opencollective.com/mochajs/sponsors/badge.svg" alt="OpenCollective"></a>
 
-Does your company use Mocha?  Ask your manager or marketing team if your company would be interested in supporting our project.  Support will allow the maintainers to dedicate more time for maintenance and new features for everyone.  Also, your company's logo will show [on GitHub](https://github.com/mochajs/mocha#readme) and on [our site](https://mochajs.org) - who doesn't want a little extra exposure?  [Here's the info](https://opencollective.com/mochajs#sponsor).
+Does your company use Mocha? Ask your manager or marketing team if your company would be interested in supporting our project. Support will allow the maintainers to dedicate more time for maintenance and new features for everyone. Also, your company's logo will show [on GitHub](https://github.com/mochajs/mocha#readme) and on [our site](https://mochajs.org) - who doesn't want a little extra exposure? [Here's the info](https://opencollective.com/mochajs#sponsor).
 
@@ -88,8 +88,8 @@ [![MochaJS Sponsor](https://opencollective.com/mochajs/sponsor/0/avatar)](https://opencollective.com/mochajs/sponsor/0/website)
 
-- Mocha is the *most-depended-upon* module on npm (source: [libraries.io](https://libraries.io/search?order=desc&platforms=NPM&sort=dependents_count)), and
-- Mocha is an *independent* open-source project, maintained exclusively by volunteers.
+- Mocha is the _most-depended-upon_ module on npm (source: [libraries.io](https://libraries.io/search?order=desc&platforms=NPM&sort=dependents_count)), and
+- Mocha is an _independent_ open-source project, maintained exclusively by volunteers.
 
 You might want to help:
 
-- New to contributing to Mocha?  Check out this list of [good first issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue)
+- New to contributing to Mocha? Check out this list of [good first issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+label%3Agood-first-issue)
 - Mocha could use a hand with [these issues](https://github.com/mochajs/mocha/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
@@ -96,0 +96,0 @@ - The [maintainer's handbook](https://github.com/mochajs/mocha/blob/master/MAINTAINERS.md) explains how things get done

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1001522

increased by0.84%

Lines of code

25138

increased by0.34%

Number of low supply chain risk alerts

31

decreased by-3.12%

Worsened metrics

Dependency count

24

increased by4.35%

Number of package files

64

decreased by-1.54%

Dependency changes

• + Addedchokidar@3.3.0

• + Addedanymatch@3.1.3(transitive)

• + Addedbinary-extensions@2.3.0(transitive)

• + Addedbraces@3.0.3(transitive)

• + Addedchokidar@3.3.0(transitive)

• + Addedfill-range@7.1.1(transitive)

• + Addedfsevents@2.1.3(transitive)

• + Addedglob-parent@5.1.2(transitive)

• + Addedis-binary-path@2.1.0(transitive)

• + Addedis-extglob@2.1.1(transitive)

• + Addedis-glob@4.0.3(transitive)

• + Addedis-number@7.0.0(transitive)

• + Addednode-environment-flags@1.0.6(transitive)

• + Addednormalize-path@3.0.0(transitive)

• + Addedpicomatch@2.3.1(transitive)

• + Addedreaddirp@3.2.0(transitive)

• + Addedto-regex-range@5.0.1(transitive)

• - Removednode-environment-flags@1.0.5(transitive)

• Updatednode-environment-flags@1.0.6