Circus Test Runner Types

/**
 * Node.js Process type
 */
type Process = typeof process;

/**
 * Re-exported from Global module
 */
type DoneFn = (reason?: string | Error) => void;
type BlockFn = () => void;
type BlockName = string;
type BlockNameLike = BlockName | number | Function;
type TestName = string;
type TestNameLike = TestName | number | Function;
type TestFn = ((this: Record<string, unknown>) => void | undefined | Promise<unknown>) | ((this: Record<string, unknown>) => Generator<void, unknown, void>) | ((this: Record<string, unknown>, done: DoneFn) => void | undefined);
type ConcurrentTestFn = () => Promise<unknown>;
type HookFn = TestFn;
type TestContext = Record<string, unknown>;

/**
 * Block execution modes
 */
type BlockMode = void | 'skip' | 'only' | 'todo';

/**
 * Test execution modes (same as BlockMode)
 */
type TestMode = BlockMode;

/**
 * Async function types (test or hook functions)
 */
type AsyncFn = TestFn | HookFn;

/**
 * Shared hook types (apply to all tests in suite)
 */
type SharedHookType = 'afterAll' | 'beforeAll';

/**
 * All hook types including per-test hooks
 */
type HookType = SharedHookType | 'afterEach' | 'beforeEach';

/**
 * Exception type (anything can be thrown in JavaScript)
 */
type Exception = any;

/**
 * String representation of an error
 */
type FormattedError = string;

/**
 * Test execution status
 */
type TestStatus = 'skip' | 'done' | 'todo';

/**
 * Path of test names from root to specific test
 */
type TestNamesPath = Array<TestName | BlockName>;

/**
 * Test hook representation
 */
interface Hook {
  /** Error object for async error tracking */
  asyncError: Error;
  /** Hook function to execute */
  fn: HookFn;
  /** Type of hook (beforeAll, beforeEach, etc.) */
  type: HookType;
  /** Parent describe block */
  parent: DescribeBlock;
  /** Whether done callback has been seen */
  seenDone: boolean;
  /** Hook timeout in milliseconds */
  timeout: number | undefined | null;
}

/**
 * Event handler function signature
 */
interface EventHandler {
  (event: AsyncEvent, state: State): void | Promise<void>;
  (event: SyncEvent, state: State): void;
}

/**
 * Union of all event types
 */
type Event = SyncEvent | AsyncEvent;

/**
 * Jest globals interface for Circus
 */
interface JestGlobals extends Global.TestFrameworkGlobals {
  // expect is untyped to avoid circular dependencies
  expect: unknown;
}

/**
 * Synchronous events during test definition
 */
type SyncEvent =
  | {
      asyncError: Error;
      mode: BlockMode;
      name: 'start_describe_definition';
      blockName: BlockName;
    }
  | {
      mode: BlockMode;
      name: 'finish_describe_definition';
      blockName: BlockName;
    }
  | {
      asyncError: Error;
      name: 'add_hook';
      hookType: HookType;
      fn: HookFn;
      timeout: number | undefined;
    }
  | {
      asyncError: Error;
      name: 'add_test';
      testName: TestName;
      fn: TestFn;
      mode?: TestMode;
      concurrent: boolean;
      timeout: number | undefined;
      failing: boolean;
    }
  | {
      // Unhandled error outside of test/hooks
      name: 'error';
      error: Exception;
      promise?: Promise<unknown>;
    }
  | {
      name: 'error_handled';
      promise: Promise<unknown>;
    };

/**
 * Asynchronous events during test execution
 */
type AsyncEvent =
  | {
      // First action to dispatch - good time to initialize
      name: 'setup';
      testNamePattern?: string;
      runtimeGlobals: JestGlobals;
      parentProcess: Process;
    }
  | {
      name: 'include_test_location_in_result';
    }
  | {
      name: 'hook_start';
      hook: Hook;
    }
  | {
      name: 'hook_success';
      describeBlock?: DescribeBlock;
      test?: TestEntry;
      hook: Hook;
    }
  | {
      name: 'hook_failure';
      error: string | Exception;
      describeBlock?: DescribeBlock;
      test?: TestEntry;
      hook: Hook;
    }
  | {
      name: 'test_fn_start';
      test: TestEntry;
    }
  | {
      name: 'test_fn_success';
      test: TestEntry;
    }
  | {
      name: 'test_fn_failure';
      error: Exception;
      test: TestEntry;
    }
  | {
      name: 'test_retry';
      test: TestEntry;
    }
  | {
      // The test includes all hooks + test function
      name: 'test_start';
      test: TestEntry;
    }
  | {
      name: 'test_skip';
      test: TestEntry;
    }
  | {
      name: 'test_todo';
      test: TestEntry;
    }
  | {
      name: 'test_started';
      test: TestEntry;
    }
  | {
      // Test is complete, nothing else will change its state
      name: 'test_done';
      test: TestEntry;
    }
  | {
      name: 'run_describe_start';
      describeBlock: DescribeBlock;
    }
  | {
      name: 'run_describe_finish';
      describeBlock: DescribeBlock;
    }
  | {
      name: 'run_start';
    }
  | {
      name: 'run_finish';
    }
  | {
      // Final cleanup and result preparation
      name: 'teardown';
    };

