mocha 9.1.2

package/lib/mocharc.json

@@ -0,0 +1,10 @@
+{
+  "diff": true,
+  "extension": ["js", "cjs", "mjs"],
+  "package": "./package.json",
+  "reporter": "spec",
+  "slow": 75,
+  "timeout": 2000,
+  "ui": "bdd",
+  "watch-ignore": ["node_modules", ".git"]
+}

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

@@ -0,0 +1,172 @@
+/**
+ * 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 = {...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/nodejs/esm-utils.js

@@ -0,0 +1,109 @@
+const path = require('path');
+const url = require('url');
+
+const formattedImport = async file => {
+  if (path.isAbsolute(file)) {
+    try {
+      return await import(url.pathToFileURL(file));
+    } catch (err) {
+      // This is a hack created because ESM in Node.js (at least in Node v15.5.1) does not emit
+      // the location of the syntax error in the error thrown.
+      // This is problematic because the user can't see what file has the problem,
+      // so we add the file location to the error.
+      // This `if` should be removed once Node.js fixes the problem.
+      if (
+        err instanceof SyntaxError &&
+        err.message &&
+        err.stack &&
+        !err.stack.includes(file)
+      ) {
+        const newErrorWithFilename = new SyntaxError(err.message);
+        newErrorWithFilename.stack = err.stack.replace(
+          /^SyntaxError/,
+          `SyntaxError[ @${file} ]`
+        );
+        throw newErrorWithFilename;
+      }
+      throw err;
+    }
+  }
+  return import(file);
+};
+
+const hasStableEsmImplementation = (() => {
+  const [major, minor] = process.version.split('.');
+  // ESM is stable from v12.22.0 onward
+  // https://nodejs.org/api/esm.html#esm_modules_ecmascript_modules
+  const majorNumber = parseInt(major.slice(1), 10);
+  const minorNumber = parseInt(minor, 10);
+  return majorNumber > 12 || (majorNumber === 12 && minorNumber >= 22);
+})();
+
+exports.requireOrImport = hasStableEsmImplementation
+  ? async file => {
+      if (path.extname(file) === '.mjs') {
+        return formattedImport(file);
+      }
+      try {
+        return dealWithExports(await formattedImport(file));
+      } catch (err) {
+        if (
+          err.code === 'ERR_MODULE_NOT_FOUND' ||
+          err.code === 'ERR_UNKNOWN_FILE_EXTENSION' ||
+          err.code === 'ERR_UNSUPPORTED_DIR_IMPORT'
+        ) {
+          try {
+            return require(file);
+          } catch (requireErr) {
+            if (requireErr.code === 'ERR_REQUIRE_ESM') {
+              // This happens when the test file is a JS file, but via type:module is actually ESM,
+              // AND has an import to a file that doesn't exist.
+              // This throws an `ERR_MODULE_NOT_FOUND` // error above,
+              // and when we try to `require` it here, it throws an `ERR_REQUIRE_ESM`.
+              // What we want to do is throw the original error (the `ERR_MODULE_NOT_FOUND`),
+              // and not the `ERR_REQUIRE_ESM` error, which is a red herring.
+              throw err;
+            } else {
+              throw requireErr;
+            }
+          }
+        } else {
+          throw err;
+        }
+      }
+    }
+  : implementationOfRequireOrImportForUnstableEsm;
+
+function dealWithExports(module) {
+  if (module.default) {
+    return module.default;
+  } else {
+    return {...module, default: undefined};
+  }
+}
+
+exports.loadFilesAsync = async (files, preLoadFunc, postLoadFunc) => {
+  for (const file of files) {
+    preLoadFunc(file);
+    const result = await exports.requireOrImport(path.resolve(file));
+    postLoadFunc(file, result);
+  }
+};
+
+/* istanbul ignore next */
+async function implementationOfRequireOrImportForUnstableEsm(file) {
+  if (path.extname(file) === '.mjs') {
+    return formattedImport(file);
+  }
+  // This is currently the only known way of figuring out whether a file is CJS or ESM in
+  // Node.js that doesn't necessitate calling `import` first.
+  try {
+    return require(file);
+  } catch (err) {
+    if (err.code === 'ERR_REQUIRE_ESM') {
+      return formattedImport(file);
+    } else {
+      throw err;
+    }
+  }
+}

