mocha-compat 3.6.4 → 10.8.2

package/lib/cli/cli.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+'use strict';
+
+/**
+ * Contains CLI entry point and public API for programmatic usage in Node.js.
+ * - Option parsing is handled by {@link https://npm.im/yargs yargs}.
+ * - If executed via `node`, this module will run {@linkcode module:lib/cli.main main()}.
+ * @public
+ * @module lib/cli
+ */
+
+const debug = require('debug')('mocha:cli:cli');
+const symbols = require('log-symbols');
+const yargs = require('yargs/yargs');
+const path = require('path');
+const {
+  loadRc,
+  loadPkgRc,
+  loadOptions,
+  YARGS_PARSER_CONFIG
+} = require('./options');
+const lookupFiles = require('./lookup-files');
+const commands = require('./commands');
+const ansi = require('ansi-colors');
+const {repository, homepage, version, discord} = require('../../package.json');
+const {cwd} = require('../utils');
+
+/**
+ * - Accepts an `Array` of arguments
+ * - Modifies {@link https://nodejs.org/api/modules.html#modules_module_paths Node.js' search path} for easy loading of consumer modules
+ * - Sets {@linkcode https://nodejs.org/api/errors.html#errors_error_stacktracelimit Error.stackTraceLimit} to `Infinity`
+ * @public
+ * @summary Mocha's main command-line entry-point.
+ * @param {string[]} argv - Array of arguments to parse, or by default the lovely `process.argv.slice(2)`
+ * @param {object} [mochaArgs] - Object of already parsed Mocha arguments (by bin/mocha)
+ */
+exports.main = (argv = process.argv.slice(2), mochaArgs) => {
+  debug('entered main with raw args', argv);
+  // ensure we can require() from current working directory
+  if (typeof module.paths !== 'undefined') {
+    module.paths.push(cwd(), path.resolve('node_modules'));
+  }
+
+  Error.stackTraceLimit = Infinity; // configurable via --stack-trace-limit?
+
+  var args = mochaArgs || loadOptions(argv);
+
+  yargs()
+    .scriptName('mocha-compat-10')
+    .command(commands.run)
+    .command(commands.init)
+    .updateStrings({
+      'Positionals:': 'Positional Arguments',
+      'Options:': 'Other Options',
+      'Commands:': 'Commands'
+    })
+    .fail((msg, err, yargs) => {
+      debug('caught error sometime before command handler: %O', err);
+      yargs.showHelp();
+      console.error(`\n${symbols.error} ${ansi.red('ERROR:')} ${msg}`);
+      process.exitCode = 1;
+    })
+    .help('help', 'Show usage information & exit')
+    .alias('help', 'h')
+    .version('version', 'Show version number & exit', version)
+    .alias('version', 'V')
+    .wrap(process.stdout.columns ? Math.min(process.stdout.columns, 80) : 80)
+    .epilog(
+      `Mocha Resources
+    Chat: ${ansi.magenta(discord)}
+  GitHub: ${ansi.blue(repository.url)}
+    Docs: ${ansi.yellow(homepage)}
+      `
+    )
+    .parserConfiguration(YARGS_PARSER_CONFIG)
+    .config(args)
+    .parse(args._);
+};
+
+exports.lookupFiles = lookupFiles;
+exports.loadOptions = loadOptions;
+exports.loadPkgRc = loadPkgRc;
+exports.loadRc = loadRc;
+
+// allow direct execution
+if (require.main === module) {
+  exports.main();
+}

