Skip to content

armgit / mocha

Public Imported from GitHub
0

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

9.5 KB
Raw Blame
/**
 * These types are a preliminary step towards moving Mocha's TypeScript types into Mocha.
 * They are not yet complete and are not yet fully used in the codebase.
 * For now, if you're an external user, you should use the types from @types/mocha.
 */

import type { FSWatcher, MatchFunction } from "chokidar" with {
  "resolution-mode": "import",
};

import type { constants } from "./error-constants.js";
import type Mocha from "./mocha.cjs";
import { Runner } from "./runner.js";

/**
 * Command-line options
 */
export interface MochaOptions {
  /** Propagate uncaught errors? */
  allowUncaught?: boolean;

  /** Force `done` callback or promise? */
  asyncOnly?: boolean;

  /** Bail after first test failure? */
  bail?: boolean;

  /** Check for global variable leaks? */
  checkLeaks?: boolean;

  /** Color TTY output from reporter? */
  color?: boolean;

  /** Delay root suite execution? */
  delay?: boolean;

  /** Show diff on failure? */
  diff?: boolean;

  /** Report tests without running them? */
  dryRun?: boolean;

  /** Fail test run if tests were failed? */
  passOnFailingTestSuite?: boolean;

  /** Fail test run if zero tests? */
  failZero?: boolean;

  /** Test filter given string. */
  fgrep?: string;

  /** Tests marked `only` fail the suite? */
  forbidOnly?: boolean;

  /** Pending tests fail the suite? */
  forbidPending?: boolean;

  /** Full stacktrace upon failure? */
  fullTrace?: boolean;

  /** Variables expected in global scope. */
  global?: string[];

  /** Test filter given regular expression. */
  grep?: RegExp;

  /** Display inline diffs? */
  inlineDiffs?: boolean;

  /** Invert test filter matches? */
  invert?: boolean;

  /** Disable syntax highlighting? */
  noHighlighting?: boolean;

  /** Reporter name or constructor. */
  reporter?: string | Reporter;

  /** Reporter settings object. */
  reporterOption?: Object;

  /** Number of times to retry failed tests. */
  retries?: number;

  /** Slow threshold value, in milliseconds. */
  slow?: number;

  /** Timeout threshold value, in milliseconds. */
  timeout?: number | string;

  /** Interface name. */
  ui?: string;

  /** Run jobs in parallel. */
  parallel?: boolean;

  /** Max number of worker processes for parallel runs. */
  jobs?: number;

  /** Hooks to bootstrap the root suite with. */
  rootHooks?: MochaRootHookObject;

  /** Pathname of `rootHooks` plugin for parallel runs. */
  require?: string[];

  /** Should be `true` if `Mocha` process is running in a worker process. */
  isWorker?: boolean;

  watch?: boolean;
  extension?: string[];
  recursive?: boolean;
  sort?: boolean;
  file?: string[];
  spec?: string[];
  ignore?: string[];
}

/**
 * Callback to be invoked when test execution is complete.
 *
 * @private
 * @param failures - Number of failures that occurred.
 */
export type DoneCB = (failures?: number) => void;

export interface RunnerOptions {
  /** Files to run */
  files?: string[];
  /** Command-line options */
  options?: object;
}

/**
 * An alternative way to define root hooks that works with parallel runs.
 */
export interface MochaRootHookObject {
  /** "Before all" hook(s) */
  beforeAll?: Function | Function[];
  /** "Before each" hook(s) */
  beforeEach?: Function | Function[];
  /** "After all" hook(s) */
  afterAll?: Function | Function[];
  /** "After each" hook(s)} */
  afterEach?: Function | Function[];
}

/**
 * A function that's invoked _once_ which is either sync or async.
 * Can be a "teardown" or "setup".  These will all share the same context.
 */
export type MochaGlobalFixture = () => void | Promise<void>;

/**
 * An object making up all necessary parts of a plugin loader and aggregator
 */
export interface PluginDefinition {
  /**
   * Named export to use
   */
  exportName: string;
  /**
   * Option name for Mocha constructor (use `exportName` if omitted)
   */
  optionName?: string;
  /**
   * Validator function
   */
  validate?: PluginValidator;
  /**
   * Finalizer/aggregator function
   */
  finalize?: PluginFinalizer;
}

/**
 * A (sync) function to assert a user-supplied plugin implementation is valid.
 *
 * Defined in a {@link PluginDefinition}.

 * @param value Value to check
 * @this {PluginDefinition}
 */
export type PluginValidator = (this: PluginDefinition, value: unknown) => void;

/**
 * A function to finalize plugins implementations of a particular ilk
 * @param implementations User-supplied implementations
 */
export type PluginFinalizer = (
  implementations: unknown[],
) => Promise<unknown> | unknown;

/**
 * An object to configure how Mocha gathers test files
 */