/**
 * Results from matcher execution
 */
interface MatcherResults {
  actual: unknown;
  expected: unknown;
  name: string;
  pass: boolean;
}

/**
 * Test case start information
 */
interface TestCaseStartInfo {
  ancestorTitles: Array<string>;
  fullName: string;
  mode: TestMode;
  title: string;
  startedAt?: number | null;
}

/**
 * Individual test result
 */
interface TestResult {
  duration?: number | null;
  errors: Array<FormattedError>;
  errorsDetailed: Array<MatcherResults | unknown>;
  /** Whether test.failing() was used */
  failing?: boolean;
  invocations: number;
  startedAt?: number | null;
  status: TestStatus;
  location?: { column: number; line: number } | null;
  numPassingAsserts: number;
  retryReasons: Array<FormattedError>;
  testPath: TestNamesPath;
}

/**
 * Overall test run result
 */
interface RunResult {
  unhandledErrors: Array<FormattedError>;
  testResults: TestResults;
}

/**
 * Array of test results
 */
type TestResults = Array<TestResult>;

/**
 * Global error handlers for different error types
 */
interface GlobalErrorHandlers {
  rejectionHandled: Array<(promise: Promise<unknown>) => void>;
  uncaughtException: Array<NodeJS.UncaughtExceptionListener>;
  unhandledRejection: Array<NodeJS.UnhandledRejectionListener>;
}

/**
 * Complete Circus test runner state
 */
interface State {
  /** Current describe block being processed */
  currentDescribeBlock: DescribeBlock;
  /** Currently running test (includes when hooks are executing) */
  currentlyRunningTest?: TestEntry | null;
  /** Whether to expand error messages */
  expand?: boolean;
  /** Whether there are focused tests (test.only) */
  hasFocusedTests: boolean;
  /** Whether the root describe block has started running */
  hasStarted: boolean;
  /** Original global error handlers (restored after run) */
  originalGlobalErrorHandlers?: GlobalErrorHandlers;
  /** Process object from outer scope */
  parentProcess: Process | null;
  /** Whether to randomize test order */
  randomize?: boolean;
  /** Root describe block containing all tests */
  rootDescribeBlock: DescribeBlock;
  /** Random seed for test ordering */
  seed: number;
  /** Pattern for filtering test names */
  testNamePattern?: RegExp | null;
  /** Default test timeout */
  testTimeout: number;
  /** Unhandled errors during test run */
  unhandledErrors: Array<Exception>;
  /** Whether to include test location in results */
  includeTestLocationInResult: boolean;
  /** Maximum number of concurrent tests */
  maxConcurrency: number;
  /** Map of unhandled rejection errors by promise */
  unhandledRejectionErrorByPromise: Map<Promise<unknown>, Exception>;
}

/**
 * Describe block (test suite) representation
 */
interface DescribeBlock {
  type: 'describeBlock';
  /** Child describe blocks and tests */
  children: Array<DescribeBlock | TestEntry>;
  /** Hooks attached to this describe block */
  hooks: Array<Hook>;
  /** Execution mode of this block */
  mode: BlockMode;
  /** Name of the describe block */
  name: BlockName;
  /** Parent describe block (undefined for root) */
  parent?: DescribeBlock;
  /** @deprecated Use children array instead */
  tests: Array<TestEntry>;
}

/**
 * Test error types (can be single error or error pair for async)
 */
type TestError = Exception | [Exception | undefined, Exception];

/**
 * Individual test entry representation
 */
interface TestEntry {
  type: 'test';
  /** Error for cases with no usable stack trace */
  asyncError: Exception;
  /** Test execution errors */
  errors: Array<TestError>;
  /** Errors from test retries */
  retryReasons: Array<TestError>;
  /** Test function to execute */
  fn: TestFn;
  /** Number of times test has been invoked */
  invocations: number;
  /** Test execution mode */
  mode: TestMode;
  /** Whether test runs concurrently */
  concurrent: boolean;
  /** Test name */
  name: TestName;
  /** Number of passing assertions */
  numPassingAsserts: number;
  /** Parent describe block */
  parent: DescribeBlock;
  /** Test start timestamp */
  startedAt?: number | null;
  /** Test duration in milliseconds */
  duration?: number | null;
  /** Whether done callback has been seen */
  seenDone: boolean;
  /** Test execution status */
  status?: TestStatus | null;
  /** Test timeout in milliseconds */
  timeout?: number;
  /** Whether this is a failing test (test.failing) */
  failing: boolean;
  /** Map of unhandled rejection errors by promise */
  unhandledRejectionErrorByPromise: Map<Promise<unknown>, Exception>;
}

import type { Circus } from "@jest/types";

// Custom event handler
const myEventHandler: Circus.EventHandler = (event, state) => {
  if (event.name === 'test_start') {
    console.log(`Starting test: ${event.test.name}`);
  }
};

// Check test status
const checkTestStatus = (test: Circus.TestEntry) => {
  if (test.status === 'done' && test.errors.length === 0) {
    console.log(`Test ${test.name} passed`);
  }
};

// Process test results
const processResults = (runResult: Circus.RunResult) => {
  runResult.testResults.forEach((result) => {
    console.log(`${result.testPath.join(' > ')}: ${result.status}`);
  });
};