Core Testing API

/**
 * Create a Japa test. Defining a test without the callback will create a todo test.
 * @param title - The test title
 * @param callback - Optional test executor function
 * @returns Test instance for chaining
 */
function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<undefined>;

interface TestExecutor<Context, TestData> {
  (context: Context, done?: Function): void | Promise<void>;
}

import { test } from "@japa/runner";
import { assert } from "chai"; // or your preferred assertion library

// Basic test
test("should calculate sum correctly", async (ctx) => {
  const result = 2 + 3;
  assert.equal(result, 5);
});

// Todo test (without callback)
test("should implement user authentication");

// Test with custom timeout
test("should handle async operations", async (ctx) => {
  await new Promise(resolve => setTimeout(resolve, 1000));
  assert.isTrue(true);
}).timeout(2000);

/**
 * Configure the tests runner with inline configuration.
 * Must be called before the run method.
 * CLI flags will overwrite the options provided to the configure method.
 * @param options - Configuration options
 */
function configure(options: Config): void;

interface Config {
  cwd?: string;
  timeout?: number;
  retries?: number;
  filters?: Filters;
  configureSuite?: (suite: Suite) => void;
  reporters?: {
    activated: string[];
    list?: NamedReporterContract[];
  };
  plugins?: PluginFn[];
  importer?: (filePath: URL) => void | Promise<void>;
  refiner?: Refiner;
  forceExit?: boolean;
  setup?: SetupHookHandler[];
  teardown?: TeardownHookHandler[];
  exclude?: string[];
} & (
  | { files: TestFiles }
  | { suites: TestSuite[] }
);

interface Filters {
  files?: string[];
  suites?: string[];
  tests?: string | string[];
  groups?: string | string[];
  tags?: string | string[];
}

import { configure } from "@japa/runner";

// Basic configuration with files
configure({
  files: ["tests/**/*.spec.ts"],
  timeout: 5000,
  forceExit: false,
});

// Configuration with suites
configure({
  suites: [
    {
      name: "unit",
      files: ["tests/unit/**/*.spec.ts"],
      timeout: 2000,
    },
    {
      name: "integration", 
      files: ["tests/integration/**/*.spec.ts"],
      timeout: 10000,
    },
  ],
  filters: {
    tags: ["@slow", "@integration"],
  },
});

// Configuration with reporters and plugins
configure({
  files: ["tests/**/*.spec.ts"],
  reporters: {
    activated: ["spec", "ndjson"],
  },
  plugins: [myCustomPlugin()],
  setup: [setupDatabase],
  teardown: [cleanupDatabase],
});

/**
 * Execute Japa tests. Calling this function will import the test files behind the scenes.
 * Must be called after configure().
 */
async function run(): Promise<void>;

import { test, configure, run } from "@japa/runner";

// Configure and run tests
configure({
  files: ["tests/**/*.spec.ts"],
});

// Define tests
test("example test", async (ctx) => {
  assert.isTrue(true);
});

// Run the tests
await run();

/**
 * Make Japa process command line arguments. 
 * Later the parsed output will be used by Japa to compute the configuration.
 * @param argv - Array of command line arguments
 */
function processCLIArgs(argv: string[]): void;

import { processCLIArgs, configure, run } from "@japa/runner";

// Process CLI arguments
processCLIArgs(process.argv.slice(2));

// Configure and run tests
configure({
  files: ["tests/**/*.spec.ts"],
});

await run();

/**
 * Get the currently running test instance
 * @returns Current test instance or undefined if not in test context
 */
function getActiveTest(): Test<any> | undefined;

/**
 * Get the currently running test instance or throw an error
 * @returns Current test instance
 * @throws Error if not in test context
 */
function getActiveTestOrFail(): Test<any>;

import { test, getActiveTest, getActiveTestOrFail } from "@japa/runner";

// Using in a macro
const assertUserExists = test.macro(() => {
  const currentTest = getActiveTestOrFail();
  currentTest.cleanup(() => {
    // Cleanup logic here
  });
  
  // Test logic here
});

test("user operations", (ctx) => {
  assertUserExists();
  // Test continues...
});

interface TestExecutor<Context, TestData> {
  (context: Context, done?: Function): void | Promise<void>;
}

type TestFiles = string | string[] | (() => URL[] | Promise<URL[]>);

interface TestSuite {
  name: string;
  files: TestFiles;
  configure?: (suite: Suite) => void;
  timeout?: number;
  retries?: number;
}