export interface FileCollectionOptions {
  /** Return an empty list instead of exiting when no test files are found */
  allowEmpty?: boolean;
  /** File extensions to use */
  extension?: string[];
  /** Files, dirs, globs to run */
  spec?: string[];
  /** Files, dirs, globs to ignore */
  ignore?: string[];
  /** List of additional files to include */
  file?: string[];
  /** Find files recursively */
  recursive?: boolean;
  /** Sort test files */
  sort?: boolean;
}

/**
 * Diagnostic object containing unmatched files
 */
export interface UnmatchedFile {
  /** The absolute path to the file */
  absolutePath: string;
  /** A list of unmatched files derived from the file arguments passed in */
  pattern: string;
}

/**
 * Response object containing a list of files to test and unmatched files.
 */
export interface FileCollectionResponse {
  /** A list of files to test */
  files: string[];
  /** A list of unmatched files derived from the file arguments passed in */
  unmatchedFiles: UnmatchedFile[];
}

/**
 * @private
 */
export interface BeforeWatchRunOptions {
  mocha: Mocha;
  watcher: FSWatcher;
}

/**
 * Callback to be run before `mocha.run()` is called.
 * Optionally, it can return a new `Mocha` instance.
 * @private
 */
export type BeforeWatchRun = (options: BeforeWatchRunOptions) => Mocha;

/**
 * Object containing run control methods
 * @private
 */
export interface Rerunner {
  /** Calls `mocha.run()` */
  run: Function;
  /** Schedules another call to `run */
  scheduleRun: Function;
}

/**
 * Object containing paths (without globs) and glob paths for matching.
 * @private
 */
export interface PathPattern {
  /** Set of absolute paths without globs. */
  paths: Set<string>;
  /** Set of absolute glob paths. */
  globs: Set<string>;
}

/**
 * Object containing path patterns for filtering from the provided glob paths.
 * @private
 */
export interface PathFilter {
  /** Path patterns for directories. */
  dir: PathPattern;
  /** Path patterns for matching. */
  match: PathPattern;
}

/**
 * Checks if the file path matches the allowed patterns.
 * @private
 * @param filePath The file path to check.
 * @returns Determines if there was a match.
 */
export type AllowMatchFunction = (filePath: string) => boolean;

/**
 * Object for matching paths to either allow or ignore them.
 * @private
 */
export interface PathMatcher {
  /** Checks if the file path matches the allowed patterns. */
  allow: AllowMatchFunction;
  /** The Chokidar `ignored` match function. */
  ignore: MatchFunction;
}

export interface StatsCollector {
  /** integer count of suites run */
  suites: number;

  /** integer count of tests run */
  tests: number;

  /** integer count of passing tests */
  passes: number;

  /** integer count of pending tests */
  pending: number;

  /** integer count of failed tests */
  failures: number;

  /** time when testing began */
  start: Date;

  /** time when testing concluded */
  end: Date;

  /** number of msecs that testing took */
  duration: number;
}

export interface PluginLoaderOptions {
  /**
   * Plugin definitions
   */
  pluginDefs?: PluginDefinition;

  /**
   * A list of plugins to ignore when loading
   */
  ignore?: string[];
}

/**
 * @memberof module:lib/errors
 */
export interface MochaTimeoutError extends Error {
  code: typeof constants.TIMEOUT;

  /**
   * Timeout in ms
   */
  timeout?: number;

  /**
   * Filepath, if given
   */
  file?: string;
}

/**
 * The result of calling `SerializableEvent.serialize`, as received
 * by the deserializer.
 * @private
 */
export interface SerializedEvent {
  /** Optional serialized data */
  data?: object;

  /** Optional serialized `Error` */
  error?: Error;
}

/**
 * The result of calling `SerializableWorkerResult.serialize` as received
 * by the deserializer.
 * @private
 */
export interface SerializedWorkerResult {
  /** Number of failures */
  failureCount: number;

  /** Serialized events */
  events: SerializedEvent[];

  /** Symbol-like to denote the type of object this is */
  __type: "SerializedWorkerResult";
}

/**
 * Listener function intended to be bound to `Process.SIGINT` event
 * @private
 */
export type SigIntListener = () => Promise<void>;

/**
 * A function accepting a test file path and returning the results of a test run
 * @private
 * @param filename - File to run
 */
export type FileRunner = (filename: string) => Promise<SerializedWorkerResult>;

/**
 * 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.
 */
export interface BufferedEvent {
  /** Event name */
  name: string;

  /** Event parameters */
  data: object;
}

/**
 * An object with all stack traces recursively mounted from each err.cause
 * @memberof module:lib/reporters/base
 */
export interface FullErrorStack {
  message: string;
  msg: string;
  stack: string;
}

export interface Reporter {
  new (runner: Runner, options: MochaOptions): Reporter;
  done?: (failures: number, callback: () => void) => void;
}