Test Framework Globals

/**
 * Creates a test suite grouping related tests
 * @param blockName - Name or description of the test suite
 * @param blockFn - Function containing test definitions
 */
function describe(blockName: BlockNameLike, blockFn: BlockFn): void;

interface DescribeMethods {
  /** Run only this describe block */
  only(blockName: BlockNameLike, blockFn: BlockFn): void;
  /** Skip this entire describe block */
  skip(blockName: BlockNameLike, blockFn: BlockFn): void;
  /** Run parameterized describe blocks with different inputs */
  each<T extends readonly any[]>(
    table: ReadonlyArray<T>
  ): (name: string, fn: (...args: T) => void) => void;
}

import { describe } from "jest-circus";

describe("Math operations", () => {
  // Tests go here
});

// Focus on specific suite
describe.only("Critical tests", () => {
  // Only this suite will run
});

// Skip entire suite
describe.skip("Broken tests", () => {
  // This suite will be skipped
});

// Parameterized describe blocks
describe.each([
  [1, 2, 3],
  [4, 5, 9],
])("Calculator with %i + %i", (a, b, expected) => {
  test(`equals ${expected}`, () => {
    expect(a + b).toBe(expected);
  });
});

/**
 * Define a test case (alias for test)
 * @param testName - Name or description of the test
 * @param fn - Test function
 * @param timeout - Optional timeout in milliseconds
 */
function it(testName: TestNameLike, fn: TestFn, timeout?: number): void;

/**
 * Define a test case
 * @param testName - Name or description of the test  
 * @param fn - Test function
 * @param timeout - Optional timeout in milliseconds
 */
function test(testName: TestNameLike, fn: TestFn, timeout?: number): void;

interface TestMethods {
  /** Run only this test */
  only(testName: TestNameLike, fn: TestFn, timeout?: number): void;
  /** Skip this test */
  skip(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
  /** Mark test as TODO (not implemented) */
  todo(testName: TestNameLike, ...rest: Array<any>): void;
  /** Test expected to fail */
  failing(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
  /** Run parameterized tests with different inputs */
  each<T extends readonly any[]>(
    table: ReadonlyArray<T>
  ): (name: string, fn: (...args: T) => void, timeout?: number) => void;
  /** Run test concurrently */
  concurrent: ConcurrentTestFunction;
}

interface ConcurrentTestFunction {
  (testName: TestNameLike, fn: TestFn, timeout?: number): void;
  only(testName: TestNameLike, fn: TestFn, timeout?: number): void;  
  skip(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
  failing(testName: TestNameLike, fn?: TestFn, timeout?: number): void;
  each<T extends readonly any[]>(
    table: ReadonlyArray<T>
  ): (name: string, fn: (...args: T) => void, timeout?: number) => void;
}

import { it, test } from "jest-circus";

// Basic test
test("should add numbers", () => {
  expect(1 + 2).toBe(3);
});

// it is an alias for test
it("should subtract numbers", () => {
  expect(5 - 3).toBe(2);
});

// Async test
test("should handle async operations", async () => {
  const result = await fetchData();
  expect(result).toBe("data");
});

// Test with custom timeout
test("slow test", async () => {
  await slowOperation();
}, 10000);

// Focus on specific test
test.only("important test", () => {
  expect(true).toBe(true);
});

// Skip test
test.skip("broken test", () => {
  // This test will be skipped
});

// TODO test
test.todo("implement this feature");

// Failing test (expected to fail)
test.failing("known bug", () => {
  expect(buggyFunction()).toBe("correct");
});

// Concurrent test execution
test.concurrent("parallel test 1", async () => {
  const result = await asyncOperation1();
  expect(result).toBe("result1");
});

test.concurrent("parallel test 2", async () => {
  const result = await asyncOperation2();
  expect(result).toBe("result2");
});

// Parameterized tests
test.each([
  [1, 1, 2],
  [1, 2, 3], 
  [2, 1, 3],
])(".add(%i, %i)", (a, b, expected) => {
  expect(a + b).toBe(expected);
});

/**
 * Run once before all tests in the current describe block
 * @param fn - Hook function
 * @param timeout - Optional timeout in milliseconds
 */
function beforeAll(fn: HookFn, timeout?: number): void;

/**
 * Run once after all tests in the current describe block
 * @param fn - Hook function
 * @param timeout - Optional timeout in milliseconds
 */
function afterAll(fn: HookFn, timeout?: number): void;

/**
 * Run before each test in the current describe block
 * @param fn - Hook function
 * @param timeout - Optional timeout in milliseconds
 */
function beforeEach(fn: HookFn, timeout?: number): void;

/**
 * Run after each test in the current describe block
 * @param fn - Hook function
 * @param timeout - Optional timeout in milliseconds
 */
function afterEach(fn: HookFn, timeout?: number): void;

import { describe, test, beforeAll, afterAll, beforeEach, afterEach } from "jest-circus";

describe("Database tests", () => {
  let database;

  beforeAll(async () => {
    // Setup database connection once
    database = await createConnection();
  });

  afterAll(async () => {
    // Close database connection
    await database.close();
  });

  beforeEach(async () => {
    // Clean database before each test
    await database.clean();
  });

  afterEach(async () => {
    // Optional cleanup after each test
    await database.resetState();
  });

  test("should insert user", async () => {
    const user = await database.insertUser({ name: "John" });
    expect(user.id).toBeDefined();
  });

  test("should find user", async () => {
    await database.insertUser({ name: "Jane" });
    const user = await database.findUser({ name: "Jane" });
    expect(user).toBeTruthy();
  });
});

// Hooks with custom timeout
beforeAll(async () => {
  await slowSetup();
}, 30000); // 30 second timeout

type BlockNameLike = string | Function;
type TestNameLike = string | Function;

type BlockFn = () => void;
type TestFn = (done?: DoneFn) => void | Promise<void>;
type HookFn = (done?: DoneFn) => void | Promise<void>;
type DoneFn = (reason?: string | Error) => void;

type BlockMode = void | 'skip' | 'only' | 'todo';
type TestMode = BlockMode;