package/lib/cli/collect-files.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const ansi = require('ansi-colors');
+const debug = require('debug')('mocha:cli:run:helpers');
+const minimatch = require('minimatch');
+const {NO_FILES_MATCH_PATTERN} = require('../errors').constants;
+const lookupFiles = require('./lookup-files');
+const {castArray} = require('../utils');
+
+/**
+ * Exports a function that collects test files from CLI parameters.
+ * @see module:lib/cli/run-helpers
+ * @see module:lib/cli/watch-run
+ * @module
+ * @private
+ */
+
+/**
+ * Smash together an array of test files in the correct order
+ * @param {FileCollectionOptions} [opts] - Options
+ * @returns {FileCollectionResponse} An object containing a list of files to test and unmatched files.
+ * @private
+ */
+module.exports = ({
+  ignore,
+  extension,
+  file: fileArgs,
+  recursive,
+  sort,
+  spec
+} = {}) => {
+  const unmatchedSpecFiles = [];
+  const specFiles = spec.reduce((specFiles, arg) => {
+    try {
+      const moreSpecFiles = castArray(lookupFiles(arg, extension, recursive))
+        .filter(filename =>
+          ignore.every(
+            pattern =>
+              !minimatch(filename, pattern, {windowsPathsNoEscape: true})
+          )
+        )
+        .map(filename => path.resolve(filename));
+      return [...specFiles, ...moreSpecFiles];
+    } catch (err) {
+      if (err.code === NO_FILES_MATCH_PATTERN) {
+        unmatchedSpecFiles.push({message: err.message, pattern: err.pattern});
+        return specFiles;
+      }
+
+      throw err;
+    }
+  }, []);
+
+  // check that each file passed in to --file exists
+
+  const unmatchedFiles = [];
+  fileArgs.forEach(file => {
+    const fileAbsolutePath = path.resolve(file);
+    try {
+      // Used instead of fs.existsSync to ensure that file-ending less files are still resolved correctly
+      require.resolve(fileAbsolutePath);
+    } catch (err) {
+      if (err.code === 'MODULE_NOT_FOUND') {
+        unmatchedFiles.push({
+          pattern: file,
+          absolutePath: fileAbsolutePath
+        });
+        return;
+      }
+
+      throw err;
+    }
+  });
+
+  // ensure we don't sort the stuff from fileArgs; order is important!
+  if (sort) {
+    specFiles.sort();
+  }
+
+  // add files given through --file to be ran first
+  const files = [
+    ...fileArgs.map(filepath => path.resolve(filepath)),
+    ...specFiles
+  ];
+  debug('test files (in order): ', files);
+
+  if (!files.length) {
+    // give full message details when only 1 file is missing
+    const noneFoundMsg =
+      unmatchedSpecFiles.length === 1
+        ? `Error: No test files found: ${JSON.stringify(
+            unmatchedSpecFiles[0].pattern
+          )}` // stringify to print escaped characters raw
+        : 'Error: No test files found';
+    console.error(ansi.red(noneFoundMsg));
+    process.exit(1);
+  } else {
+    // print messages as a warning
+    unmatchedSpecFiles.forEach(warning => {
+      console.warn(ansi.yellow(`Warning: ${warning.message}`));
+    });
+  }
+
+  return {
+    files,
+    unmatchedFiles
+  };
+};
+
+/**
+ * An object to configure how Mocha gathers test files
+ * @private
+ * @typedef {Object} FileCollectionOptions
+ * @property {string[]} extension - File extensions to use
+ * @property {string[]} spec - Files, dirs, globs to run
+ * @property {string[]} ignore - Files, dirs, globs to ignore
+ * @property {string[]} file - List of additional files to include
+ * @property {boolean} recursive - Find files recursively
+ * @property {boolean} sort - Sort test files
+ */
+
+/**
+ * Diagnostic object containing unmatched files
+ * @typedef {Object} UnmatchedFile -
+ * @property {string} absolutePath - A list of unmatched files derived from the file arguments passed in.
+ * @property {string} pattern - A list of unmatched files derived from the file arguments passed in.
+ *
+ */
+
+/**
+ * Response object containing a list of files to test and unmatched files.
+ * @typedef {Object} FileCollectionResponse
+ * @property {string[]} files - A list of files to test
+ * @property {UnmatchedFile[]} unmatchedFiles - A list of unmatched files derived from the file arguments passed in.
+ */

package/lib/cli/commands.js

@@ -0,0 +1,14 @@
+'use strict';
+
+/**
+ * Exports Yargs commands
+ * @see https://github.com/yargs/yargs/blob/main/docs/advanced.md
+ * @private
+ * @module
+ */
+
+module.exports = {
+  init: require('./init'),
+  // default command
+  run: require('./run'),
+}

