Skip to content

armgit / mocha

Public Imported from GitHub
0

☕️ Classic, reliable, trusted test framework for Node.js and the browser

29.0 KB
Raw Blame
"use strict";

const os = require("node:os");
const fs = require("node:fs");
const fsP = require("node:fs/promises");
const { format } = require("node:util");
const path = require("node:path");
const { Base } = require("../../lib/reporters/base.js");
const { escapeRegExp } = require("../../lib/utils/regexp.js");
const debug = require("debug")("mocha:test:integration:helpers");
const SIGNAL_OFFSET = 128;
const { DEFAULT_WATCH_BUDGET_MS } = require("./constants.js");

/**
 * Path to `mocha` executable
 */
const MOCHA_EXECUTABLE = require.resolve("../../bin/mocha.js");

/**
 * regular expression used for splitting lines based on new line / dot symbol.
 */
const SPLIT_DOT_REPORTER_REGEXP = new RegExp("[\\n" + Base.symbols.dot + "]+");

/**
 * Name of "default" fixture file.
 */
const DEFAULT_FIXTURE = "__default__.fixture.js";

/**
 * Path to "default" fixture file
 */
const DEFAULT_FIXTURE_PATH = resolveFixturePath(DEFAULT_FIXTURE);

/**
 * Invokes the mocha binary for the given fixture with color output disabled.
 * Accepts an array of additional command line args to pass. The callback is
 * invoked with a summary of the run, in addition to its output. The summary
 * includes the number of passing, pending, and failing tests, as well as the
 * exit code. Useful for testing different reporters.
 *
 * By default, `STDERR` is ignored. Pass `{stdio: 'pipe'}` as `opts` if you
 * want it.
 * Example response:
 * {
 *   pending: 0,
 *   passing: 0,
 *   failing: 1,
 *   code:    1,
 *   output:  '...'
 * }
 *
 * @param {string} fixturePath - Path to fixture .js file
 * @param {string[]|SummarizedResultCallback} args - Extra args to mocha executable
 * @param {SummarizedResultCallback|Object} done - Callback
 * @param {Object} [opts] - Options for `spawn()`
 * @returns {ChildProcess} Subprocess process
 */
function runMocha(fixturePath, args, done, opts = {}) {
  if (typeof args === "function") {
    opts = done;
    done = args;
    args = [];
  }

  return invokeMocha(
    [...args, resolveFixturePath(fixturePath)],
    (err, res) => {
      if (err) {
        return done(err);
      }

      done(null, getSummary(res));
    },
    opts,
  );
}

/**
 * Invokes the mocha executable for the given fixture using the `json` reporter,
 * calling callback `done` with parsed output.
 *
 * Use when you expect `mocha` _not_ to fail (test failures OK); the output from
 * the `json` reporter--and thus the entire subprocess--must be valid JSON!
 *
 * By default, `STDERR` is ignored. Pass `{stdio: 'pipe'}` as `opts` if you
 * want it.
 * @param {string} fixturePath - Path from `__dirname__`
 * @param {string[]|JSONResultCallback} args - Args to `mocha` or callback
 * @param {JSONResultCallback|Object} done - Callback or options
 * @param {Object} [opts] - Opts for `spawn()`
 * @returns {ChildProcess} Subprocess instance
 */
function runMochaJSON(fixturePath, args, done, opts) {
  if (typeof args === "function") {
    opts = done;
    done = args;
    args = [];
  }

  return invokeMocha(
    [...args, "--reporter", "json", resolveFixturePath(fixturePath)],
    (err, res) => {
      if (err) {
        return done(err);
      }

      let result;
      try {
        result = toJSONResult(res);
      } catch (err) {
        return done(
          new Error(
            format(
              "Failed to parse JSON reporter output. Error:\n%O\nResult:\n%O",
              err,
              res,
            ),
          ),
        );
      }
      done(null, result);
    },
    opts,
  );
}

