mocha 8.1.0 → 8.2.0

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

package/lib/errors.js

@@ -1,12 +1,57 @@
 'use strict';
 
-var format = require('util').format;
+const {format} = require('util');
 
 /**
- * Factory functions to create throwable error objects
- * @module Errors
+ * Contains error codes, factory functions to create throwable error objects,
+ * and warning/deprecation functions.
+ * @module
  */
 
+/**
+ * process.emitWarning or a polyfill
+ * @see https://nodejs.org/api/process.html#process_process_emitwarning_warning_options
+ * @ignore
+ */
+const emitWarning = (msg, type) => {
+  if (process.emitWarning) {
+    process.emitWarning(msg, type);
+  } else {
+    process.nextTick(function() {
+      console.warn(type + ': ' + msg);
+    });
+  }
+};
+
+/**
+ * Show a deprecation warning. Each distinct message is only displayed once.
+ * Ignores empty messages.
+ *
+ * @param {string} [msg] - Warning to print
+ * @private
+ */
+const deprecate = msg => {
+  msg = String(msg);
+  if (msg && !deprecate.cache[msg]) {
+    deprecate.cache[msg] = true;
+    emitWarning(msg, 'DeprecationWarning');
+  }
+};
+deprecate.cache = {};
+
+/**
+ * Show a generic warning.
+ * Ignores empty messages.
+ *
+ * @param {string} [msg] - Warning to print
+ * @private
+ */
+const warn = msg => {
+  if (msg) {
+    emitWarning(msg);
+  }
+};
+
 /**
  * When Mocha throw exceptions (or otherwise errors), it attempts to assign a
  * `code` property to the `Error` object, for easier handling.  These are the
@@ -71,7 +116,17 @@ var constants = {
   /**
    * Use of `only()` w/ `--forbid-only` results in this error.
    */
-  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY'
+  FORBIDDEN_EXCLUSIVITY: 'ERR_MOCHA_FORBIDDEN_EXCLUSIVITY',
+
+  /**
+   * To be thrown when a user-defined plugin implementation (e.g., `mochaHooks`) is invalid
+   */
+  INVALID_PLUGIN_IMPLEMENTATION: 'ERR_MOCHA_INVALID_PLUGIN_IMPLEMENTATION',
+
+  /**
+   * To be thrown when a builtin or third-party plugin definition (the _definition_ of `mochaHooks`) is invalid
+   */
+  INVALID_PLUGIN_DEFINITION: 'ERR_MOCHA_INVALID_PLUGIN_DEFINITION'
 };
 
 /**
@@ -221,7 +276,7 @@ function createFatalError(message, value) {
  * @public
  * @returns {Error}
  */