package/lib/cli/config.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Responsible for loading / finding Mocha's "rc" files.
+ *
+ * @private
+ * @module
+ */
+
+const fs = require('fs');
+const path = require('path');
+const debug = require('debug')('mocha:cli:config');
+const findUp = require('find-up');
+const {createUnparsableFileError} = require('../errors');
+const utils = require('../utils');
+
+/**
+ * These are the valid config files, in order of precedence;
+ * e.g., if `.mocharc.js` is present, then `.mocharc.yaml` and the rest
+ * will be ignored.
+ * The user should still be able to explicitly specify a file.
+ * @private
+ */
+exports.CONFIG_FILES = [
+  '.mocharc.cjs',
+  '.mocharc.js',
+  '.mocharc.yaml',
+  '.mocharc.yml',
+  '.mocharc.jsonc',
+  '.mocharc.json'
+];
+
+/**
+ * Parsers for various config filetypes. Each accepts a filepath and
+ * returns an object (but could throw)
+ */
+const parsers = (exports.parsers = {
+  yaml: filepath => require('js-yaml').load(fs.readFileSync(filepath, 'utf8')),
+  js: filepath => {
+    let cwdFilepath;
+    try {
+      debug('parsers: load cwd-relative path: "%s"', path.resolve(filepath));
+      cwdFilepath = require.resolve(path.resolve(filepath)); // evtl. throws
+      return require(cwdFilepath);
+    } catch (err) {
+      if (cwdFilepath) throw err;
+
+      debug('parsers: retry load as module-relative path: "%s"', filepath);
+      return require(filepath);
+    }
+  },
+  json: filepath =>
+    JSON.parse(
+      require('strip-json-comments')(fs.readFileSync(filepath, 'utf8'))
+    )
+});
+
+/**
+ * Loads and parses, based on file extension, a config file.
+ * "JSON" files may have comments.
+ *
+ * @private
+ * @param {string} filepath - Config file path to load
+ * @returns {Object} Parsed config object
+ */
+exports.loadConfig = filepath => {
+  let config = {};
+  debug('loadConfig: trying to parse config at %s', filepath);
+
+  const ext = path.extname(filepath);
+  try {
+    if (ext === '.yml' || ext === '.yaml') {
+      config = parsers.yaml(filepath);
+    } else if (ext === '.js' || ext === '.cjs') {
+      config = parsers.js(filepath);
+    } else {
+      config = parsers.json(filepath);
+    }
+  } catch (err) {
+    throw createUnparsableFileError(
+      `Unable to read/parse ${filepath}: ${err}`,
+      filepath
+    );
+  }
+  return config;
+};
+
+/**
+ * Find ("find up") config file starting at `cwd`
+ *
+ * @param {string} [cwd] - Current working directory
+ * @returns {string|null} Filepath to config, if found
+ */
+exports.findConfig = (cwd = utils.cwd()) => {
+  const filepath = findUp.sync(exports.CONFIG_FILES, {cwd});
+  if (filepath) {
+    debug('findConfig: found config file %s', filepath);
+  }
+  return filepath;
+};

package/lib/cli/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./cli');

package/lib/cli/init.js