/**
 *
 * If you need more granular control, try {@link invokeMochaAsync} instead.
 *
 * Like {@link runMocha}, but returns a `Promise`.
 * @param {string} fixturePath - Path to (or name of, or basename of) fixture file
 * @param {Options} [args] - Command-line arguments to the `mocha` executable
 * @param {Object} [opts] - Options for `child_process.spawn`.
 * @returns {Promise<Summary>}
 */
function runMochaAsync(fixturePath, args, opts) {
  return new Promise((resolve, reject) => {
    runMocha(
      fixturePath,
      args,
      (err, result) => {
        if (err) {
          return reject(err);
        }
        resolve(result);
      },
      opts,
    );
  });
}

/**
 * Like {@link runMochaJSON}, but returns a `Promise`.
 * @param {string} fixturePath - Path to (or name of, or basename of) fixture file
 * @param {Options} [args] - Command-line args
 * @param {Object} [opts] - Options for `child_process.spawn`
 * @returns {Promise<JSONResult>}
 */
function runMochaJSONAsync(fixturePath, args = [], opts = {}) {
  return new Promise((resolve, reject) => {
    runMochaJSON(
      fixturePath,
      args,
      (err, result) => {
        if (err) {
          return reject(err);
        }
        resolve(result);
      },
      opts,
    );
  });
}

/**
 * Coerce output as returned by _spawnMochaWithListeners using JSON reporter into a JSONResult as
 * recognized by our custom unexpected assertions
 * @param {RawResult} result - Raw stdout from Mocha run using JSON reporter
 * @returns {JSONResult}
 */
function toJSONResult(result) {
  try {
    return { ...JSON.parse(result.output), ...result };
  } catch (err) {
    throw new Error(
      `Couldn't parse JSON: ${err.message}\n\nOriginal result output: ${result.output}`,
      { cause: err },
    );
  }
}

/**
 * Creates arguments loading a default fixture if none provided
 *
 * - The `--no-color` arg is always used (color output complicates testing `STDOUT`)
 * - Unless `--bail` or `--no-bail` is set, use `--no-bail`.  This enables using
 *   `--bail` (if desired) from the command-line when running our integration
 *   test suites without stepping on the toes of subprocesses.
 * - Unless `--parallel` or `--no-parallel` is set, use `--no-parallel`.  We
 *   assume the test suite is _already_ running in parallel--and there's no point
 *   in trying to run a single test fixture in parallel.
 * - The {@link DEFAULT_FIXTURE} file is used if no arguments are provided.
 *
 * @param {string[]|*} [args] - Arguments to `spawn`
 * @returns {string[]}
 */
function defaultArgs(args = [DEFAULT_FIXTURE_PATH]) {
  const newArgs = [
    ...(!args.length ? [DEFAULT_FIXTURE_PATH] : args),
    "--no-color",
  ];
  if (!newArgs.some((arg) => /--(no-)?bail/.test(arg))) {
    newArgs.push("--no-bail");
  }
  if (!newArgs.some((arg) => /--(no-)?parallel/.test(arg))) {
    newArgs.push("--no-parallel");
  }
  return newArgs;
}

/**
 * Invoke `mocha` with default arguments. Calls `done` upon exit. Does _not_ accept a fixture path.
 *
 * Good for testing error conditions. This is low-level, and you likely want
 * {@link runMocha} or even {@link runMochaJSON} if you are running test fixtures.
 *
 * @param {string[]|RawResultCallback} args - Args to `mocha` or callback
 * @param {RawResultCallback|Object} done - Callback or options
 * @param {Object} [opts] - Options
 * @returns {ChildProcess}
 */
function invokeMocha(args, done, opts = {}) {
  if (typeof args === "function") {
    opts = done;
    done = args;
    args = [];
  }
  return createSubprocess(
    defaultArgs([MOCHA_EXECUTABLE].concat(args)),
    done,
    opts,
  );
}

