mocha 7.1.1 → 8.0.1

package/lib/nodejs/buffered-worker-pool.js

@@ -0,0 +1,174 @@
+/**
+ * A wrapper around a third-party child process worker pool implementation.
+ * Used by {@link module:buffered-runner}.
+ * @private
+ * @module buffered-worker-pool
+ */
+
+'use strict';
+
+const serializeJavascript = require('serialize-javascript');
+const workerpool = require('workerpool');
+const {deserialize} = require('./serializer');
+const debug = require('debug')('mocha:parallel:buffered-worker-pool');
+const {createInvalidArgumentTypeError} = require('../errors');
+
+const WORKER_PATH = require.resolve('./worker.js');
+
+/**
+ * A mapping of Mocha `Options` objects to serialized values.
+ *
+ * This is helpful because we tend to same the same options over and over
+ * over IPC.
+ * @type {WeakMap<Options,string>}
+ */
+let optionsCache = new WeakMap();
+
+/**
+ * These options are passed into the [workerpool](https://npm.im/workerpool) module.
+ * @type {Partial<WorkerPoolOptions>}
+ */
+const WORKER_POOL_DEFAULT_OPTS = {
+  // use child processes, not worker threads!
+  workerType: 'process',
+  // ensure the same flags sent to `node` for this `mocha` invocation are passed
+  // along to children
+  forkOpts: {execArgv: process.execArgv},
+  maxWorkers: workerpool.cpus - 1
+};
+
+/**
+ * A wrapper around a third-party worker pool implementation.
+ * @private
+ */
+class BufferedWorkerPool {
+  /**
+   * Creates an underlying worker pool instance; determines max worker count
+   * @param {Partial<WorkerPoolOptions>} [opts] - Options
+   */
+  constructor(opts = {}) {
+    const maxWorkers = Math.max(
+      1,
+      typeof opts.maxWorkers === 'undefined'
+        ? WORKER_POOL_DEFAULT_OPTS.maxWorkers
+        : opts.maxWorkers
+    );
+
+    /* istanbul ignore next */
+    if (workerpool.cpus < 2) {
+      // TODO: decide whether we should warn
+      debug(
+        'not enough CPU cores available to run multiple jobs; avoid --parallel on this machine'
+      );
+    } else if (maxWorkers >= workerpool.cpus) {
+      // TODO: decide whether we should warn
+      debug(
+        '%d concurrent job(s) requested, but only %d core(s) available',
+        maxWorkers,
+        workerpool.cpus
+      );
+    }
+    /* istanbul ignore next */
+    debug(
+      'run(): starting worker pool of max size %d, using node args: %s',
+      maxWorkers,
+      process.execArgv.join(' ')
+    );
+
+    this.options = Object.assign({}, WORKER_POOL_DEFAULT_OPTS, opts, {
+      maxWorkers
+    });
+    this._pool = workerpool.pool(WORKER_PATH, this.options);
+  }
+
+  /**
+   * Terminates all workers in the pool.
+   * @param {boolean} [force] - Whether to force-kill workers. By default, lets workers finish their current task before termination.
+   * @private
+   * @returns {Promise<void>}
+   */
+  async terminate(force = false) {
+    /* istanbul ignore next */
+    debug('terminate(): terminating with force = %s', force);
+    return this._pool.terminate(force);
+  }
+
+  /**
+   * Adds a test file run to the worker pool queue for execution by a worker process.
+   *
+   * Handles serialization/deserialization.
+   *
+   * @param {string} filepath - Filepath of test
+   * @param {Options} [options] - Options for Mocha instance
+   * @private
+   * @returns {Promise<SerializedWorkerResult>}
+   */
+  async run(filepath, options = {}) {
+    if (!filepath || typeof filepath !== 'string') {
+      throw createInvalidArgumentTypeError(
+        'Expected a non-empty filepath',
+        'filepath',
+        'string'
+      );
+    }
+    const serializedOptions = BufferedWorkerPool.serializeOptions(options);
+    const result = await this._pool.exec('run', [filepath, serializedOptions]);
+    return deserialize(result);
+  }
+
+  /**
+   * Returns stats about the state of the worker processes in the pool.
+   *
+   * Used for debugging.
+   *
+   * @private
+   */
+  stats() {
+    return this._pool.stats();
+  }
+
+  /**
+   * Instantiates a {@link WorkerPool}.
+   * @private
+   */
+  static create(...args) {
+    return new BufferedWorkerPool(...args);
+  }
+
+  /**
+   * Given Mocha options object `opts`, serialize into a format suitable for
+   * transmission over IPC.
+   *
+   * @param {Options} [opts] - Mocha options
+   * @private
+   * @returns {string} Serialized options
+   */
+  static serializeOptions(opts = {}) {
+    if (!optionsCache.has(opts)) {
+      const serialized = serializeJavascript(opts, {
+        unsafe: true, // this means we don't care about XSS
+        ignoreFunction: true // do not serialize functions
+      });
+      optionsCache.set(opts, serialized);
+      /* istanbul ignore next */
+      debug(
+        'serializeOptions(): serialized options %O to: %s',
+        opts,
+        serialized
+      );
+    }
+    return optionsCache.get(opts);
+  }
+
+  /**
+   * Resets internal cache of serialized options objects.
+   *
+   * For testing/debugging
+   * @private
+   */
+  static resetOptionsCache() {
+    optionsCache = new WeakMap();
+  }
+}
+
+exports.BufferedWorkerPool = BufferedWorkerPool;

