poku/lib/modules/index.d.cts

🐷 Poku makes testing easy for Node.js, Bun, Deno, and you at the same time.

import { AssertValue, AssertEqual, AssertMatch, AssertRejects, AssertThrows, AssertionMessage, AsyncTestCb, TestCb, Describe, Code, Configs, ConfigFile } from './_shared.cjs';
export { Configs$1 as Configs, poku, VERSION as version } from './_shared.cjs';
import 'node:assert';
import 'node:child_process';

declare const assert: ((value: unknown, message?: string | Error | undefined) => void) & {
    ok: AssertValue;
    equal: AssertEqual;
    deepEqual: AssertEqual;
    strictEqual: AssertEqual;
    deepStrictEqual: AssertEqual;
    doesNotMatch: AssertMatch;
    doesNotReject: AssertRejects;
    throws: AssertThrows;
    doesNotThrow: AssertThrows;
    notEqual: AssertEqual;
    notDeepEqual: AssertEqual;
    notStrictEqual: AssertEqual;
    notDeepStrictEqual: AssertEqual;
    match: AssertMatch;
    ifError: AssertValue;
    fail: (message?: AssertionMessage) => never;
    rejects: AssertRejects;
};

declare const strict: ((value: unknown, message?: string | Error | undefined) => void) & {
    ok: AssertValue;
    equal: AssertEqual;
    deepEqual: AssertEqual;
    strictEqual: AssertEqual;
    deepStrictEqual: AssertEqual;
    doesNotMatch: AssertMatch;
    doesNotReject: AssertRejects;
    throws: AssertThrows;
    doesNotThrow: AssertThrows;
    notEqual: AssertEqual;
    notDeepEqual: AssertEqual;
    notStrictEqual: AssertEqual;
    notDeepStrictEqual: AssertEqual;
    match: AssertMatch;
    ifError: AssertValue;
    fail: (message?: AssertionMessage) => never;
    rejects: AssertRejects;
};

type Todo = {
    (message: string): void;
    (message: string, cb?: AsyncTestCb): Promise<void>;
    (message: string, cb?: TestCb): void;
};
type Modifier = {
    (message: string, cb: AsyncTestCb): Promise<void>;
    (message: string, cb: TestCb): void;
    (cb: AsyncTestCb): Promise<void>;
    (cb: TestCb): void;
};

type It = {
    (title: string, cb: AsyncTestCb): Promise<void>;
    (title: string, cb: TestCb): void;
    (cb: AsyncTestCb): Promise<void>;
    (cb: TestCb): void;
};

declare const test: It & {
    todo: Todo;
    skip: Modifier;
    only: Modifier;
};

declare const describe: Describe & {
    todo: Todo;
    skip: Modifier;
    only: Modifier;
};

declare const it: It & {
    todo: Todo;
    skip: Modifier;
    only: Modifier;
};

/** Reads an environment file and sets the environment variables. */
declare const envFile: (filePath?: string) => Promise<void>;

declare const skip: (message?: string) => never;

type Control = {
    pause: () => void;
    continue: () => void;
    reset: () => void;
};
type EachOptions = {
    immediate?: boolean;
};

/**
 * Handle **global states** and **external** services before each `test` or `it`.
 *
 * ---
 *
 * ```ts
 * import { beforeEach } from 'poku';
 *
 * const before = beforeEach(() => {
 *   // prepare
 * };
 *
 * before.pause();
 * before.continue();
 * before.reset();
 * ```
 */
declare const beforeEach: (callback: () => unknown, options?: EachOptions) => Control;
/**
 * Handle **global states** and **external** services after each `test` or `it`.
 *
 * ---
 *
 * ```ts
 * import { afterEach } from 'poku';
 *
 * const after = afterEach(() => {
 *   // cleanup
 * };
 *
 * after.pause();
 * after.continue();
 * after.reset();
 * ```
 */
declare const afterEach: (callback: () => unknown) => Control;

type Runner = 'npm' | 'bun' | 'deno' | 'yarn' | 'pnpm';

