mocha 8.1.1 → 8.2.1

package/lib/nodejs/parallel-buffered-runner.js

@@ -6,13 +6,31 @@
 
 'use strict';
 
-const allSettled = require('promise.allsettled');
+const allSettled = require('@ungap/promise-all-settled').bind(Promise);
 const Runner = require('../runner');
 const {EVENT_RUN_BEGIN, EVENT_RUN_END} = Runner.constants;
 const debug = require('debug')('mocha:parallel:parallel-buffered-runner');
 const {BufferedWorkerPool} = require('./buffered-worker-pool');
 const {setInterval, clearInterval} = global;
-const {createMap} = require('../utils');
+const {createMap, constants} = require('../utils');
+const {MOCHA_ID_PROP_NAME} = constants;
+const {createFatalError} = require('../errors');
+
+const DEFAULT_WORKER_REPORTER = require.resolve(
+  './reporters/parallel-buffered'
+);
+
+/**
+ * List of options to _not_ serialize for transmission to workers
+ */
+const DENY_OPTIONS = [
+  'globalSetup',
+  'globalTeardown',
+  'parallel',
+  'p',
+  'jobs',
+  'j'
+];
 
 /**
  * Outputs a debug statement with worker stats
@@ -56,7 +74,7 @@ const states = createMap({
 /**
  * This `Runner` delegates tests runs to worker threads.  Does not execute any
  * {@link Runnable}s by itself!
- * @private
+ * @public
  */
 class ParallelBufferedRunner extends Runner {
   constructor(...args) {
@@ -76,6 +94,10 @@ class ParallelBufferedRunner extends Runner {
       }
     });
 
+    this._workerReporter = DEFAULT_WORKER_REPORTER;
+    this._linkPartialObjects = false;
+    this._linkedObjectMap = new Map();
+
     this.once(Runner.constants.EVENT_RUN_END, () => {
       this._state = COMPLETE;
     });