/**
 * Invokes the mocha binary with the given arguments. Returns the
 * child process and a promise for the results of running the
 * command. The promise resolves when the child process exits. The
 * result includes the **raw** string output, as well as exit code.
 *
 * By default, `STDERR` is ignored. Pass `{stdio: 'pipe'}` as `opts` if you
 * want it as part of the result output.
 *
 * @param {string[]} args - Array of args
 * @param {Object} [opts] - Opts for `spawn()`
 * @returns {[import('child_process').ChildProcess,Promise<RawResult>]} A tuple of process and result promise
 */
function invokeMochaAsync(args, opts = {}) {
  let mochaProcess;
  const resultPromise = new Promise((resolve, reject) => {
    mochaProcess = createSubprocess(
      defaultArgs([MOCHA_EXECUTABLE].concat(args)),
      (err, result) => {
        if (err) {
          reject(err);
        } else {
          resolve(result);
        }
      },
      opts,
    );
  });
  return [mochaProcess, resultPromise];
}

/**
 * Invokes subprocess with currently-running `node`.
 *
 * Useful for running certain fixtures as scripts.
 *
 * @param {string[]|RawResultCallback} args - Args to `mocha` or callback
 * @param {RawResultCallback|Object} done - Callback or options
 * @param {Object} [opts] - Options
 * @returns {ChildProcess}
 */
function invokeNode(args, done, opts = {}) {
  if (typeof args === "function") {
    opts = done;
    done = args;
    args = [];
  }
  return createSubprocess(args, done, opts);
}

/**
 * Creates a subprocess and calls callback `done` when it has exited.
 *
 * This is the most low-level function and should _not_ be exported.
 *
 * @param {string[]} args - Path to executable and arguments
 * @param {RawResultCallback} done - Callback
 * @param {Object|string} [opts] - Options to `child_process` or 'pipe' for shortcut to `{stdio: pipe}`
 * @param {boolean} [opts.fork] - If `true`, use `child_process.fork` instead
 * @param {boolean} [opts.separateStderr] - If `true`, accumulate piped `STDERR` into the result's `stderr` field instead of merging it into `output`
 * @returns {import('child_process').ChildProcess}
 */
function createSubprocess(args, done, opts = {}) {
  let output = "";
  let stderrOutput = "";

  if (opts === "pipe") {
    opts = { stdio: ["inherit", "pipe", "pipe"] };
  }

  const env = { ...process.env };
  // prevent DEBUG from borking STDERR when piping, unless explicitly set via `opts`
  delete env.DEBUG;

  opts = {
    cwd: process.cwd(),
    stdio: ["inherit", "pipe", "inherit"],
    env,
    ...opts,
  };

  /**
   * @type {import('child_process').ChildProcess}
   */
  let mocha;
  if (opts.fork) {
    const { fork } = require("node:child_process");
    // to use ipc, we need a fourth item in `stdio` array.
    // opts.stdio is usually an array of length 3, but it could be smaller
    // (pad with `null`)
    for (let i = opts.stdio.length; i < 4; i++) {
      opts.stdio.push(i === 3 ? "ipc" : null);
    }
    debug("forking: %s", args.join(" "));
    mocha = fork(args[0], args.slice(1), opts);
  } else {
    const { spawn } = require("node:child_process");
    debug("spawning: %s", [process.execPath].concat(args).join(" "));
    mocha = spawn(process.execPath, args, opts);
  }

  const listener = (data) => {
    output += data;
  };

  mocha.stdout.on("data", listener);
  if (mocha.stderr) {
    if (opts.separateStderr) {
      mocha.stderr.on("data", (data) => {
        stderrOutput += data;
      });
    } else {
      mocha.stderr.on("data", listener);
    }
  }
  mocha.on("error", done);

  mocha.on("close", (code) => {
    done(null, {
      output,
      stderr: stderrOutput,
      code,
      args,
      command: args.join(" "),
    });
  });

  /**
   * Emulate node's exit code for fatal signal. Allows tests to see the same
   * exit code as the mocha cli.
   */
  mocha.on("exit", (code, signal) => {
    if (signal) {
      mocha.exitCode =
        SIGNAL_OFFSET +
        (typeof signal == "string" ? os.constants.signals[signal] : signal);
    }
  });

  return mocha;
}

