twd-js/dist/twd.d.ts

Test While Developing (TWD) - in-browser testing

import { Options, Rule } from './commands/mockBridge';
import { TWDElemAPI } from './twd-types';
import { URLCommandAPI } from './commands/url';
/**
 * Stores the function to run before each test.
 */
declare let beforeEachFn: (() => void | Promise<void>) | null;
/**
 * Registers a function to run before each test.
 * @example
 * beforeEach(() => { ... });
 */
export declare const beforeEach: (fn: typeof beforeEachFn) => void;
/**
 * Groups related tests together.
 * @example
 * describe("My group", () => { ... });
 */
export declare const describe: (name: string, fn: () => void) => void;
/**
 * Defines a test case.
 * @example
 * it("does something", async () => { ... });
 */
export declare const it: (name: string, fn: () => Promise<void> | void) => void;
/**
 * Defines an exclusive test case (only this runs).
 * @example
 * itOnly("runs only this", async () => { ... });
 */
export declare const itOnly: (name: string, fn: () => Promise<void> | void) => void;
/**
 * Skips a test case.
 * @example
 * itSkip("skipped test", () => { ... });
 */
export declare const itSkip: (name: string, _fn: () => Promise<void> | void) => void;
interface TWDAPI {
    /**
     * Finds an element by selector and returns the TWD API for it.
     * @param selector CSS selector
     * @returns {Promise<TWDElemAPI>} The TWD API for the element
     *
     * @example
     * ```ts
     * const btn = await twd.get("button");
     *
     * ```
     *
     */
    get: (selector: string) => Promise<TWDElemAPI>;
    /**
     * Finds multiple elements by selector and returns an array of TWD APIs for them.
     * @param selector CSS selector
     * @returns {Promise<TWDElemAPI[]>} Array of TWD APIs for the elements
     *
     * @example
     * ```ts
     * const items = await twd.getAll(".item");
     * items.at(0).should("be.visible");
     * items.at(1).should("contain.text", "Hello");
     * expect(items).to.have.length(3);
     * ```
     */
    getAll: (selector: string) => Promise<TWDElemAPI[]>;
    /**
     * Simulates visiting a URL (SPA navigation).
     * @param url The URL to visit
     *
     * @example
     * ```ts
     * twd.visit("/contact");
     *
     * ```
     */
    visit: (url: string) => void;
    /**
     * Mock a network request.
     *
     * @param alias Identifier for the mock rule. Useful for `waitFor()`.
     * @param options Options to configure the mock:
     *  - `method`: HTTP method ("GET", "POST", …)
     *  - `url`: URL string or RegExp to match
     *  - `response`: Body of the mocked response
     *  - `status`: (optional) HTTP status code (default: 200)
     *  - `headers`: (optional) Response headers
     *
     * @example
     * ```ts
     * mockRequest("getUser", {
     *   method: "GET",
     *   url: /\/api\/user\/\d+/,
     *   response: { id: 1, name: "Kevin" },
     *   status: 200,
     *   headers: { "x-mock": "true" }
     * });
     * ```
     */
    mockRequest: (alias: string, options: Options) => void;
    /**
     * Wait for a mocked request to be made.
     * @param alias The alias of the mock rule to wait for
     * @return The matched rule (with body if applicable)
     *
     * @example
     * ```ts
     * const rule = await twd.waitFor("aliasId");
     * console.log(rule.body);
     *
     * ```
     */
    waitForRequest: (alias: string) => Promise<Rule>;
    /**
     * wait for a list of mocked requests to be made.
     * @param aliases The aliases of the mock rules to wait for
     * @returns The matched rules (with body if applicable)
     * @example
     * ```ts
     * const rules = await waitForRequests(["getUser", "postComment"]);
     * ```
     */
    waitForRequests: (aliases: string[]) => Promise<Rule[]>;
    /**
     * URL-related assertions.
     *
     * @example
     * ```ts
     * twd.url().should("eq", "http://localhost:3000/contact");
     * twd.url().should("contain.url", "/contact");
     *
     * ```
     */
    url: () => URLCommandAPI;
    /**
     * Initializes request mocking (registers the service worker).
     * Must be called before using `twd.mockRequest()`.
     *
     * @example
     * ```ts
     * await twd.initRequestMocking();
     *
     * ```
     */
    initRequestMocking: () => Promise<void>;
    /**
     * Clears all request mock rules.
     *
     * @example
     * ```ts
     * twd.clearRequestMockRules();
     *
     * ```
     */
    clearRequestMockRules: () => void;
    /**
     * Gets all current request mock rules.
     *
     * @example
     * ```ts
     * const rules = twd.getRequestMockRules();
     * console.log(rules);
     * ```
     */
    getRequestMockRules: () => Rule[];
    /**
     * Waits for a specified time.
     * @param time Time in milliseconds to wait
     * @returns A promise that resolves after the specified time
     * @example
     * ```ts
     * await twd.wait(500); // wait for 500ms
     * ```
     */
    wait: (time: number) => Promise<void>;
}
/**
 * Mini Cypress-style helpers for DOM testing.
 * @namespace twd
 */
export declare const twd: TWDAPI;
export {};