mocha 8.1.3 → 8.2.0

package/CHANGELOG.md

@@ -1,3 +1,59 @@
+# 8.2.0 / 2020-10-15
+
+The major feature added in v8.2.0 is addition of support for [_global fixtures_](https://mochajs.org/#global-fixtures).
+
+While Mocha has always had the ability to run setup and teardown via a hook (e.g., a `before()` at the top level of a test file) when running tests in serial, Mocha v8.0.0 added support for parallel runs. Parallel runs are _incompatible_ with this strategy; e.g., a top-level `before()` would only run for the file in which it was defined.
+
+With [global fixtures](https://mochajs.org/#global-fixtures), Mocha can now perform user-defined setup and teardown _regardless_ of mode, and these fixtures are guaranteed to run _once and only once_. This holds for parallel mode, serial mode, and even "watch" mode (the teardown will run once you hit Ctrl-C, just before Mocha finally exits). Tasks such as starting and stopping servers are well-suited to global fixtures, but not sharing resources--global fixtures do _not_ share context with your test files (but they do share context with each other).
+
+Here's a short example of usage:
+
+```js
+// fixtures.js
+
+// can be async or not
+exports.mochaGlobalSetup = async function() {
+  this.server = await startSomeServer({port: process.env.TEST_PORT});
+  console.log(`server running on port ${this.server.port}`);
+};
+
+exports.mochaGlobalTeardown = async function() {
+  // the context (`this`) is shared, but not with the test files
+  await this.server.stop();
+  console.log(`server on port ${this.server.port} stopped`);
+};
+
+// this file can contain root hook plugins as well!
+// exports.mochaHooks = { ... }
+```
+
+Fixtures are loaded with `--require`, e.g., `mocha --require fixtures.js`.
+
+For detailed information, please see the [documentation](https://mochajs.org/#global-fixtures) and this handy-dandy [flowchart](https://mochajs.org/#test-fixture-decision-tree-wizard-thing) to help understand the differences between hooks, root hook plugins, and global fixtures (and when you should use each).
+
+## :tada: Enhancements
+
+- [#4308](https://github.com/mochajs/mocha/issues/4308): Support run-once [global setup & teardown fixtures](https://mochajs.org/#global-fixtures) ([**@boneskull**](https://github.com/boneskull))
+- [#4442](https://github.com/mochajs/mocha/issues/4442): Multi-part extensions (e.g., `test.js`) now usable with `--extension` option ([**@jordanstephens**](https://github.com/jordanstephens))
+- [#4472](https://github.com/mochajs/mocha/issues/4472): Leading dots (e.g., `.js`, `.test.js`) now usable with `--extension` option ([**@boneskull**](https://github.com/boneskull))
+- [#4434](https://github.com/mochajs/mocha/issues/4434): Output of `json` reporter now contains `speed` ("fast"/"medium"/"slow") property ([**@wwhurin**](https://github.com/wwhurin))
+- [#4464](https://github.com/mochajs/mocha/issues/4464): Errors thrown by serializer in parallel mode now have error codes ([**@evaline-ju**](https://github.com/evaline-ju))
+
+_For implementors of custom reporters:_
+
+- [#4409](https://github.com/mochajs/mocha/issues/4409): Parallel mode and custom reporter improvements ([**@boneskull**](https://github.com/boneskull)):
+  - Support custom worker-process-only reporters (`Runner.prototype.workerReporter()`); reporters should subclass `ParallelBufferedReporter` in `mocha/lib/nodejs/reporters/parallel-buffered`
+  - Allow opt-in of object reference matching for "sufficiently advanced" custom reporters (`Runner.prototype.linkPartialObjects()`); use if strict object equality is needed when consuming `Runner` event data
+  - Enable detection of parallel mode (`Runner.prototype.isParallelMode()`)
+
+## :bug: Fixes
+
+- [#4476](https://github.com/mochajs/mocha/issues/4476): Workaround for profoundly bizarre issue affecting `npm` v6.x causing some of Mocha's deps to be installed when `mocha` is present in a package's `devDependencies` and `npm install --production` is run the package's working copy ([**@boneskull**](https://github.com/boneskull))
+- [#4465](https://github.com/mochajs/mocha/issues/4465): Worker processes guaranteed (as opposed to "very likely") to exit before Mocha does; fixes a problem when using `nyc` with Mocha in parallel mode ([**@boneskull**](https://github.com/boneskull))
+- [#4419](https://github.com/mochajs/mocha/issues/4419): Restore `lookupFiles()` in `mocha/lib/utils`, which was broken/missing in Mocha v8.1.0; it now prints a deprecation warning (use `const {lookupFiles} = require('mocha/lib/cli')` instead) ([**@boneskull**](https://github.com/boneskull))
+
+Thanks to [**@AviVahl**](https://github.com/AviVahl), [**@donghoon-song**](https://github.com/donghoon-song), [**@ValeriaVG**](https://github.com/ValeriaVG), [**@znarf**](https://github.com/znarf), [**@sujin-park**](https://github.com/sujin-park), and [**@majecty**](https://github.com/majecty) for other helpful contributions!
+
 # 8.1.3 / 2020-08-28
 
 ## :bug: Fixes
@@ -9,7 +65,7 @@
 ## :bug: Fixes
 
 - [#4418](https://github.com/mochajs/mocha/issues/4418): Fix command-line flag incompatibility in forthcoming Node.js v14.9.0 ([**@boneskull**](https://github.com/boneskull))
-- [#4401](https://github.com/mochajs/mocha/issues/4401): Fix missing global variable in browser ([**@irrationelle**](https://github.com/irrationelle))
+- [#4401](https://github.com/mochajs/mocha/issues/4401): Fix missing global variable in browser ([**@irrationnelle**](https://github.com/irrationnelle))
 
 ## :lock: Security Fixes
 

package/README.md

@@ -7,6 +7,8 @@
 <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>
 
+<p align="center"><a href="https://www.npmjs.com/package/mocha"><img src="https://img.shields.io/npm/v/mocha.svg" alt="NPM Version"></a>  <a href="https://github.com/mochajs/mocha"><img src="https://img.shields.io/node/v/mocha.svg" alt="Node Version"></a></p>
+
 <p align="center"><br><img alt="Mocha Browser Support h/t SauceLabs" src="https://saucelabs.com/browser-matrix/mochajs.svg" width="354"></p>
 
 ## Links

package/lib/cli/lookup-files.js

@@ -1,5 +1,4 @@
 'use strict';
-
 /**
  * Contains `lookupFiles`, which takes some globs/dirs/options and returns a list of files.
  * @module
@@ -14,6 +13,7 @@ var errors = require('../errors');
 var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;
 var createMissingArgumentError = errors.createMissingArgumentError;
 var {sQuote, dQuote} = require('../utils');
+const debug = require('debug')('mocha:cli:lookup-files');
 
 /**
  * Determines if pathname would be a "hidden" file (or directory) on UN*X.
@@ -30,26 +30,26 @@ var {sQuote, dQuote} = require('../utils');
  * @example
  * isHiddenOnUnix('.profile'); // => true
  */
-function isHiddenOnUnix(pathname) {
-  return path.basename(pathname)[0] === '.';
-}
+const isHiddenOnUnix = pathname => path.basename(pathname).startsWith('.');
 
 /**
  * Determines if pathname has a matching file extension.
  *
+ * Supports multi-part extensions.
+ *
  * @private
  * @param {string} pathname - Pathname to check for match.
- * @param {string[]} exts - List of file extensions (sans period).
- * @return {boolean} whether file extension matches.
+ * @param {string[]} exts - List of file extensions, w/-or-w/o leading period
+ * @return {boolean} `true` if file extension matches.
  * @example
- * hasMatchingExtname('foo.html', ['js', 'css']); // => false
+ * hasMatchingExtname('foo.html', ['js', 'css']); // false
+ * hasMatchingExtname('foo.js', ['.js']); // true
+ * hasMatchingExtname('foo.js', ['js']); // ture
  */
-function hasMatchingExtname(pathname, exts) {
-  var suffix = path.extname(pathname).slice(1);
-  return exts.some(function(element) {
-    return suffix === element;
-  });
-}
+const hasMatchingExtname = (pathname, exts = []) =>
+  exts
+    .map(ext => (ext.startsWith('.') ? ext : `.${ext}`))
+    .some(ext => pathname.endsWith(ext));
 
 /**
  * Lookup file names at the given `path`.
@@ -67,27 +67,28 @@ function hasMatchingExtname(pathname, exts) {
  * @throws {Error} if no files match pattern.
  * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
  */
-module.exports = function lookupFiles(filepath, extensions, recursive) {
-  extensions = extensions || [];
-  recursive = recursive || false;
-  var files = [];
-  var stat;
+module.exports = function lookupFiles(
+  filepath,
+  extensions = [],
+  recursive = false
+) {
+  const files = [];
+  let stat;
 
   if (!fs.existsSync(filepath)) {
-    var pattern;
+    let pattern;
     if (glob.hasMagic(filepath)) {
       // Handle glob as is without extensions
       pattern = filepath;
     } else {
       // glob pattern e.g. 'filepath+(.js|.ts)'
-      var strExtensions = extensions
-        .map(function(v) {
-          return '.' + v;
-        })
+      const strExtensions = extensions
+        .map(ext => (ext.startsWith('.') ? ext : `.${ext}`))
         .join('|');
-      pattern = filepath + '+(' + strExtensions + ')';
+      pattern = `${filepath}+(${strExtensions})`;
+      debug('looking for files using glob pattern: %s', pattern);
     }
-    files = glob.sync(pattern, {nodir: true});
+    files.push(...glob.sync(pattern, {nodir: true}));
     if (!files.length) {
       throw createNoFilesMatchPatternError(
         'Cannot find any files matching pattern ' + dQuote(filepath),
@@ -109,20 +110,19 @@ module.exports = function lookupFiles(filepath, extensions, recursive) {
   }
 
   // Handle directory
-  fs.readdirSync(filepath).forEach(function(dirent) {
-    var pathname = path.join(filepath, dirent);
-    var stat;
+  fs.readdirSync(filepath).forEach(dirent => {
+    const pathname = path.join(filepath, dirent);
+    let stat;
 
     try {
       stat = fs.statSync(pathname);
       if (stat.isDirectory()) {
         if (recursive) {
-          files = files.concat(lookupFiles(pathname, extensions, recursive));
+          files.push(...lookupFiles(pathname, extensions, recursive));
         }
         return;
       }
-    } catch (err) {
-      // ignore error
+    } catch (ignored) {
       return;
     }
     if (!extensions.length) {

package/lib/cli/run-helpers.js

@@ -12,10 +12,10 @@ const path = require('path');
 const debug = require('debug')('mocha:cli:run:helpers');
 const {watchRun, watchParallelRun} = require('./watch-run');
 const collectFiles = require('./collect-files');
-const {type} = require('../utils');
 const {format} = require('util');
-const {createInvalidPluginError, createUnsupportedError} = require('../errors');
+const {createInvalidLegacyPluginError} = require('../errors');
 const {requireOrImport} = require('../esm-utils');
+const PluginLoader = require('../plugin-loader');
 
 /**
  * Exits Mocha when tests + code under test has finished execution (default)
@@ -79,12 +79,12 @@ exports.list = str =>
  *
  * Returns array of `mochaHooks` exports, if any.
  * @param {string[]} requires - Modules to require
- * @returns {Promise<MochaRootHookObject|MochaRootHookFunction>} Any root hooks
+ * @returns {Promise<object>} Plugin implementations
  * @private
  */
-exports.handleRequires = async (requires = []) => {
-  const acc = [];
-  for (const mod of requires) {
+exports.handleRequires = async (requires = [], {ignoredPlugins = []} = {}) => {
+  const pluginLoader = PluginLoader.create({ignore: ignoredPlugins});
+  for await (const mod of requires) {
     let modpath = mod;
     // this is relative to cwd
     if (fs.existsSync(mod) || fs.existsSync(`${mod}.js`)) {
@@ -92,49 +92,18 @@ exports.handleRequires = async (requires = []) => {
       debug('resolved required file %s to %s', mod, modpath);
     }
     const requiredModule = await requireOrImport(modpath);
-    if (
-      requiredModule &&
-      typeof requiredModule === 'object' &&
-      requiredModule.mochaHooks
-    ) {
-      const mochaHooksType = type(requiredModule.mochaHooks);
-      if (/function$/.test(mochaHooksType) || mochaHooksType === 'object') {
-        debug('found root hooks in required file %s', mod);
-        acc.push(requiredModule.mochaHooks);
-      } else {
-        throw createUnsupportedError(
-          'mochaHooks must be an object or a function returning (or fulfilling with) an object'
-        );
+    if (requiredModule && typeof requiredModule === 'object') {
+      if (pluginLoader.load(requiredModule)) {
+        debug('found one or more plugin implementations in %s', modpath);
       }
     }
     debug('loaded required module "%s"', mod);
   }
-  return acc;
-};
-
-/**
- * Loads root hooks as exported via `mochaHooks` from required files.
- * These can be sync/async functions returning objects, or just objects.
- * Flattens to a single object.
- * @param {Array<MochaRootHookObject|MochaRootHookFunction>} rootHooks - Array of root hooks
- * @private
- * @returns {MochaRootHookObject}
- */
-exports.loadRootHooks = async rootHooks => {
-  const rootHookObjects = await Promise.all(
-    rootHooks.map(async hook => (/function$/.test(type(hook)) ? hook() : hook))
-  );
-
-  return rootHookObjects.reduce(
-    (acc, hook) => {
-      acc.beforeAll = acc.beforeAll.concat(hook.beforeAll || []);
-      acc.beforeEach = acc.beforeEach.concat(hook.beforeEach || []);
-      acc.afterAll = acc.afterAll.concat(hook.afterAll || []);
-      acc.afterEach = acc.afterEach.concat(hook.afterEach || []);
-      return acc;
-    },
-    {beforeAll: [], beforeEach: [], afterAll: [], afterEach: []}
-  );
+  const plugins = await pluginLoader.finalize();
+  if (Object.keys(plugins).length) {
+    debug('finalized plugin implementations: %O', plugins);
+  }
+  return plugins;
 };
 
 /**
@@ -172,11 +141,7 @@ const singleRun = async (mocha, {exit}, fileCollectParams) => {
  */
 const parallelRun = async (mocha, options, fileCollectParams) => {
   const files = collectFiles(fileCollectParams);
-  debug(
-    'executing %d test file(s) across %d concurrent jobs',
-    files.length,
-    options.jobs
-  );
+  debug('executing %d test file(s) in parallel mode', files.length);
   mocha.files = files;
 
   // note that we DO NOT load any files here; this is handled by the worker
@@ -236,7 +201,7 @@ exports.runMocha = async (mocha, options) => {
  * name
  * @private
  */
-exports.validatePlugin = (opts, pluginType, map = {}) => {
+exports.validateLegacyPlugin = (opts, pluginType, map = {}) => {
   /**
    * This should be a unique identifier; either a string (present in `map`),
    * or a resolvable (via `require.resolve`) module ID/path.
@@ -245,14 +210,14 @@ exports.validatePlugin = (opts, pluginType, map = {}) => {
   const pluginId = opts[pluginType];
 
   if (Array.isArray(pluginId)) {
-    throw createInvalidPluginError(
+    throw createInvalidLegacyPluginError(
       `"--${pluginType}" can only be specified once`,
       pluginType
     );
   }
 
-  const unknownError = err =>
-    createInvalidPluginError(
+  const createUnknownError = err =>
+    createInvalidLegacyPluginError(
       format('Could not load %s "%s":\n\n %O', pluginType, pluginId, err),
       pluginType,
       pluginId
@@ -268,10 +233,10 @@ exports.validatePlugin = (opts, pluginType, map = {}) => {
         try {
           opts[pluginType] = require(path.resolve(pluginId));
         } catch (err) {
-          throw unknownError(err);
+          throw createUnknownError(err);
         }
       } else {
-        throw unknownError(err);
+        throw createUnknownError(err);
       }
     }
   }

package/lib/cli/run.js

@@ -19,8 +19,7 @@ const {
 const {
   list,
   handleRequires,
-  validatePlugin,
-  loadRootHooks,
+  validateLegacyPlugin,
   runMocha
 } = require('./run-helpers');
 const {ONE_AND_DONES, ONE_AND_DONE_ARGS} = require('./one-and-dones');
@@ -339,13 +338,10 @@ exports.builder = yargs =>
       // currently a failing middleware does not work nicely with yargs' `fail()`.
       try {
         // load requires first, because it can impact "plugin" validation
-        const rawRootHooks = await handleRequires(argv.require);
-        validatePlugin(argv, 'reporter', Mocha.reporters);
-        validatePlugin(argv, 'ui', Mocha.interfaces);
-
-        if (rawRootHooks && rawRootHooks.length) {
-          argv.rootHooks = await loadRootHooks(rawRootHooks);
-        }
+        const plugins = await handleRequires(argv.require);
+        validateLegacyPlugin(argv, 'reporter', Mocha.reporters);
+        validateLegacyPlugin(argv, 'ui', Mocha.interfaces);
+        Object.assign(argv, plugins);
       } catch (err) {
         // this could be a bad --require, bad reporter, ui, etc.
         console.error(`\n${symbols.error} ${ansi.red('ERROR:')}`, err);

package/lib/cli/watch-run.js

@@ -1,5 +1,6 @@
 'use strict';
 
+const logSymbols = require('log-symbols');
 const debug = require('debug')('mocha:cli:watch');
 const path = require('path');
 const chokidar = require('chokidar');
@@ -32,6 +33,7 @@ exports.watchParallelRun = (
   fileCollectParams
 ) => {
   debug('creating parallel watcher');
+
   return createWatcher(mocha, {
     watchFiles,
     watchIgnore,
@@ -68,9 +70,6 @@ exports.watchParallelRun = (
       newMocha.lazyLoadFiles(true);
       return newMocha;
     },
-    afterRun({watcher}) {
-      blastCache(watcher);
-    },
     fileCollectParams
   });
 };
@@ -91,7 +90,6 @@ exports.watchParallelRun = (
  */
 exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
   debug('creating serial watcher');
-  // list of all test files
 
   return createWatcher(mocha, {
     watchFiles,
@@ -128,9 +126,6 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
 
       return newMocha;
     },
-    afterRun({watcher}) {
-      blastCache(watcher);
-    },
     fileCollectParams
   });
 };
@@ -141,7 +136,6 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
  * @param {Object} opts
  * @param {BeforeWatchRun} [opts.beforeRun] - Function to call before
  * `mocha.run()`
- * @param {AfterWatchRun} [opts.afterRun] - Function to call after `mocha.run()`
  * @param {string[]} [opts.watchFiles] - List of paths and patterns to watch. If
  *   not provided all files with an extension included in
  *   `fileCollectionParams.extension` are watched. See first argument of
@@ -155,13 +149,17 @@ exports.watchRun = (mocha, {watchFiles, watchIgnore}, fileCollectParams) => {
  */
 const createWatcher = (
   mocha,
-  {watchFiles, watchIgnore, beforeRun, afterRun, fileCollectParams}
+  {watchFiles, watchIgnore, beforeRun, fileCollectParams}
 ) => {
   if (!watchFiles) {
     watchFiles = fileCollectParams.extension.map(ext => `**/*.${ext}`);
   }
 
   debug('ignoring files matching: %s', watchIgnore);
+  let globalFixtureContext;
+
+  // we handle global fixtures manually
+  mocha.enableGlobalSetup(false).enableGlobalTeardown(false);
 
   const watcher = chokidar.watch(watchFiles, {
     ignored: watchIgnore,
@@ -169,11 +167,14 @@ const createWatcher = (
   });
 
   const rerunner = createRerunner(mocha, watcher, {
-    beforeRun,
-    afterRun
+    beforeRun
   });
 
-  watcher.on('ready', () => {
+  watcher.on('ready', async () => {
+    if (!globalFixtureContext) {
+      debug('triggering global setup');
+      globalFixtureContext = await mocha.runGlobalSetup();
+    }
     rerunner.run();
   });
 
@@ -185,10 +186,39 @@ const createWatcher = (
   process.on('exit', () => {
     showCursor();
   });
-  process.on('SIGINT', () => {
+
+  // this is for testing.
+  // win32 cannot gracefully shutdown via a signal from a parent
+  // process; a `SIGINT` from a parent will cause the process
+  // to immediately exit.  during normal course of operation, a user
+  // will type Ctrl-C and the listener will be invoked, but this
+  // is not possible in automated testing.
+  // there may be another way to solve this, but it too will be a hack.
+  // for our watch tests on win32 we must _fork_ mocha with an IPC channel
+  if (process.connected) {
+    process.on('message', msg => {
+      if (msg === 'SIGINT') {
+        process.emit('SIGINT');
+      }
+    });
+  }
+
+  let exiting = false;
+  process.on('SIGINT', async () => {
     showCursor();
-    console.log('\n');
-    process.exit(128 + 2);
+    console.error(`${logSymbols.warning} [mocha] cleaning up, please wait...`);
+    if (!exiting) {
+      exiting = true;
+      if (mocha.hasGlobalTeardownFixtures()) {
+        debug('running global teardown');
+        try {
+          await mocha.runGlobalTeardown(globalFixtureContext);
+        } catch (err) {
+          console.error(err);
+        }
+      }
+      process.exit(130);
+    }
   });
 
   // Keyboard shortcut for restarting when "rs\n" is typed (ala Nodemon)
@@ -212,12 +242,11 @@ const createWatcher = (
  * @param {FSWatcher} watcher - chokidar `FSWatcher` instance
  * @param {Object} [opts] - Options!
  * @param {BeforeWatchRun} [opts.beforeRun] - Function to call before `mocha.run()`
- * @param {AfterWatchRun} [opts.afterRun] - Function to call after `mocha.run()`
  * @returns {Rerunner}
  * @ignore
  * @private
  */
-const createRerunner = (mocha, watcher, {beforeRun, afterRun} = {}) => {
+const createRerunner = (mocha, watcher, {beforeRun} = {}) => {
   // Set to a `Runner` when mocha is running. Set to `null` when mocha is not
   // running.
   let runner = null;
@@ -226,16 +255,15 @@ const createRerunner = (mocha, watcher, {beforeRun, afterRun} = {}) => {
   let rerunScheduled = false;
 
   const run = () => {
-    mocha = beforeRun ? beforeRun({mocha, watcher}) : mocha;
-
+    mocha = beforeRun ? beforeRun({mocha, watcher}) || mocha : mocha;
     runner = mocha.run(() => {
       debug('finished watch run');
       runner = null;
-      afterRun && afterRun({mocha, watcher});
+      blastCache(watcher);
       if (rerunScheduled) {
         rerun();
       } else {
-        debug('waiting for changes...');
+        console.error(`${logSymbols.info} [mocha] waiting for changes...`);
       }
     });
   };
@@ -333,15 +361,6 @@ const blastCache = watcher => {
  * @returns {Mocha}
  */
 
-/**
- * Callback to be run after `mocha.run()` completes.  Typically used to clear
- * require cache.
- * @callback AfterWatchRun
- * @private
- * @param {{mocha: Mocha, watcher: FSWatcher}} options
- * @returns {void}
- */
-
 /**
  * Object containing run control methods
  * @typedef {Object} Rerunner