package/lib/{growl.js → nodejs/growl.js}

@@ -8,7 +8,8 @@
 const os = require('os');
 const path = require('path');
 const {sync: which} = require('which');
-const {EVENT_RUN_END} = require('./runner').constants;
+const {EVENT_RUN_END} = require('../runner').constants;
+const {isBrowser} = require('../utils');
 
 /**
  * @summary
@@ -25,7 +26,7 @@ const {EVENT_RUN_END} = require('./runner').constants;
  * @return {boolean} whether Growl notification support can be expected
  */
 exports.isCapable = () => {
-  if (!process.browser) {
+  if (!isBrowser()) {
     return getSupportBinaries().reduce(
       (acc, binary) => acc || Boolean(which(binary, {nothrow: true})),
       false

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

@@ -0,0 +1,293 @@
+/**
+ * A test Runner that uses a {@link module:buffered-worker-pool}.
+ * @module parallel-buffered-runner
+ * @private
+ */
+
+'use strict';
+
+const allSettled = require('promise.allsettled');
+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');
+
+/**
+ * Outputs a debug statement with worker stats
+ * @param {BufferedWorkerPool} pool - Worker pool
+ */
+/* istanbul ignore next */
+const debugStats = pool => {
+  const {totalWorkers, busyWorkers, idleWorkers, pendingTasks} = pool.stats();
+  debug(
+    '%d/%d busy workers; %d idle; %d tasks queued',
+    busyWorkers,
+    totalWorkers,
+    idleWorkers,
+    pendingTasks
+  );
+};
+
+/**
+ * The interval at which we will display stats for worker processes in debug mode
+ */
+const DEBUG_STATS_INTERVAL = 5000;
+
+const ABORTED = 'ABORTED';
+const IDLE = 'IDLE';
+const ABORTING = 'ABORTING';
+const RUNNING = 'RUNNING';
+const BAILING = 'BAILING';
+const BAILED = 'BAILED';
+const COMPLETE = 'COMPLETE';
+
+const states = createMap({
+  [IDLE]: new Set([RUNNING, ABORTING]),
+  [RUNNING]: new Set([COMPLETE, BAILING, ABORTING]),
+  [COMPLETE]: new Set(),
+  [ABORTED]: new Set(),
+  [ABORTING]: new Set([ABORTED]),
+  [BAILING]: new Set([BAILED, ABORTING]),
+  [BAILED]: new Set([COMPLETE, ABORTING])
+});
+
+/**
+ * This `Runner` delegates tests runs to worker threads.  Does not execute any
+ * {@link Runnable}s by itself!
+ * @private
+ */
+class ParallelBufferedRunner extends Runner {
+  constructor(...args) {
+    super(...args);
+
+    let state = IDLE;
+    Object.defineProperty(this, '_state', {
+      get() {
+        return state;
+      },
+      set(newState) {
+        if (states[state].has(newState)) {
+          state = newState;
+        } else {
+          throw new Error(`invalid state transition: ${state} => ${newState}`);
+        }
+      }
+    });
+
+    this.once(Runner.constants.EVENT_RUN_END, () => {
+      this._state = COMPLETE;
+    });
+  }
+
+  /**
+   * Returns a mapping function to enqueue a file in the worker pool and return results of its execution.
+   * @param {BufferedWorkerPool} pool - Worker pool
+   * @param {Options} options - Mocha options
+   * @returns {FileRunner} Mapping function
+   */
+  _createFileRunner(pool, options) {
+    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.
+          // TODO: determine if this is the desired behavior, or if we
+          // should report the events of this run anyway.
+          return;
+        }
+        debug(
+          'run(): completed run of file %s; %d failures / %d events',
+          file,
+          failureCount,
+          events.length
+        );
+        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;
+          }
+          event = events.shift();
+        }
+        if (this._state === BAILING) {
+          debug('run(): terminating pool due to "bail" flag');
+          this._state = BAILED;
+          await pool.terminate();
+        }
+      } catch (err) {
+        if (this._state === BAILED || this._state === ABORTING) {
+          debug(
+            'run(): worker pool terminated with intent; skipping file %s',
+            file
+          );
+        } else {
+          // this is an uncaught exception
+          debug('run(): encountered uncaught exception: %O', err);
+          if (this.allowUncaught) {
+            // still have to clean up
+            this._state = ABORTING;
+            await pool.terminate(true);
+          }
+          throw err;
+        }
+      } finally {
+        debug('run(): done running file %s', file);
+      }
+    };
+  }
+
+  /**
+   * Listen on `Process.SIGINT`; terminate pool if caught.
+   * Returns the listener for later call to `process.removeListener()`.
+   * @param {BufferedWorkerPool} pool - Worker pool
+   * @returns {SigIntListener} Listener
+   */
+  _bindSigIntListener(pool) {
+    const sigIntListener = async () => {
+      debug('run(): caught a SIGINT');
+      this._state = ABORTING;
+
+      try {
+        debug('run(): force-terminating worker pool');
+        await pool.terminate(true);
+      } catch (err) {
+        console.error(
+          `Error while attempting to force-terminate worker pool: ${err}`
+        );
+        process.exitCode = 1;
+      } finally {
+        process.nextTick(() => {
+          debug('run(): imminent death');
+          this._state = ABORTED;
+          process.kill(process.pid, 'SIGINT');
+        });
+      }
+    };
+
+    process.once('SIGINT', sigIntListener);
+
+    return sigIntListener;
+  }
+
+  /**
+   * Runs Mocha tests by creating a thread pool, then delegating work to the
+   * worker threads.
+   *
+   * Each worker receives one file, and as workers become available, they take a
+   * file from the queue and run it. The worker thread execution is treated like
+   * an RPC--it returns a `Promise` containing serialized information about the
+   * run.  The information is processed as it's received, and emitted to a
+   * {@link Reporter}, which is likely listening for these events.
+   *
+   * @param {Function} callback - Called with an exit code corresponding to
+   * number of test failures.
+   * @param {{files: string[], options: Options}} opts - Files to run and
+   * command-line options, respectively.
+   */
+  run(callback, {files, options} = {}) {
+    /**
+     * Listener on `Process.SIGINT` which tries to cleanly terminate the worker pool.
+     */
+    let sigIntListener;
+    // 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
+       */
+      let debugInterval;
+
+      /**
+       * @type {BufferedWorkerPool}
+       */
+      let pool;
+
+      try {
+        pool = BufferedWorkerPool.create({maxWorkers: options.jobs});
+
+        sigIntListener = this._bindSigIntListener(pool);
+
+        /* istanbul ignore next */
+        debugInterval = setInterval(
+          () => debugStats(pool),
+          DEBUG_STATS_INTERVAL
+        ).unref();
+
+        // this is set for uncaught exception handling in `Runner#uncaught`
+        // TODO: `Runner` should be using a state machine instead.
+        this.started = true;
+        this._state = RUNNING;
+
+        this.emit(EVENT_RUN_BEGIN);
+
+        const results = await allSettled(
+          files.map(this._createFileRunner(pool, options))
+        );
+
+        // note that pool may already be terminated due to --bail
+        await pool.terminate();
+
+        results
+          .filter(({status}) => status === 'rejected')
+          .forEach(({reason}) => {
+            if (this.allowUncaught) {
+              // yep, just the first one.
+              throw reason;
+            }
+            // "rejected" will correspond to uncaught exceptions.
+            // unlike the serial runner, the parallel runner can always recover.
+            this.uncaught(reason);
+          });
+
+        if (this._state === ABORTING) {
+          return;
+        }
+        this.emit(EVENT_RUN_END);
+        debug('run(): completing with failure count %d', this.failures);
+        callback(this.failures);
+      } catch (err) {
+        // this `nextTick` takes us out of the `Promise` scope, so the
+        // exception will not be caught and returned as a rejected `Promise`,
+        // which would lead to an `unhandledRejection` event.
+        process.nextTick(() => {
+          debug('run(): re-throwing uncaught exception');
+          throw err;
+        });
+      } finally {
+        clearInterval(debugInterval);
+        process.removeListener('SIGINT', sigIntListener);
+      }
+    })();
+    return this;
+  }
+}
+
+module.exports = ParallelBufferedRunner;
+
+/**
+ * Listener function intended to be bound to `Process.SIGINT` event
+ * @callback SigIntListener
+ * @returns {Promise<void>}
+ */
+
+/**
+ * A function accepting a test file path and returning the results of a test run
+ * @callback FileRunner
+ * @param {string} filename - File to run
+ * @returns {Promise<SerializedWorkerResult>}
+ */

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