-function createInvalidPluginError(message, pluginType, pluginId) {
+function createInvalidLegacyPluginError(message, pluginType, pluginId) {
   switch (pluginType) {
     case 'reporter':
       return createInvalidReporterError(message, pluginId);
@@ -232,6 +287,21 @@ function createInvalidPluginError(message, pluginType, pluginId) {
   }
 }
 
+/**
+ * **DEPRECATED**.  Use {@link createInvalidLegacyPluginError} instead  Dynamically creates a plugin-type-specific error based on plugin type
+ * @deprecated
+ * @param {string} message - Error message
+ * @param {"reporter"|"interface"} pluginType - Plugin type. Future: expand as needed
+ * @param {string} [pluginId] - Name/path of plugin, if any
+ * @throws When `pluginType` is not known
+ * @public
+ * @returns {Error}
+ */
+function createInvalidPluginError(...args) {
+  deprecate('Use createInvalidLegacyPluginError() instead');
+  return createInvalidLegacyPluginError(...args);
+}
+
 /**
  * Creates an error object to be thrown when a mocha object's `run` method is executed while it is already disposed.
  * @param {string} message The error message to be displayed.
@@ -315,20 +385,59 @@ function createForbiddenExclusivityError(mocha) {
   return err;
 }
 
+/**
+ * Creates an error object to be thrown when a plugin definition is invalid
+ * @param {string} msg - Error message
+ * @param {PluginDefinition} [pluginDef] - Problematic plugin definition
+ * @public
+ * @returns {Error} Error with code {@link constants.INVALID_PLUGIN_DEFINITION}
+ */
+function createInvalidPluginDefinitionError(msg, pluginDef) {
+  const err = new Error(msg);
+  err.code = constants.INVALID_PLUGIN_DEFINITION;
+  err.pluginDef = pluginDef;
+  return err;
+}
+
+/**
+ * Creates an error object to be thrown when a plugin implementation (user code) is invalid
+ * @param {string} msg - Error message
+ * @param {Object} [opts] - Plugin definition and user-supplied implementation
+ * @param {PluginDefinition} [opts.pluginDef] - Plugin Definition
+ * @param {*} [opts.pluginImpl] - Plugin Implementation (user-supplied)
+ * @public
+ * @returns {Error} Error with code {@link constants.INVALID_PLUGIN_DEFINITION}
+ */
+function createInvalidPluginImplementationError(
+  msg,
+  {pluginDef, pluginImpl} = {}
+) {
+  const err = new Error(msg);
+  err.code = constants.INVALID_PLUGIN_IMPLEMENTATION;
+  err.pluginDef = pluginDef;
+  err.pluginImpl = pluginImpl;
+  return err;
+}
+
 module.exports = {
-  createInvalidArgumentTypeError: createInvalidArgumentTypeError,
-  createInvalidArgumentValueError: createInvalidArgumentValueError,
-  createInvalidExceptionError: createInvalidExceptionError,
-  createInvalidInterfaceError: createInvalidInterfaceError,
-  createInvalidReporterError: createInvalidReporterError,
-  createMissingArgumentError: createMissingArgumentError,
-  createNoFilesMatchPatternError: createNoFilesMatchPatternError,
-  createUnsupportedError: createUnsupportedError,
-  createInvalidPluginError: createInvalidPluginError,
-  createMochaInstanceAlreadyDisposedError: createMochaInstanceAlreadyDisposedError,
-  createMochaInstanceAlreadyRunningError: createMochaInstanceAlreadyRunningError,
-  createFatalError: createFatalError,
-  createMultipleDoneError: createMultipleDoneError,
-  createForbiddenExclusivityError: createForbiddenExclusivityError,
-  constants: constants
+  constants,
+  createFatalError,
+  createForbiddenExclusivityError,
+  createInvalidArgumentTypeError,
+  createInvalidArgumentValueError,
+  createInvalidExceptionError,
+  createInvalidInterfaceError,
+  createInvalidLegacyPluginError,
+  createInvalidPluginDefinitionError,
+  createInvalidPluginError,
+  createInvalidPluginImplementationError,
+  createInvalidReporterError,
+  createMissingArgumentError,
+  createMochaInstanceAlreadyDisposedError,
+  createMochaInstanceAlreadyRunningError,
+  createMultipleDoneError,
+  createNoFilesMatchPatternError,
+  createUnsupportedError,
+  deprecate,
+  warn
 };

package/lib/hook.js

@@ -1,7 +1,8 @@
 'use strict';
 
 var Runnable = require('./runnable');
-var inherits = require('./utils').inherits;
+const {inherits, constants} = require('./utils');
+const {MOCHA_ID_PROP_NAME} = constants;
 
 /**
  * Expose `Hook`.
@@ -63,16 +64,20 @@ Hook.prototype.serialize = function serialize() {
   return {
     $$isPending: this.isPending(),
     $$titlePath: this.titlePath(),
-    ctx: {
-      currentTest: {
-        title: this.ctx && this.ctx.currentTest && this.ctx.currentTest.title
-      }
-    },
+    ctx:
+      this.ctx && this.ctx.currentTest
+        ? {
+            currentTest: {
+              title: this.ctx.currentTest.title,
+              [MOCHA_ID_PROP_NAME]: this.ctx.currentTest.id
+            }
+          }
+        : {},
     parent: {
-      root: this.parent.root,
-      title: this.parent.title
+      [MOCHA_ID_PROP_NAME]: this.parent.id
     },
     title: this.title,
-    type: this.type
+    type: this.type,
+    [MOCHA_ID_PROP_NAME]: this.id
   };
 };