mocha 6.2.2 → 7.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 (The MIT License)
 
-Copyright (c) 2011-2018 JS Foundation and contributors, https://js.foundation
+Copyright (c) 2011-2020 OpenJS Foundation and contributors, https://openjsf.org
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

package/README.md

@@ -2,7 +2,7 @@
   <img src="https://cldup.com/xFVFxOioAU.svg" alt="Mocha test framework"/>
 </p>
 
-<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>
 
 <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>
 </p>
@@ -56,7 +56,7 @@
 
 ## Sponsors
 
-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).
 
 [![MochaJS Sponsor](https://opencollective.com/mochajs/sponsor/0/avatar)](https://opencollective.com/mochajs/sponsor/0/website)
 [![MochaJS Sponsor](https://opencollective.com/mochajs/sponsor/1/avatar)](https://opencollective.com/mochajs/sponsor/1/website)
@@ -83,12 +83,12 @@ Does your company use Mocha?  Ask your manager or marketing team if your company
 
 You might want to know that:
 
-- 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)
 - The [maintainer's handbook](https://github.com/mochajs/mocha/blob/master/MAINTAINERS.md) explains how things get done
 
@@ -100,6 +100,6 @@ Finally, come [chat with the maintainers](https://gitter.im/mochajs/contributors
 
 ## License
 
-[MIT](LICENSE)
+Copyright 2011-2020 OpenJS Foundation and contributors. Licensed [MIT](https://github.com/mochajs/mocha/blob/master/LICENSE).
 
 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha.svg?type=large)](https://app.fossa.io/projects/git%2Bhttps%3A%2F%2Fgithub.com%2Fmochajs%2Fmocha?ref=badge_large)

package/bin/mocha

@@ -10,7 +10,7 @@
  * @private
  */
 
-const {deprecate, warn} = require('../lib/utils');
+const {deprecate} = require('../lib/utils');
 const {loadOptions} = require('../lib/cli/options');
 const {
   unparseNodeFlags,
@@ -20,7 +20,6 @@ const {
 const unparse = require('yargs-unparser');
 const debug = require('debug')('mocha:cli:mocha');
 const {aliases} = require('../lib/cli/run-option-metadata');
-const nodeEnv = require('node-environment-flags');
 
 const mochaArgs = {};
 const nodeArgs = {};
@@ -55,59 +54,29 @@ const trimV8Option = value =>
 Object.keys(opts).forEach(opt => {
   if (isNodeFlag(opt)) {
     nodeArgs[trimV8Option(opt)] = opts[opt];
-    disableTimeouts(opt);
   } else {
     mochaArgs[opt] = opts[opt];
   }
 });
 
+// disable 'timeout' for debugFlags
+Object.keys(nodeArgs).forEach(opt => disableTimeouts(opt));
+
 // Native debugger handling
 // see https://nodejs.org/api/debugger.html#debugger_debugger
-// look for 'debug' or 'inspect' that would launch this debugger,
+// look for 'inspect' or 'debug' that would launch this debugger,
 // remove it from Mocha's opts and prepend it to Node's opts.
-// also coerce depending on Node.js version.
 // A deprecation warning will be printed by node, if applicable.
 // (mochaArgs._ are "positional" arguments, not prefixed with - or --)
-if (/^(debug|inspect)$/.test(mochaArgs._[0])) {
-  const command = mochaArgs._.shift();
-  disableTimeouts(command);
-  // don't conflict with inspector
-  ['debug', 'inspect', 'debug-brk', 'inspect-brk']
-    .filter(opt => opt in nodeArgs || opt in mochaArgs)
-    .forEach(opt => {
-      warn(`command "${command}" provided; --${opt} ignored`);
-      delete nodeArgs[opt];
-      delete mochaArgs[opt];
-    });
-  nodeArgs._ = [
-    parseInt(
-      process.version
-        .slice(1)
-        .split('.')
-        .shift(),
-      10
-    ) >= 8
-      ? 'inspect'
-      : 'debug'
-  ];
+if (mochaArgs._) {
+  const i = mochaArgs._.findIndex(val => val === 'inspect' || val === 'debug');
+  if (i > -1) {
+    const [command] = mochaArgs._.splice(i, 1);
+    disableTimeouts('inspect');
+    nodeArgs._ = [command];
+  }
 }
 
-// allow --debug to invoke --inspect on Node.js v8 or newer.
-['debug', 'debug-brk']
-  .filter(opt => opt in nodeArgs && !nodeEnv.has(opt))
-  .forEach(opt => {
-    const newOpt = opt === 'debug' ? 'inspect' : 'inspect-brk';
-    warn(
-      `"--${opt}" is not available in Node.js ${
-        process.version
-      }; use "--${newOpt}" instead.`
-    );
-    nodeArgs[newOpt] = nodeArgs[opt];
-    mochaArgs.timeout = false;
-    debug(`--${opt} -> ${newOpt}`);
-    delete nodeArgs[opt];
-  });
-
 // historical
 if (nodeArgs.gc) {
   deprecate(

package/lib/cli/node-flags.js

@@ -14,7 +14,7 @@ const unparse = require('yargs-unparser');
  * @see {@link impliesNoTimeouts}
  * @private
  */
-const debugFlags = new Set(['debug', 'debug-brk', 'inspect', 'inspect-brk']);
+const debugFlags = new Set(['inspect', 'inspect-brk']);
 
 /**
  * Mocha has historical support for various `node` and V8 flags which might not

package/lib/cli/one-and-dones.js

@@ -48,14 +48,14 @@ exports.ONE_AND_DONES = {
    * Dump list of built-in interfaces
    * @private
    */
-  interfaces: () => {
+  'list-interfaces': () => {
     showKeys(Mocha.interfaces);
   },
   /**
    * Dump list of built-in reporters
    * @private
    */
-  reporters: () => {
+  'list-reporters': () => {
     showKeys(Mocha.reporters);
   }
 };

package/lib/cli/options.js

@@ -163,40 +163,6 @@ const parseMochaOpts = content =>
     .filter(Boolean)
     .map(value => value.replace(/%20/g, ' '));
 
-/**
- * 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.
  * @param {Object} [args] - Arguments object
@@ -231,6 +197,9 @@ const loadMochaOpts = (args = {}) => {
   // if there's an exception to catch here, I'm not sure what it is.
   // by attaching the `no-opts` arg, we avoid re-parsing of `mocha.opts`.
   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));
     debug(`${filepath} parsed succesfully`);
   }

package/lib/cli/run-helpers.js

@@ -118,13 +118,14 @@ exports.runMocha = (mocha, options) => {
   const {
     watch = false,
     extension = [],
-    ui = 'bdd',
     exit = false,
     ignore = [],
     file = [],
     recursive = false,
     sort = false,
-    spec = []
+    spec = [],
+    watchFiles,
+    watchIgnore
   } = options;
 
   const fileCollectParams = {
@@ -137,7 +138,7 @@ exports.runMocha = (mocha, options) => {
   };
 
   if (watch) {
-    watchRun(mocha, {ui}, fileCollectParams);
+    watchRun(mocha, {watchFiles, watchIgnore}, fileCollectParams);
   } else {
     exports.singleRun(mocha, {exit}, fileCollectParams);
   }

package/lib/cli/run-option-metadata.js

@@ -18,9 +18,11 @@ exports.types = {
     'file',
     'global',
     'ignore',
-    'require',
     'reporter-option',
-    'spec'
+    'require',
+    'spec',
+    'watch-files',
+    'watch-ignore'
   ],
   boolean: [
     'allow-uncaught',
@@ -36,11 +38,11 @@ exports.types = {
     'full-trace',
     'growl',
     'inline-diffs',
-    'interfaces',
     'invert',
+    'list-interfaces',
+    'list-reporters',
     'no-colors',
     'recursive',
-    'reporters',
     'sort',
     'watch'
   ],
@@ -68,7 +70,6 @@ exports.aliases = {
   'async-only': ['A'],
   bail: ['b'],
   color: ['c', 'colors'],
-  extension: ['watch-extensions'],
   fgrep: ['f'],
   global: ['globals'],
   grep: ['g'],

package/lib/cli/run.js

@@ -38,7 +38,7 @@ const GROUPS = {
   CONFIG: 'Configuration'
 };
 
-exports.command = ['$0 [spec..]', 'debug [spec..]'];
+exports.command = ['$0 [spec..]', 'inspect'];
 
 exports.describe = 'Run tests with Mocha';
 
@@ -88,7 +88,7 @@ exports.builder = yargs =>
       extension: {
         default: defaults.extension,
         defaultDescription: 'js',
-        description: 'File extension(s) to load and/or watch',
+        description: 'File extension(s) to load',
         group: GROUPS.FILES,
         requiresArg: true,
         coerce: list
@@ -147,14 +147,18 @@ exports.builder = yargs =>
           'Display actual/expected differences inline within each string',
         group: GROUPS.OUTPUT
       },
-      interfaces: {
-        conflicts: Array.from(ONE_AND_DONE_ARGS),
-        description: 'List built-in user interfaces & exit'
-      },
       invert: {
         description: 'Inverts --grep and --fgrep matches',
         group: GROUPS.FILTERS
       },
+      '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': {
         description: 'Force-disable color output',
         group: GROUPS.OUTPUT,
@@ -162,7 +166,7 @@ exports.builder = yargs =>
       },
       opts: {
         default: defaults.opts,
-        description: 'Path to `mocha.opts`',
+        description: 'Path to `mocha.opts` (DEPRECATED)',
         group: GROUPS.CONFIG,
         normalize: true,
         requiresArg: true
@@ -183,10 +187,6 @@ exports.builder = yargs =>
         group: GROUPS.OUTPUT,
         requiresArg: true
       },
-      reporters: {
-        conflicts: Array.from(ONE_AND_DONE_ARGS),
-        description: 'List built-in reporters & exit'
-      },
       'reporter-option': {
         coerce: opts =>
           list(opts).reduce((acc, opt) => {
@@ -241,6 +241,19 @@ exports.builder = yargs =>
       watch: {
         description: 'Watch files in the current working directory for changes',
         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']
       }
     })
     .positional('spec', {

package/lib/cli/watch-run.js

@@ -1,8 +1,8 @@
 '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');
 
 /**
@@ -16,36 +16,88 @@ const collectFiles = require('./collect-files');
  * Run Mocha in "watch" mode
  * @param {Mocha} mocha - Mocha instance
  * @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();
+  });
+};
+
+/**
+ * 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;
 
-  const loadAndRun = () => {
+  let rerunScheduled = false;
+
+  const run = () => {
     try {
-      mocha.files = files;
-      runAgain = false;
+      beforeRun();
+      resetMocha(mocha);
       runner = mocha.run(() => {
         runner = null;
-        if (runAgain) {
+        if (rerunScheduled) {
           rerun();
         }
       });
@@ -54,29 +106,62 @@ module.exports = (mocha, {ui}, fileCollectParams) => {
     }
   };
 
-  const purge = () => {
-    watchFiles.forEach(Mocha.unloadFile);
-  };
-
-  loadAndRun();
-
-  const rerun = () => {
-    purge();
-    eraseLine();
-    mocha.suite = mocha.suite.clone();
-    mocha.suite.ctx = new Context();
-    mocha.ui(ui);
-    loadAndRun();
-  };
+  const scheduleRun = () => {
+    if (rerunScheduled) {
+      return;
+    }
 
-  utils.watch(watchFiles, () => {
-    runAgain = true;
+    rerunScheduled = true;
     if (runner) {
       runner.abort();
     } else {
       rerun();
     }
+  };
+
+  const rerun = () => {
+    rerunScheduled = false;
+    eraseLine();
+    run();
+  };
+
+  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);
 };
 
 /**