/**
 * Given an exact fixture reference (a relative path from `${__dirname}/fixtures`,
 * including its extension) or an absolute path, resolve a fixture filepath.
 *
 * Fixture references must be exact. Passing a bare name such as my-file and
 * relying on my-file.fixture.js being found is no longer supported, pass the
 * full file name (for example: my-file.fixture.js) instead.
 *
 * @param {string} fixture - Exact fixture reference
 * @returns {string} Resolved filepath
 */
function resolveFixturePath(fixture) {
  if (path.isAbsolute(fixture)) {
    return fixture;
  }

  if (!path.extname(fixture)) {
    throw new Error(
      `Fixture "${fixture}" must be referenced by its exact file name, ` +
        `e.g. "${fixture}.fixture.js".`,
    );
  }

  return path.resolve(__dirname, "fixtures", fixture);
}

/**
 * Parses some `mocha` reporter output and returns a summary based on the "epilogue"
 * @param {string} res - Typically output of STDOUT from the 'spec' reporter
 * @returns {Summary}
 */
function getSummary(res) {
  return ["passing", "pending", "failing"].reduce((summary, type) => {
    const pattern = new RegExp(`  (\\d+) ${type}\\s`);
    const match = pattern.exec(res.output);
    summary[type] = match ? parseInt(match, 10) : 0;

    return summary;
  }, res);
}

/**
 * Marker printed to `STDERR` by mocha's watch mode (`lib/cli/watch-run.js`)
 * after every completed test run which did not already have a rerun
 * scheduled, including the very first run.
 */
const WATCH_RUN_MARKER = "[mocha] waiting for changes";

/**
 * ANSI sequence that shows the terminal cursor. Watch mode
 * hides the cursor and only restores it on a clean exit. When a
 * watch test fails we dump the killed child's `STDOUT`, which still contains
 * the "hide cursor" sequence with no matching "show cursor", appending this
 * keeps the developer's cursor from staying hidden.
 */
const SHOW_CURSOR_ANSI = "\u001b[?25h";

/**
 * Time to wait for an erroneous rerun to begin after run finishes
 */
const WATCH_NO_RERUN_GRACE_MS = 2000;

/**
 * How long to wait for the watch child to exit after `SIGINT` before
 * escalating to `SIGKILL`.
 */
const WATCH_EXIT_TIMEOUT_MS = 10000;

/**
 * How long to wait for the `close` event after `SIGKILL` is sent.  SIGKILL is
 * unignorable, so the OS delivers it almost instantly; this is just a safety
 * cap so {@link shutdownWatchChild} has a finite deadline.
 */
const WATCH_KILL_GRACE_MS = 2000;

/**
 * Parses the output of a `mocha --watch --reporter json` child into one
 * object per **completed** test run, ignoring a trailing segment which has
 * not fully arrived yet.
 *
 * @param {string} output - Raw `STDOUT` of the watch child
 * @returns {object[]} One parsed JSON result per completed run
 */
function parseWatchJSONOutput(output) {
  return getJsonSegments(output)
    .map((segment) => {
      try {
        return JSON.parse(segment);
      } catch {
        // an incomplete segment still crossing the pipe
        return null;
      }
    })
    .filter((parsed) => parsed !== null);
}

/**
 * Returns non-empty segments from the watch child's `STDOUT` that cannot be
 * parsed as JSON. A non-empty unparseable segment means a run started but its
 * output was truncated (e.g. the child was killed mid-flush).
 *
 * @param {string} output - Raw `STDOUT` of the watch child
 * @returns {string[]} Segments that failed JSON.parse
 */