type BackgroundProcessOptions = {
    /**
     * - Default: resolves in the first console output
     * - String: waits for a specifc string on console output to resolve
     * - Number: waits for time in milliseconds to resolve
     *
     * @default undefined
     */
    startAfter?: string | number;
    /**
     * Stops the service for neither success nor failure after:
     *
     * @default 60000
     */
    timeout?: number;
    /** Shows the output from service */
    verbose?: boolean;
    /**
     * Specify a target path to start the process
     *
     * @default "./"
     */
    cwd?: string | undefined;
};
type StartScriptOptions = {
    /** By default, Poku will use `npm`. Change it as you want */
    readonly runner?: Runner;
} & BackgroundProcessOptions;
type StartServiceOptions = BackgroundProcessOptions;
type End = (port?: number | number[]) => Promise<void>;

/** Starts a file in a background process (useful for servers, APIs, etc.) */
declare const startService: (file: string, options?: StartServiceOptions) => Promise<{
    end: End;
}>;
/**
 *
 * Starts a script (package.json) or task (deno.json) in a background process (useful for servers, APIs, etc.).
 *
 * ---
 *
 * By default it uses **npm**, but you can costumize it using the `runner` option.
 */
declare const startScript: (script: string, options?: StartScriptOptions) => Promise<{
    end: End;
}>;

type WaitForExpectedResultOptions = {
    /**
     * Retry interval in milliseconds
     *
     * @default 100
     */
    interval?: number;
    /**
     * Timeout in milliseconds
     *
     * @default 60000
     */
    timeout?: number;
    /**
     * Delays both the start and end by the defined milliseconds
     *
     * @default 0
     */
    delay?: number;
    /**
     * Ensure strict comparisons
     *
     * - For **Bun** users, this option isn't necessary
     *
     * @default false
     */
    strict?: boolean;
};
type WaitForPortOptions = {
    /**
     * Host to check the port on
     *
     * @default "localhost"
     */
    host?: string;
} & Omit<WaitForExpectedResultOptions, 'strict'>;

/** Wait until the defined milliseconds. */
declare const sleep: (milliseconds: number) => Promise<void>;
/** Wait until a result is equal the expected value. */
declare const waitForExpectedResult: (callback: () => unknown | Promise<unknown>, expectedResult: unknown, options?: WaitForExpectedResultOptions) => Promise<void>;
/** Wait until the defined port is active. */
declare const waitForPort: (port: number, options?: WaitForPortOptions) => Promise<void>;

/** Kill processes by PIDs, ports and port ranges. */
declare const kill: {
    /** Kill the specified process ID */
    pid: (PID: number | number[]) => Promise<void>;
    /** Kill all processes listening on the specified port */
    port: (port: number | number[]) => Promise<void>;
    /** Kill all processes listening on the specified range ports */
    range: (startsAt: number, endsAt: number) => Promise<void>;
};

/** Returns an array containing the ID of all processes listening to the specified port */
declare const getPIDs: ((port: number | number[]) => Promise<number[]>) & {
    /** Returns an array containing the ID of all processes listening to the specified port range */
    range: (startsAt: number, endsAt: number) => Promise<number[]>;
};

declare const exit: (code: Code, quiet?: boolean) => void;

/** By default **Poku** only shows outputs generated from itself. This helper allows you to use an alternative to `console.log` with **Poku**. */
declare const log: (...args: unknown[]) => void;

declare const listFiles: (targetDir: string, configs?: Configs) => Promise<string[]>;

/** 🐷 Auxiliary function to define the `poku` configurations */
declare const defineConfig: (options: ConfigFile) => ConfigFile;

export { Code, ConfigFile, Configs as ListFilesConfigs, afterEach, assert, beforeEach, defineConfig, describe, envFile, exit, getPIDs, it, kill, listFiles, log, skip, sleep, startScript, startService, strict, test, waitForExpectedResult, waitForPort };
export type { StartScriptOptions, StartServiceOptions, WaitForExpectedResultOptions, WaitForPortOptions };