@@ -86,12 +108,68 @@ class ParallelBufferedRunner extends Runner {
    * @param {BufferedWorkerPool} pool - Worker pool
    * @param {Options} options - Mocha options
    * @returns {FileRunner} Mapping function
+   * @private
    */
   _createFileRunner(pool, options) {
+    /**
+     * Emits event and sets `BAILING` state, if necessary.
+     * @param {Object} event - Event having `eventName`, maybe `data` and maybe `error`
+     * @param {number} failureCount - Failure count
+     */
+    const emitEvent = (event, failureCount) => {
+      this.emit(event.eventName, event.data, event.error);
+      if (
+        this._state !== BAILING &&
+        event.data &&
+        event.data._bail &&
+        (failureCount || event.error)
+      ) {
+        debug('run(): nonzero failure count & found bail flag');
+        // we need to let the events complete for this file, as the worker
+        // should run any cleanup hooks
+        this._state = BAILING;
+      }
+    };
+
+    /**
+     * Given an event, recursively find any objects in its data that have ID's, and create object references to already-seen objects.
+     * @param {Object} event - Event having `eventName`, maybe `data` and maybe `error`
+     */
+    const linkEvent = event => {
+      const stack = [{parent: event, prop: 'data'}];
+      while (stack.length) {
+        const {parent, prop} = stack.pop();
+        const obj = parent[prop];
+        let newObj;
+        if (obj && typeof obj === 'object') {
+          if (obj[MOCHA_ID_PROP_NAME]) {
+            const id = obj[MOCHA_ID_PROP_NAME];
+            newObj = this._linkedObjectMap.has(id)
+              ? Object.assign(this._linkedObjectMap.get(id), obj)
+              : obj;
+            this._linkedObjectMap.set(id, newObj);
+            parent[prop] = newObj;
+          } else {
+            throw createFatalError(
+              'Object missing ID received in event data',
+              obj
+            );
+          }
+        }
+        Object.keys(newObj).forEach(key => {
+          const value = obj[key];
+          if (value && typeof value === 'object' && value[MOCHA_ID_PROP_NAME]) {
+            stack.push({obj: value, parent: newObj, prop: key});
+          }
+        });
+      }
+    };
+
     return async file => {
       debug('run(): enqueueing test file %s', file);
       try {
         const {failureCount, events} = await pool.run(file, options);
+
         if (this._state === BAILED) {
           // short-circuit after a graceful bail. if this happens,
           // some other worker has bailed.
@@ -107,20 +185,18 @@ class ParallelBufferedRunner extends Runner {
         );
         this.failures += failureCount; // can this ever be non-numeric?
         let event = events.shift();
-        while (event) {
-          this.emit(event.eventName, event.data, event.error);
-          if (
-            this._state !== BAILING &&
-            event.data &&
-            event.data._bail &&
-            (failureCount || event.error)
-          ) {
-            debug('run(): nonzero failure count & found bail flag');
-            // we need to let the events complete for this file, as the worker
-            // should run any cleanup hooks
-            this._state = BAILING;
+
+        if (this._linkPartialObjects) {
+          while (event) {
+            linkEvent(event);
+            emitEvent(event, failureCount);
+            event = events.shift();
+          }
+        } else {
+          while (event) {
+            emitEvent(event, failureCount);
+            event = events.shift();
           }
-          event = events.shift();
         }
         if (this._state === BAILING) {
           debug('run(): terminating pool due to "bail" flag');
@@ -154,6 +230,7 @@ class ParallelBufferedRunner extends Runner {
    * Returns the listener for later call to `process.removeListener()`.
    * @param {BufferedWorkerPool} pool - Worker pool
    * @returns {SigIntListener} Listener
+   * @private
    */
   _bindSigIntListener(pool) {
     const sigIntListener = async () => {
@@ -197,15 +274,19 @@ class ParallelBufferedRunner extends Runner {
    * @param {{files: string[], options: Options}} opts - Files to run and
    * command-line options, respectively.
    */
-  run(callback, {files, options} = {}) {
+  run(callback, {files, options = {}} = {}) {
     /**
      * Listener on `Process.SIGINT` which tries to cleanly terminate the worker pool.
      */
     let sigIntListener;
+
+    // assign the reporter the worker will use, which will be different than the
+    // main process' reporter
+    options = {...options, reporter: this._workerReporter};
+
     // This function should _not_ return a `Promise`; its parent (`Runner#run`)
     // returns this instance, so this should do the same. However, we want to make
     // use of `async`/`await`, so we use this IIFE.
-
     (async () => {
       /**
        * This is an interval that outputs stats about the worker pool every so often
@@ -235,6 +316,11 @@ class ParallelBufferedRunner extends Runner {
 
         this.emit(EVENT_RUN_BEGIN);
 
+        options = {...options};
+        DENY_OPTIONS.forEach(opt => {
+          delete options[opt];
+        });
+
         const results = await allSettled(
           files.map(this._createFileRunner(pool, options))
         );
@@ -257,6 +343,7 @@ class ParallelBufferedRunner extends Runner {
         if (this._state === ABORTING) {
           return;
         }
+
         this.emit(EVENT_RUN_END);
         debug('run(): completing with failure count %d', this.failures);
         callback(this.failures);
@@ -275,6 +362,57 @@ class ParallelBufferedRunner extends Runner {
     })();
     return this;
   }
+
+  /**
+   * Toggle partial object linking behavior; used for building object references from
+   * unique ID's.
+   * @param {boolean} [value] - If `true`, enable partial object linking, otherwise disable
+   * @returns {Runner}
+   * @chainable
+   * @public
+   * @example
+   * // this reporter needs proper object references when run in parallel mode
+   * class MyReporter() {
+   *   constructor(runner) {
+   *     this.runner.linkPartialObjects(true)
+   *       .on(EVENT_SUITE_BEGIN, suite => {
+             // this Suite may be the same object...
+  *       })
+  *       .on(EVENT_TEST_BEGIN, test => {
+  *         // ...as the `test.parent` property
+  *       });
+  *   }
+  * }
+  */
+  linkPartialObjects(value) {
+    this._linkPartialObjects = Boolean(value);
+    return super.linkPartialObjects(value);
+  }
+
+  /**
+   * If this class is the `Runner` in use, then this is going to return `true`.
+   *
+   * For use by reporters.
+   * @returns {true}
+   * @public
+   */
+  isParallelMode() {
+    return true;
+  }
+
+  /**
+   * Configures an alternate reporter for worker processes to use. Subclasses
+   * using worker processes should implement this.
+   * @public
+   * @param {string} path - Absolute path to alternate reporter for worker processes to use
+   * @returns {Runner}
+   * @throws When in serial mode
+   * @chainable
+   */
+  workerReporter(reporter) {
+    this._workerReporter = reporter;
+    return this;
+  }
 }
 
 module.exports = ParallelBufferedRunner;

package/lib/nodejs/reporters/parallel-buffered.js

@@ -1,7 +1,7 @@
 /**
  * "Buffered" reporter used internally by a worker process when running in parallel mode.
- * @module reporters/parallel-buffered
- * @private
+ * @module nodejs/reporters/parallel-buffered
+ * @public
  */
 
 'use strict';
@@ -53,15 +53,16 @@ const EVENT_NAMES = [
 const ONCE_EVENT_NAMES = [EVENT_DELAY_BEGIN, EVENT_DELAY_END];
 
 /**
- * The `ParallelBuffered` reporter is for use by concurrent runs. Instead of outputting
- * to `STDOUT`, etc., it retains a list of events it receives and hands these
- * off to the callback passed into {@link Mocha#run}. That callback will then
- * return the data to the main process.
- * @private
+ * The `ParallelBuffered` reporter is used by each worker process in "parallel"
+ * mode, by default.  Instead of reporting to to `STDOUT`, etc., it retains a
+ * list of events it receives and hands these off to the callback passed into
+ * {@link Mocha#run}. That callback will then return the data to the main
+ * process.
+ * @public
  */
 class ParallelBuffered extends Base {
   /**
-   * Listens for {@link Runner} events and retains them in an `events` instance prop.
+   * Calls {@link ParallelBuffered#createListeners}
    * @param {Runner} runner
    */
   constructor(runner, opts) {
@@ -70,50 +71,81 @@ class ParallelBuffered extends Base {
     /**
      * Retained list of events emitted from the {@link Runner} instance.
      * @type {BufferedEvent[]}
-     * @memberOf Buffered
+     * @public
      */
-    const events = (this.events = []);
+    this.events = [];
 
     /**
-     * mapping of event names to listener functions we've created,
-     * so we can cleanly _remove_ them from the runner once it's completed.
+     * Map of `Runner` event names to listeners (for later teardown)
+     * @public
+     * @type {Map<string,EventListener>}
      */
-    const listeners = new Map();
+    this.listeners = new Map();
 
-    /**
-     * Creates a listener for event `eventName` and adds it to the `listeners`
-     * map. This is a defensive measure, so that we don't a) leak memory or b)
-     * remove _other_ listeners that may not be associated with this reporter.
-     * @param {string} eventName - Event name
-     */
-    const createListener = eventName =>
-      listeners
-        .set(eventName, (runnable, err) => {
-          events.push(SerializableEvent.create(eventName, runnable, err));
-        })
-        .get(eventName);
+    this.createListeners(runner);
+  }
+
+  /**
+   * Returns a new listener which saves event data in memory to
+   * {@link ParallelBuffered#events}. Listeners are indexed by `eventName` and stored
+   * in {@link ParallelBuffered#listeners}. This is a defensive measure, so that we
+   * don't a) leak memory or b) remove _other_ listeners that may not be
+   * associated with this reporter.
+   *
+   * Subclasses could override this behavior.
+   *
+   * @public
+   * @param {string} eventName - Name of event to create listener for
+   * @returns {EventListener}
+   */
+  createListener(eventName) {
+    const listener = (runnable, err) => {
+      this.events.push(SerializableEvent.create(eventName, runnable, err));
+    };
+    return this.listeners.set(eventName, listener).get(eventName);
+  }
 
+  /**
+   * Creates event listeners (using {@link ParallelBuffered#createListener}) for each
+   * reporter-relevant event emitted by a {@link Runner}. This array is drained when
+   * {@link ParallelBuffered#done} is called by {@link Runner#run}.
+   *
+   * Subclasses could override this behavior.
+   * @public
+   * @param {Runner} runner - Runner instance
+   * @returns {ParallelBuffered}
+   * @chainable
+   */
+  createListeners(runner) {
     EVENT_NAMES.forEach(evt => {
-      runner.on(evt, createListener(evt));
+      runner.on(evt, this.createListener(evt));
     });
     ONCE_EVENT_NAMES.forEach(evt => {
-      runner.once(evt, createListener(evt));
+      runner.once(evt, this.createListener(evt));
     });
 
     runner.once(EVENT_RUN_END, () => {
       debug('received EVENT_RUN_END');
-      listeners.forEach((listener, evt) => {
+      this.listeners.forEach((listener, evt) => {
         runner.removeListener(evt, listener);
-        listeners.delete(evt);
+        this.listeners.delete(evt);
       });
     });
+
+    return this;
   }
 
   /**
    * Calls the {@link Mocha#run} callback (`callback`) with the test failure
    * count and the array of {@link BufferedEvent} objects. Resets the array.
+   *
+   * This is called directly by `Runner#run` and should not be called by any other consumer.
+   *
+   * Subclasses could override this.
+   *
    * @param {number} failures - Number of failed tests
    * @param {Function} callback - The callback passed to {@link Mocha#run}.
+   * @public
    */
   done(failures, callback) {
     callback(SerializableWorkerResult.create(this.events, failures));

package/lib/nodejs/serializer.js

@@ -56,7 +56,7 @@ class SerializableWorkerResult {
   /**
    * Instantiates a new {@link SerializableWorkerResult}.
    * @param {...any} args - Args to constructor
-   * @returns {SerilizableWorkerResult}
+   * @returns {SerializableWorkerResult}
    */
   static create(...args) {
     return new SerializableWorkerResult(...args);
@@ -131,7 +131,11 @@ class SerializableEvent {
    */
   constructor(eventName, originalValue, originalError) {
     if (!eventName) {
-      throw new Error('expected a non-empty `eventName` string argument');
+      throw createInvalidArgumentTypeError(
+        'Empty `eventName` string argument',
+        'eventName',
+        'string'
+      );
     }
     /**
      * The event name.
@@ -140,8 +144,10 @@ class SerializableEvent {
     this.eventName = eventName;
     const originalValueType = type(originalValue);
     if (originalValueType !== 'object' && originalValueType !== 'undefined') {
-      throw new Error(
-        `expected object, received [${originalValueType}]: ${originalValue}`
+      throw createInvalidArgumentTypeError(
+        `Expected object but received ${originalValueType}`,
+        'originalValue',
+        'object'
       );
     }
     /**
@@ -190,7 +196,8 @@ class SerializableEvent {
       parent[key] = Object.create(null);
       return;
     }
-    if (type(value) === 'error' || value instanceof Error) {
+    let _type = type(value);
+    if (_type === 'error') {
       // we need to reference the stack prop b/c it's lazily-loaded.
       // `__type` is necessary for deserialization to create an `Error` later.
       // `message` is apparently not enumerable, so we must handle it specifically.
@@ -200,10 +207,11 @@ class SerializableEvent {
         __type: 'Error'
       });
       parent[key] = value;
-      // after this, the result of type(value) will be `object`, and we'll throw
+      // after this, set the result of type(value) to be `object`, and we'll throw
       // whatever other junk is in the original error into the new `value`.
+      _type = 'object';
     }
-    switch (type(value)) {
+    switch (_type) {
       case 'object':
         if (type(value.serialize) === 'function') {
           parent[key] = value.serialize();

package/lib/nodejs/worker.js

@@ -12,19 +12,13 @@ const {
 } = require('../errors');
 const workerpool = require('workerpool');
 const Mocha = require('../mocha');
-const {
-  handleRequires,
-  validatePlugin,
-  loadRootHooks
-} = require('../cli/run-helpers');
+const {handleRequires, validateLegacyPlugin} = require('../cli/run-helpers');
 const d = require('debug');
 const debug = d.debug(`mocha:parallel:worker:${process.pid}`);
 const isDebugEnabled = d.enabled(`mocha:parallel:worker:${process.pid}`);
 const {serialize} = require('./serializer');
 const {setInterval, clearInterval} = global;
 
-const BUFFERED_REPORTER_PATH = require.resolve('./reporters/parallel-buffered');
-
 let rootHooks;
 
 if (workerpool.isMainThread) {
@@ -45,9 +39,13 @@ if (workerpool.isMainThread) {
  * @param {Options} argv - Command-line options
  */
 let bootstrap = async argv => {
-  const rawRootHooks = await handleRequires(argv.require);
-  rootHooks = await loadRootHooks(rawRootHooks);
-  validatePlugin(argv, 'ui', Mocha.interfaces);
+  // globalSetup and globalTeardown do not run in workers
+  const plugins = await handleRequires(argv.require, {
+    ignoredPlugins: ['mochaGlobalSetup', 'mochaGlobalTeardown']
+  });
+  validateLegacyPlugin(argv, 'ui', Mocha.interfaces);
+
+  rootHooks = plugins.rootHooks;
   bootstrap = () => {};
   debug('bootstrap(): finished with args: %O', argv);
 };
@@ -91,8 +89,6 @@ async function run(filepath, serializedOptions = '{}') {
   }
 
   const opts = Object.assign({ui: 'bdd'}, argv, {
-    // workers only use the `Buffered` reporter.
-    reporter: BUFFERED_REPORTER_PATH,
     // if this was true, it would cause infinite recursion.
     parallel: false,
     // this doesn't work in parallel mode
@@ -125,6 +121,7 @@ async function run(filepath, serializedOptions = '{}') {
     mocha.run(result => {
       // Runner adds these; if we don't remove them, we'll get a leak.
       process.removeAllListeners('uncaughtException');
+      process.removeAllListeners('unhandledRejection');
 
       try {
         const serialized = serialize(result);