@@ -0,0 +1,36 @@
+'use strict';
+
+/**
+ * Command module for "init" command
+ *
+ * @private
+ * @module
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+exports.command = 'init <path>';
+
+exports.description = 'create a client-side Mocha setup at <path>';
+
+exports.builder = yargs =>
+  yargs.positional('path', {
+    type: 'string',
+    normalize: true
+  });
+
+exports.handler = argv => {
+  const destdir = argv.path;
+  const srcdir = path.join(__dirname, '..', '..');
+  fs.mkdirSync(destdir, {recursive: true});
+  const css = fs.readFileSync(path.join(srcdir, 'mocha.css'));
+  const js = fs.readFileSync(path.join(srcdir, 'mocha.js'));
+  const tmpl = fs.readFileSync(
+    path.join(srcdir, 'lib', 'browser', 'template.html')
+  );
+  fs.writeFileSync(path.join(destdir, 'mocha.css'), css);
+  fs.writeFileSync(path.join(destdir, 'mocha.js'), js);
+  fs.writeFileSync(path.join(destdir, 'tests.spec.js'), '');
+  fs.writeFileSync(path.join(destdir, 'index.html'), tmpl);
+};

package/lib/cli/lookup-files.js

@@ -0,0 +1,150 @@
+'use strict';
+/**
+ * Contains `lookupFiles`, which takes some globs/dirs/options and returns a list of files.
+ * @module
+ * @private
+ */
+
+var fs = require('fs');
+var path = require('path');
+var glob = require('glob');
+var errors = require('../errors');
+var createNoFilesMatchPatternError = errors.createNoFilesMatchPatternError;
+var createMissingArgumentError = errors.createMissingArgumentError;
+const debug = require('debug')('mocha:cli:lookup-files');
+
+/**
+ * Determines if pathname would be a "hidden" file (or directory) on UN*X.
+ *
+ * @description
+ * On UN*X, pathnames beginning with a full stop (aka dot) are hidden during
+ * typical usage. Dotfiles, plain-text configuration files, are prime examples.
+ *
+ * @see {@link http://xahlee.info/UnixResource_dir/writ/unix_origin_of_dot_filename.html|Origin of Dot File Names}
+ *
+ * @private
+ * @param {string} pathname - Pathname to check for match.
+ * @return {boolean} whether pathname would be considered a hidden file.
+ * @example
+ * isHiddenOnUnix('.profile'); // => true
+ */
+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, w/-or-w/o leading period
+ * @return {boolean} `true` if file extension matches.
+ * @example
+ * hasMatchingExtname('foo.html', ['js', 'css']); // false
+ * hasMatchingExtname('foo.js', ['.js']); // true
+ * hasMatchingExtname('foo.js', ['js']); // ture
+ */
+const hasMatchingExtname = (pathname, exts = []) =>
+  exts
+    .map(ext => (ext.startsWith('.') ? ext : `.${ext}`))
+    .some(ext => pathname.endsWith(ext));
+
+/**
+ * Lookup file names at the given `path`.
+ *
+ * @description
+ * Filenames are returned in _traversal_ order by the OS/filesystem.
+ * **Make no assumption that the names will be sorted in any fashion.**
+ *
+ * @public
+ * @alias module:lib/cli.lookupFiles
+ * @param {string} filepath - Base path to start searching from.
+ * @param {string[]} [extensions=[]] - File extensions to look for.
+ * @param {boolean} [recursive=false] - Whether to recurse into subdirectories.
+ * @return {string[]} An array of paths.
+ * @throws {Error} if no files match pattern.
+ * @throws {TypeError} if `filepath` is directory and `extensions` not provided.
+ */
+module.exports = function lookupFiles(
+  filepath,
+  extensions = [],
+  recursive = false
+) {
+  const files = [];
+  let stat;
+
+  if (!fs.existsSync(filepath)) {
+    let pattern;
+    if (glob.hasMagic(filepath, {windowsPathsNoEscape: true})) {
+      // Handle glob as is without extensions
+      pattern = filepath;
+    } else {
+      // glob pattern e.g. 'filepath+(.js|.ts)'
+      const strExtensions = extensions
+        .map(ext => (ext.startsWith('.') ? ext : `.${ext}`))
+        .join('|');
+      pattern = `${filepath}+(${strExtensions})`;
+      debug('looking for files using glob pattern: %s', pattern);
+    }
+    files.push(
+      ...glob.sync(pattern, {
+        nodir: true,
+        windowsPathsNoEscape: true
+      })
+    );
+    if (!files.length) {
+      throw createNoFilesMatchPatternError(
+        `Cannot find any files matching pattern "${filepath}"`,
+        filepath
+      );
+    }
+    return files;
+  }
+
+  // Handle file
+  try {
+    stat = fs.statSync(filepath);
+    if (stat.isFile()) {
+      return filepath;
+    }
+  } catch (err) {
+    // ignore error
+    return;
+  }
+
+  // Handle directory
+  fs.readdirSync(filepath).forEach(dirent => {
+    const pathname = path.join(filepath, dirent);
+    let stat;
+
+    try {
+      stat = fs.statSync(pathname);
+      if (stat.isDirectory()) {
+        if (recursive) {
+          files.push(...lookupFiles(pathname, extensions, recursive));
+        }
+        return;
+      }
+    } catch (ignored) {
+      return;
+    }
+    if (!extensions.length) {
+      throw createMissingArgumentError(
+        `Argument '${extensions}' required when argument '${filepath}' is a directory`,
+        'extensions',
+        'array'
+      );
+    }
+
+    if (
+      !stat.isFile() ||
+      !hasMatchingExtname(pathname, extensions) ||
+      isHiddenOnUnix(pathname)
+    ) {
+      return;
+    }
+    files.push(pathname);
+  });
+
+  return files;
+};

package/lib/cli/node-flags.js