function getUnparsedSegments(output) {
  return getJsonSegments(output).filter((segment) => {
    try {
      JSON.parse(segment);
      return false;
    } catch {
      return true;
    }
  });
}

/**
 * Returns the split JSON for each run in the `output` session.
 * @param {string} output stdout from a `mocha --watch --reporter json` session
 * @returns {string[]} truthy strings, test run CLI output.
 */
function getJsonSegments(output) {
  /** Pattern for CLI output hiding or showing the cursor */
  // eslint-disable-next-line no-control-regex
  const hideOrShowCursorRegex = /\u001b\[\?25./g;
  /** CLI output for erasing the current line */
  const lineErasureCliOutput = "\u001b[2K";
  return output
    .replace(hideOrShowCursorRegex, "")
    .split(lineErasureCliOutput)
    .filter(Boolean);
}

/**
 * Observes a `mocha --watch` child's output, letting callers wait until a
 * given number of test runs have verifiably completed.
 *
 * Two detectors are available:
 * - `json` counts fully parseable `--reporter json` payloads on `STDOUT`. A
 *   successful parse proves the run completed AND its output completely
 *   crossed the pipe, making it safe to `SIGINT` the child afterwards
 *   (killing the child can discard output it has not flushed yet).
 * - `marker` counts watch mode's "waiting for changes" `STDERR` messages,
 *   for tests using reporters other than `json`.
 *
 * @param {import('child_process').ChildProcess} mochaProcess - Watch child with piped stdio
 * @param {Object} opts - Options
 * @param {'json'|'marker'} opts.runDetector - How to count completed runs
 * @param {number} opts.budgetMs - Shared deadline for all waits of one helper call
 */
function createWatchRunObserver(mochaProcess, { runDetector, budgetMs }) {
  const deadlineAt = Date.now() + budgetMs;
  let stdout = "";
  let stderr = "";
  const waiters = new Set();

  const runCount = () =>
    runDetector === "json"
      ? // wait for JSON payload to flush for future assertions
        parseWatchJSONOutput(stdout).length
      : stderr.split(WATCH_RUN_MARKER).length - 1;

  const evaluate = () => {
    for (const waiter of waiters) {
      if (waiter.isSatisfied()) {
        waiters.delete(waiter);
        clearTimeout(waiter.timer);
        waiter.resolve();
      }
    }
  };

  mochaProcess.stdout.on("data", (chunk) => {
    stdout += chunk;
    evaluate();
  });
  mochaProcess.stderr.on("data", (chunk) => {
    stderr += chunk;
    evaluate();
  });

  const waitFor = (isSatisfied, description) => {
    if (isSatisfied()) {
      return Promise.resolve();
    }
    return new Promise((resolve, reject) => {
      const waiter = { isSatisfied, resolve };
      waiter.timer = setTimeout(
        () => {
          waiters.delete(waiter);
          reject(
            new Error(
              `runMochaWatchAsync: timed out waiting for ${description}; ` +
                `${runCount()} run(s) completed so far\n` +
                `=== watch child STDOUT ===\n${stdout}\n` +
                `=== watch child STDERR ===\n${stderr}` +
                SHOW_CURSOR_ANSI,
            ),
          );
        },
        Math.max(deadlineAt - Date.now(), 1),
      );
      waiters.add(waiter);
    });
  };

  return {
    runCount,
    waitForRuns: (n) =>
      waitFor(() => runCount() >= n, `${n} run(s) to complete`),
    waitForStderr: (pattern, description) =>
      waitFor(() => pattern.test(stderr), description),
  };
}

/**
 * Shuts a watch child down with `SIGINT` (sent as an IPC message when the
 * child was forked, as on Windows), escalating to `SIGKILL` if it has not
 * exited within {@link WATCH_EXIT_TIMEOUT_MS}, then waits for the `close`
 * event with a {@link WATCH_KILL_GRACE_MS} grace period so the total deadline
 * is always finite.
 *
 * @param {import('child_process').ChildProcess} mochaProcess - Watch child
 * @param {Promise<void>} closed - Resolves once the child has closed
 */
async function shutdownWatchChild(mochaProcess, closed) {
  if (mochaProcess.exitCode === null && mochaProcess.signalCode === null) {
    try {
      if (mochaProcess.connected) {
        mochaProcess.send("SIGINT");
      } else {
        mochaProcess.kill("SIGINT");
      }
    } catch {
      // the child exited in between; the bounded wait below settles it
    }
  }
  const killTimer = setTimeout(() => {
    try {
      mochaProcess.kill("SIGKILL");
    } catch {
      // already gone
    }
  }, WATCH_EXIT_TIMEOUT_MS);
  await Promise.race([
    closed,
    sleep(WATCH_EXIT_TIMEOUT_MS + WATCH_KILL_GRACE_MS),
  ]);
  clearTimeout(killTimer);
}

/**
 * Runs the mocha executable in watch mode, calls `change`, returns the raw result.
 *
 * The function starts mocha with the given arguments and `--watch`, waits
 * until the first test run has verifiably completed (which also proves the
 * file watcher is ready), calls `change`, and waits until
 * `opts.expectedRuns` runs have completed in total. Mocha is then killed
 * and the result is returned.
 *
 * On Windows, this will call `child_process.fork()` instead of `spawn()`.
 *
 * **Exit code will always be 0**
 * @param {string[]} args - Array of argument strings
 * @param {object|string} opts - If a `string`, then `cwd`, otherwise options for `child_process` plus the watch options below
 * @param {number} [opts.expectedRuns] - Total completed runs (including the first) to wait for before killing mocha; defaults to `2`
 * @param {boolean} [opts.noRerun] - If `true`, expect NO rerun: observe a bounded grace period after `change` instead of waiting for a second run
 * @param {RegExp} [opts.firstRunCrashPattern] - If set, expect the first run to fail to load, printing only an error stack (no stdout) with a message matching this pattern. No countable run output to wait for.
 * @param {'json'|'marker'} [opts.runDetector] - How completed runs are counted; `runMochaWatchJSONAsync` sets `json`
 * @param {number} [opts.budgetMs] - Shared deadline for everything this call waits on; must stay below the test's timeout
 * @param {Function} change - A potentially `Promise`-returning callback which changes a watched file; receives the child process and `{waitForRuns, runCount}` (`runCount()` reports completed runs observed so far)
 * @returns {Promise<RawResult>}
 */
async function runMochaWatchAsync(args, opts, change) {
  if (typeof opts === "string") {
    opts = { cwd: opts };
  }
  const {
    expectedRuns = 2,
    noRerun = false,
    firstRunCrashPattern = null,
    runDetector = "marker",
    budgetMs = DEFAULT_WATCH_BUDGET_MS,
    ...spawnOpts
  } = opts;
  if (noRerun && opts.expectedRuns !== undefined) {
    throw new Error(
      "runMochaWatchAsync: `noRerun` and `expectedRuns` are mutually exclusive",
    );
  }
  opts = {
    stdio: ["pipe", "pipe", "pipe"],
    separateStderr: true,
    ...spawnOpts,
    fork: process.platform === "win32",
  };
  const [mochaProcess, resultPromise] = invokeMochaAsync(
    [...args, "--watch"],
    opts,
  );
  // avoid an unhandled rejection when a wait below throws first
  resultPromise.catch(() => {});
  const closed = new Promise((resolve) => {
    mochaProcess.once("close", resolve);
  });
  const observer = createWatchRunObserver(mochaProcess, {
    runDetector,
    budgetMs,
  });

  try {
    // The first watch run only starts inside chokidar's `ready` handler, and
    // file events from before then are ignored (`ignoreInitial` in
    // lib/cli/watch-run.js) -- so a completed first run proves the watcher
    // is armed and `change` cannot be lost. If watch mode ever starts the
    // first run before the watcher is ready (e.g. mochajs/mocha#5409), this
    // gate needs an explicit watcher-ready signal instead.
    if (firstRunCrashPattern) {
      await observer.waitForStderr(
        firstRunCrashPattern,
        "the first (crashing) watch run to print its error",
      );
    } else {
      await observer.waitForRuns(1);
    }

    await change(mochaProcess, {
      waitForRuns: observer.waitForRuns,
      runCount: observer.runCount,
    });

    if (noRerun) {
      // Give an erroneous rerun time to show up
      await sleep(WATCH_NO_RERUN_GRACE_MS);
    } else {
      await observer.waitForRuns(expectedRuns);
    }
  } finally {
    await shutdownWatchChild(mochaProcess, closed);
  }

  const res = await resultPromise;

  if (noRerun && runDetector === "json" && !firstRunCrashPattern) {
    const unparsed = getUnparsedSegments(res.output);
    if (unparsed.length > 0) {
      throw new Error(
        `noRerun: ${unparsed.length} non-empty unparseable JSON segment(s) found ` +
          `after the grace period — an erroneous rerun was killed mid-flush\n` +
          `=== watch child STDOUT ===\n${res.output}` +
          SHOW_CURSOR_ANSI,
      );
    }
  }

  // we kill the process with `SIGINT`, so it will always appear as "failed" to our
  // custom assertions (a non-zero exit code 130). just change it to 0.
  res.code = 0;
  return res;
}

/**
 * Runs the mocha executable in watch mode, calls `change` and returns the
 * JSON result of every completed test run.
 *
 * See {@link runMochaWatchAsync} for the synchronization behavior and
 * options; completed runs are counted by parsing the json reporter's
 * output.
 *
 * **Exit code will always be 0**
 * @param {string[]} args - Array of argument strings
 * @param {object|string} opts - If a `string`, then `cwd`, otherwise options for {@link runMochaWatchAsync}
 * @param {Function} change - A potentially `Promise`-returning callback to execute which will change a watched file
 * @returns {Promise<JSONResult>}
 */
async function runMochaWatchJSONAsync(args, opts, change) {
  if (typeof opts === "string") {
    opts = { cwd: opts };
  }
  const res = await runMochaWatchAsync(
    [...args, "--reporter", "json"],
    { runDetector: "json", ...opts },
    change,
  );
  return parseWatchJSONOutput(res.output);
}

let lastTouchedTime = Date.now();

/**
 * Synchronously touch a file, creating it and all its parent directories
 * if necessary.
 * One call is one change as far as a file watcher is concerned.
 *
 * An existing file gets a fresh, significantly-increasing mtime
 * since repeatedly setting an identical mtime is invisible to polling watchers.
 * The timestamp increases significantly so watchers don't coalesce changes.
 * A new file is only created: its timestamp is irrelevant.
 *
 * @param {string} filepath - Path to file
 */
function touchFile(filepath) {
  fs.mkdirSync(path.dirname(filepath), { recursive: true });
  lastTouchedTime = Math.max(lastTouchedTime + 1000, Date.now());
  const touchTime = new Date(lastTouchedTime);
  try {
    fs.utimesSync(filepath, touchTime, touchTime);
  } catch (err) {
    if (err.code !== "ENOENT") {
      throw err;
    }
    const fd = fs.openSync(filepath, "a");
    fs.closeSync(fd);
  }
}

/**
 * Synchronously replace all substrings matched by `pattern` with
 * `replacement` in the contents of file at `filepath`
 *
 * @param {string} filepath - Path to file
 * @param {RegExp|string} pattern - Search pattern
 * @param {string} replacement - Replacement
 */
function replaceFileContents(filepath, pattern, replacement) {
  const contents = fs.readFileSync(filepath, "utf-8");
  const newContents = contents.replace(pattern, replacement);
  fs.writeFileSync(filepath, newContents, "utf-8");
  touchFile(filepath);
}

/**
 * Synchronously copy a fixture to the given destination file path.
 * Creates parent directories of the destination path if necessary.
 *
 * @param {string} fixtureName - Relative path from __dirname to fixture, or absolute path
 * @param {*} dest - Destination directory
 */
function copyFixture(fixtureName, dest) {
  const fixtureSource = resolveFixturePath(fixtureName);
  fs.mkdirSync(path.dirname(dest), { recursive: true });
  fs.cpSync(fixtureSource, dest);
}

/**
 * Creates a temporary directory
 * @returns {Promise<CreateTempDirResult>} Temp dir path and cleanup function
 */
const createTempDir = async () => {
  const dirpath = await fsP.mkdtemp(path.join(os.tmpdir(), "mocha-"));
  return {
    dirpath,
    removeTempDir: async () => {
      if (!process.env.MOCHA_TEST_KEEP_TEMP_DIRS) {
        return fs.rmSync(dirpath, { recursive: true, force: true });
      }
    },
  };
};

/**
 * Waits for `time` ms.
 * @param {number} time - Time in ms
 * @returns {Promise<void>}
 */
function sleep(time) {
  return new Promise((resolve) => {
    setTimeout(resolve, time);
  });
}

module.exports = {
  DEFAULT_FIXTURE,
  SPLIT_DOT_REPORTER_REGEXP,
  copyFixture,

  createTempDir,
  escapeRegExp,
  getSummary,
  invokeMocha,
  invokeMochaAsync,
  invokeNode,
  replaceFileContents,
  resolveFixturePath,
  runMocha,
  runMochaAsync,
  runMochaJSON,
  runMochaJSONAsync,
  runMochaWatchAsync,
  runMochaWatchJSONAsync,
  sleep,
  toJSONResult,
  touchFile,
};

/**
 * A summary of a `mocha` run
 * @typedef {Object} Summary
 * @property {number} passing - Number of passing tests
 * @property {number} pending - Number of pending tests
 * @property {number} failing - Number of failing tests
 */

/**
 * An unprocessed result from a `mocha` run
 * @typedef {Object} RawResult
 * @property {string} output - Process output; _usually_ just stdout
 * @property {number?} code - Exit code or `null` in some circumstances
 * @property {string[]} args - Array of program arguments
 * @property {string} command - Complete command executed
 * @property {string} stderr - Process stderr output
 */

/**
 * The result of a `mocha` run using `json` reporter
 * @typedef {Object} JSONResult
 * @property {Object} stats - Statistics
 * @property {Object[]} failures - Failure information
 * @property {number?} code - Exit code or `null` in some circumstances
 * @property {string} command - Complete command executed
 */

/**
 * The result of a `mocha` run using `spec` reporter (parsed)
 * @typedef {Summary} SummarizedResult
 * @property {string} output - Process output; _usually_ just stdout
 * @property {number?} code - Exit code or `null` in some circumstances
 */

/**
 * Callback function run when `mocha` process execution complete
 * @callback RawResultCallback
 * @param {Error?} err - Error, if any
 * @param {RawResult} result - Result of `mocha` run
 * @returns {void}
 */

/**
 * Callback function run when `mocha` process execution complete
 * @callback JSONResultCallback
 * @param {Error?} err - Error, if any
 * @param {JSONResult} result - Result of `mocha` run
 * @returns {void}
 */

/**
 * Callback function run when `mocha` process execution complete
 * @callback SummarizedResultCallback
 * @param {Error?} err - Error, if any
 * @param {SummarizedResult} result - Result of `mocha` run
 * @returns {void}
 */

/**
 * Return value when calling {@link createTempDir}
 *
 * @typedef {Object} CreateTempDirResult
 * @property {string} dirname - Path of new temp dir
 * @property {RemoveTempDirCallback} removeTempDir - "Cleanup" function to remove temp dir
 */

/**
 * Cleanup function to remove temp dir
 * @callback RemoveTempDirCallback
 * @returns {void}
 */