@@ -0,0 +1,133 @@
+/**
+ * "Buffered" reporter used internally by a worker process when running in parallel mode.
+ * @module reporters/parallel-buffered
+ * @private
+ */
+
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+
+const {
+  EVENT_SUITE_BEGIN,
+  EVENT_SUITE_END,
+  EVENT_TEST_FAIL,
+  EVENT_TEST_PASS,
+  EVENT_TEST_PENDING,
+  EVENT_TEST_BEGIN,
+  EVENT_TEST_END,
+  EVENT_TEST_RETRY,
+  EVENT_DELAY_BEGIN,
+  EVENT_DELAY_END,
+  EVENT_HOOK_BEGIN,
+  EVENT_HOOK_END,
+  EVENT_RUN_END
+} = require('../../runner').constants;
+const {SerializableEvent, SerializableWorkerResult} = require('../serializer');
+const debug = require('debug')('mocha:reporters:buffered');
+const Base = require('../../reporters/base');
+
+/**
+ * List of events to listen to; these will be buffered and sent
+ * when `Mocha#run` is complete (via {@link ParallelBuffered#done}).
+ */
+const EVENT_NAMES = [
+  EVENT_SUITE_BEGIN,
+  EVENT_SUITE_END,
+  EVENT_TEST_BEGIN,
+  EVENT_TEST_PENDING,
+  EVENT_TEST_FAIL,
+  EVENT_TEST_PASS,
+  EVENT_TEST_RETRY,
+  EVENT_TEST_END,
+  EVENT_HOOK_BEGIN,
+  EVENT_HOOK_END
+];
+
+/**
+ * Like {@link EVENT_NAMES}, except we expect these events to only be emitted
+ * by the `Runner` once.
+ */
+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
+ */
+class ParallelBuffered extends Base {
+  /**
+   * Listens for {@link Runner} events and retains them in an `events` instance prop.
+   * @param {Runner} runner
+   */
+  constructor(runner, opts) {
+    super(runner, opts);
+
+    /**
+     * Retained list of events emitted from the {@link Runner} instance.
+     * @type {BufferedEvent[]}
+     * @memberOf Buffered
+     */
+    const 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.
+     */
+    const 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);
+
+    EVENT_NAMES.forEach(evt => {
+      runner.on(evt, createListener(evt));
+    });
+    ONCE_EVENT_NAMES.forEach(evt => {
+      runner.once(evt, createListener(evt));
+    });
+
+    runner.once(EVENT_RUN_END, () => {
+      debug('received EVENT_RUN_END');
+      listeners.forEach((listener, evt) => {
+        runner.removeListener(evt, listener);
+        listeners.delete(evt);
+      });
+    });
+  }
+
+  /**
+   * Calls the {@link Mocha#run} callback (`callback`) with the test failure
+   * count and the array of {@link BufferedEvent} objects. Resets the array.
+   * @param {number} failures - Number of failed tests
+   * @param {Function} callback - The callback passed to {@link Mocha#run}.
+   */
+  done(failures, callback) {
+    callback(SerializableWorkerResult.create(this.events, failures));
+    this.events = []; // defensive
+  }
+}
+
+/**
+ * Serializable event data from a `Runner`.  Keys of the `data` property
+ * beginning with `__` will be converted into a function which returns the value
+ * upon deserialization.
+ * @typedef {Object} BufferedEvent
+ * @property {string} name - Event name
+ * @property {object} data - Event parameters
+ */
+
+module.exports = ParallelBuffered;