@@ -0,0 +1,85 @@
+'use strict';
+
+/**
+ * Some settings and code related to Mocha's handling of Node.js/V8 flags.
+ * @private
+ * @module
+ */
+
+const nodeFlags = process.allowedNodeEnvironmentFlags;
+const {isMochaFlag} = require('./run-option-metadata');
+const unparse = require('yargs-unparser');
+
+/**
+ * These flags are considered "debug" flags.
+ * @see {@link impliesNoTimeouts}
+ * @private
+ */
+const debugFlags = new Set(['inspect', 'inspect-brk']);
+
+/**
+ * Mocha has historical support for various `node` and V8 flags which might not
+ * appear in `process.allowedNodeEnvironmentFlags`.
+ * These include:
+ *   - `--preserve-symlinks`
+ *   - `--harmony-*`
+ *   - `--gc-global`
+ *   - `--trace-*`
+ *   - `--es-staging`
+ *   - `--use-strict`
+ *   - `--v8-*` (but *not* `--v8-options`)
+ * @summary Whether or not to pass a flag along to the `node` executable.
+ * @param {string} flag - Flag to test
+ * @param {boolean} [bareword=true] - If `false`, we expect `flag` to have one or two leading dashes.
+ * @returns {boolean} If the flag is considered a "Node" flag.
+ * @private
+ */
+exports.isNodeFlag = (flag, bareword = true) => {
+  if (!bareword) {
+    // check if the flag begins with dashes; if not, not a node flag.
+    if (!/^--?/.test(flag)) {
+      return false;
+    }
+    // strip the leading dashes to match against subsequent checks
+    flag = flag.replace(/^--?/, '');
+  }
+  return (
+    // check actual node flags from `process.allowedNodeEnvironmentFlags`,
+    // then historical support for various V8 and non-`NODE_OPTIONS` flags
+    // and also any V8 flags with `--v8-` prefix
+    (!isMochaFlag(flag) && nodeFlags && nodeFlags.has(flag)) ||
+    debugFlags.has(flag) ||
+    /(?:preserve-symlinks(?:-main)?|harmony(?:[_-]|$)|(?:trace[_-].+$)|gc[_-]global$|es[_-]staging$|use[_-]strict$|v8[_-](?!options).+?$)/.test(
+      flag
+    )
+  );
+};
+
+/**
+ * Returns `true` if the flag is a "debug-like" flag.  These require timeouts
+ * to be suppressed, or pausing the debugger on breakpoints will cause test failures.
+ * @param {string} flag - Flag to test
+ * @returns {boolean}
+ * @private
+ */
+exports.impliesNoTimeouts = flag => debugFlags.has(flag);
+
+/**
+ * All non-strictly-boolean arguments to node--those with values--must specify those values using `=`, e.g., `--inspect=0.0.0.0`.
+ * Unparse these arguments using `yargs-unparser` (which would result in `--inspect 0.0.0.0`), then supply `=` where we have values.
+ * There's probably an easier or more robust way to do this; fixes welcome
+ * @param {Object} opts - Arguments object
+ * @returns {string[]} Unparsed arguments using `=` to specify values
+ * @private
+ */
+exports.unparseNodeFlags = opts => {
+  var args = unparse(opts);
+  return args.length
+    ? args
+        .join(' ')
+        .split(/\b/)
+        .map(arg => (arg === ' ' ? '=' : arg))
+        .join('')
+        .split(' ')
+    : [];
+};

package/lib/cli/one-and-dones.js

@@ -0,0 +1,69 @@
+'use strict';
+
+/**
+ * Contains "command" code for "one-and-dones"--options passed
+ * to Mocha which cause it to just dump some info and exit.
+ * See {@link module:lib/cli/one-and-dones.ONE_AND_DONE_ARGS ONE_AND_DONE_ARGS} for more info.
+ * @module
+ * @private
+ */
+
+const Mocha = require('../mocha');
+
+/**
+ * Dumps a sorted list of the enumerable, lower-case keys of some object
+ * to `STDOUT`.
+ * @param {Object} obj - Object, ostensibly having some enumerable keys
+ * @ignore
+ * @private
+ */
+const showKeys = obj => {
+  console.log();
+  const keys = Object.keys(obj);
+  const maxKeyLength = keys.reduce((max, key) => Math.max(max, key.length), 0);
+  keys
+    .filter(
+      key => /^[a-z]/.test(key) && !obj[key].browserOnly && !obj[key].abstract
+    )
+    .sort()
+    .forEach(key => {
+      const description = obj[key].description;
+      console.log(
+        `    ${key.padEnd(maxKeyLength + 1)}${
+          description ? `- ${description}` : ''
+        }`
+      );
+    });
+  console.log();
+};
+
+/**
+ * Handlers for one-and-done options
+ * @namespace
+ * @private
+ */
+exports.ONE_AND_DONES = {
+  /**
+   * Dump list of built-in interfaces
+   * @private
+   */
+  'list-interfaces': () => {
+    showKeys(Mocha.interfaces);
+  },
+  /**
+   * Dump list of built-in reporters
+   * @private
+   */
+  'list-reporters': () => {
+    showKeys(Mocha.reporters);
+  }
+};
+
+/**
+ * A Set of all one-and-done options
+ * @type Set<string>
+ * @private
+ */
+exports.ONE_AND_DONE_ARGS = new Set(
+  ['help', 'h', 'version', 'V'].concat(Object.keys(exports.ONE_AND_DONES))
+);