package/lib/nodejs/file-unloader.js

@@ -0,0 +1,15 @@
+'use strict';
+
+/**
+ * This module should not be in the browser bundle, so it's here.
+ * @private
+ * @module
+ */
+
+/**
+ * Deletes a file from the `require` cache.
+ * @param {string} file - File
+ */
+exports.unloadFile = file => {
+  delete require.cache[require.resolve(file)];
+};

package/lib/nodejs/growl.js

@@ -0,0 +1,137 @@
+'use strict';
+
+/**
+ * Desktop Notifications module.
+ * @module Growl
+ */
+
+const os = require('os');
+const path = require('path');
+const {sync: which} = require('which');
+const {EVENT_RUN_END} = require('../runner').constants;
+const {isBrowser} = require('../utils');
+
+/**
+ * @summary
+ * Checks if Growl notification support seems likely.
+ *
+ * @description
+ * Glosses over the distinction between an unsupported platform
+ * and one that lacks prerequisite software installations.
+ *
+ * @public
+ * @see {@link https://github.com/tj/node-growl/blob/master/README.md|Prerequisite Installs}
+ * @see {@link Mocha#growl}
+ * @see {@link Mocha#isGrowlCapable}
+ * @return {boolean} whether Growl notification support can be expected
+ */
+exports.isCapable = () => {
+  if (!isBrowser()) {
+    return getSupportBinaries().reduce(
+      (acc, binary) => acc || Boolean(which(binary, {nothrow: true})),
+      false
+    );
+  }
+  return false;
+};
+
+/**
+ * Implements desktop notifications as a pseudo-reporter.
+ *
+ * @public
+ * @see {@link Mocha#_growl}
+ * @param {Runner} runner - Runner instance.
+ */
+exports.notify = runner => {
+  runner.once(EVENT_RUN_END, () => {
+    display(runner);
+  });
+};
+
+/**
+ * Displays the notification.
+ *
+ * @private
+ * @param {Runner} runner - Runner instance.
+ */
+const display = runner => {
+  const growl = require('growl');
+  const stats = runner.stats;
+  const symbol = {
+    cross: '\u274C',
+    tick: '\u2705'
+  };
+  let _message;
+  let message;
+  let title;
+
+  if (stats.failures) {
+    _message = `${stats.failures} of ${stats.tests} tests failed`;
+    message = `${symbol.cross} ${_message}`;
+    title = 'Failed';
+  } else {
+    _message = `${stats.passes} tests passed in ${stats.duration}ms`;
+    message = `${symbol.tick} ${_message}`;
+    title = 'Passed';
+  }
+
+  // Send notification
+  const options = {
+    image: logo(),
+    name: 'mocha',
+    title
+  };
+  growl(message, options, onCompletion);
+};
+
+/**
+ * @summary
+ * Callback for result of attempted Growl notification.
+ *
+ * @description
+ * Despite its appearance, this is <strong>not</strong> an Error-first
+ * callback -- all parameters are populated regardless of success.
+ *
+ * @private
+ * @callback Growl~growlCB
+ * @param {*} err - Error object, or <code>null</code> if successful.
+ */
+function onCompletion(err) {
+  if (err) {
+    // As notifications are tangential to our purpose, just log the error.
+    const message =
+      err.code === 'ENOENT' ? 'prerequisite software not found' : err.message;
+    console.error('notification error:', message);
+  }
+}
+
+/**
+ * Returns Mocha logo image path.
+ *
+ * @private
+ * @return {string} Pathname of Mocha logo
+ */
+const logo = () => {
+  return path.join(__dirname, '..', 'assets', 'mocha-logo-96.png');
+};
+
+/**
+ * @summary
+ * Gets platform-specific Growl support binaries.
+ *
+ * @description
+ * Somewhat brittle dependency on `growl` package implementation, but it
+ * rarely changes.
+ *
+ * @private
+ * @see {@link https://github.com/tj/node-growl/blob/master/lib/growl.js#L28-L126|setupCmd}
+ * @return {string[]} names of Growl support binaries
+ */
+const getSupportBinaries = () => {
+  const binaries = {
+    Darwin: ['terminal-notifier', 'growlnotify'],
+    Linux: ['notify-send', 'growl'],
+    Windows_NT: ['growlnotify.exe']
+  };
+  return binaries[os.type()] || [];
+};