Global Test Framework Types

/**
 * Valid return values for test functions
 */
type ValidTestReturnValues = void | undefined;

/**
 * Promise-based test return value
 */
type TestReturnValue = ValidTestReturnValues | Promise<unknown>;

/**
 * Test execution context object
 */
type TestContext = Record<string, unknown>;

/**
 * Done callback function for async tests
 */
type DoneFn = (reason?: string | Error) => void;

/**
 * Test function that uses done callback
 */
type DoneTakingTestFn = (this: TestContext, done: DoneFn) => ValidTestReturnValues;

/**
 * Test function that returns a promise
 */
type PromiseReturningTestFn = (this: TestContext) => TestReturnValue;

/**
 * Test function that returns a generator
 */
type GeneratorReturningTestFn = (this: TestContext) => Generator<void, unknown, void>;

/**
 * Union of all test function types
 */
type TestFn = PromiseReturningTestFn | GeneratorReturningTestFn | DoneTakingTestFn;

/**
 * Concurrent test function (must return Promise)
 */
type ConcurrentTestFn = () => Promise<unknown>;

/**
 * Hook function (same as TestFn)
 */
type HookFn = TestFn;

/**
 * Name-like values that can be used as test/block names
 */
type NameLike = number | Function;

/**
 * Test name (string)
 */
type TestName = string;

/**
 * Test name or name-like value
 */
type TestNameLike = TestName | NameLike;

/**
 * Block function for describe blocks
 */
type BlockFn = () => void;

/**
 * Block name (string)
 */
type BlockName = string;

/**
 * Block name or name-like value
 */
type BlockNameLike = BlockName | NameLike;

/**
 * Column value in test data table
 */
type Col = unknown;

/**
 * Row of test data
 */
type Row = ReadonlyArray<Col>;

/**
 * Table of test data rows
 */
type Table = ReadonlyArray<Row>;

/**
 * Array-based table data
 */
type ArrayTable = Table | Row;

/**
 * Template string table
 */
type TemplateTable = TemplateStringsArray;

/**
 * Template data array
 */
type TemplateData = ReadonlyArray<unknown>;

/**
 * Either array or template table format
 */
type EachTable = ArrayTable | TemplateTable;

/**
 * Test callback function for parameterized tests
 */
type TestCallback = BlockFn | TestFn | ConcurrentTestFn;

/**
 * Each test function with parameters
 */
type EachTestFn<EachCallback extends TestCallback> = (
  ...args: ReadonlyArray<any>
) => ReturnType<EachCallback>;

interface Each<EachFn extends TestFn | BlockFn> {
  // Array of object literals table
  <T extends Record<string, unknown>>(
    table: ReadonlyArray<T>
  ): (
    name: string | NameLike,
    fn: (arg: T, done: DoneFn) => ReturnType<EachFn>,
    timeout?: number
  ) => void;

  // Array of tuples table
  <T extends readonly [unknown, ...Array<unknown>]>(
    table: ReadonlyArray<T>
  ): (
    name: string | NameLike,
    fn: (...args: [...T]) => ReturnType<EachFn>,
    timeout?: number
  ) => void;

  // Array of arrays table
  <T extends ReadonlyArray<unknown>>(
    table: ReadonlyArray<T>
  ): (
    name: string | NameLike,
    fn: (...args: T) => ReturnType<EachFn>,
    timeout?: number
  ) => void;

  // Generic array table
  <T>(
    table: ReadonlyArray<T>
  ): (
    name: string | NameLike,
    fn: (arg: T, done: DoneFn) => ReturnType<EachFn>,
    timeout?: number
  ) => void;

  // Template literal table
  <T extends Array<unknown>>(
    strings: TemplateStringsArray,
    ...expressions: T
  ): (
    name: string | NameLike,
    fn: (arg: Record<string, T[number]>, done: DoneFn) => ReturnType<EachFn>,
    timeout?: number
  ) => void;

  // Template literal with type argument
  <T extends Record<string, unknown>>(
    strings: TemplateStringsArray,
    ...expressions: Array<unknown>
  ): (
    name: string | NameLike,
    fn: (arg: T, done: DoneFn) => ReturnType<EachFn>,
    timeout?: number
  ) => void;
}

/**
 * Base hook function signature
 */
type HookBase = (fn: HookFn, timeout?: number) => void;

/**
 * Failing test interface
 */
interface Failing<T extends TestFn> {
  (testName: TestNameLike, fn: T, timeout?: number): void;
  each: Each<T>;
}

/**
 * Base it/test interface
 */
interface ItBase {
  (testName: TestNameLike, fn: TestFn, timeout?: number): void;
  each: Each<TestFn>;
  failing: Failing<TestFn>;
}

/**
 * Extended it/test interface with modifiers
 */
interface It extends ItBase {
  only: ItBase;
  skip: ItBase;
  todo: (testName: TestNameLike) => void;
}

/**
 * Base concurrent test interface
 */
interface ItConcurrentBase {
  (testName: TestNameLike, testFn: ConcurrentTestFn, timeout?: number): void;
  each: Each<ConcurrentTestFn>;
  failing: Failing<ConcurrentTestFn>;
}

/**
 * Extended concurrent test interface
 */
interface ItConcurrentExtended extends ItConcurrentBase {
  only: ItConcurrentBase;
  skip: ItConcurrentBase;
}

/**
 * Complete concurrent test interface
 */
interface ItConcurrent extends It {
  concurrent: ItConcurrentExtended;
}

/**
 * Base describe interface
 */
interface DescribeBase {
  (blockName: BlockNameLike, blockFn: BlockFn): void;
  each: Each<BlockFn>;
}

/**
 * Extended describe interface with modifiers
 */
interface Describe extends DescribeBase {
  only: DescribeBase;
  skip: DescribeBase;
}

/**
 * All Jest global test framework functions
 */
interface TestFrameworkGlobals {
  it: ItConcurrent;
  test: ItConcurrent;
  fit: ItBase & { concurrent?: ItConcurrentBase };
  xit: ItBase;
  xtest: ItBase;
  describe: Describe;
  xdescribe: DescribeBase;
  fdescribe: DescribeBase;
  beforeAll: HookBase;
  beforeEach: HookBase;
  afterEach: HookBase;
  afterAll: HookBase;
}

/**
 * Coverage map data from istanbul-lib-coverage
 */
type CoverageMapData = Record<string, any>;

/**
 * Global additions including test framework and coverage
 */
interface GlobalAdditions extends TestFrameworkGlobals {
  __coverage__: CoverageMapData;
}

/**
 * Complete global scope with Jest additions
 */
interface Global extends GlobalAdditions, Omit<typeof globalThis, keyof GlobalAdditions> {
  [extras: PropertyKey]: unknown;
}

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

// Type a custom test function
const myTest: Global.TestFn = async () => {
  // Test implementation
};

// Type a done-based test
const doneTest: Global.DoneTakingTestFn = (done) => {
  setTimeout(() => {
    done();
  }, 100);
};

// Type a hook function
const setupHook: Global.HookFn = async () => {
  // Setup logic
};

// Type parameterized test data
const testData: Global.Table = [
  [1, 2, 3],
  [4, 5, 9],
];