twd-js 1.1.2 → 1.2.0

package/dist/index.d.ts

@@ -1,7 +1,440 @@
-export { twd } from './twd';
-export { TWDSidebar } from './ui/TWDSidebar';
-export { initTests } from './initializers/initTests';
-export { expect } from 'chai';
-export { userEvent } from './proxies/userEvent';
-export { screenDom, configureScreenDom } from './proxies/screenDom';
-export type { Chai };
+import { configure } from '@testing-library/dom';
+import { default as default_2 } from '@testing-library/user-event';
+import { expect } from 'chai';
+import { JSX } from 'react/jsx-runtime';
+import { screen as screen_2 } from '@testing-library/dom';
+
+/**
+ * All assertion names, including negated ones.
+ */
+declare type AnyAssertion = Negatable_2<AssertionName>;
+
+/**
+ * All assertion names, including negated ones.
+ */
+declare type AnyURLAssertion = Negatable<URLAssertionName>;
+
+/**
+ * Maps assertion name to its argument tuple.
+ */
+declare type ArgsFor<A extends AnyAssertion> = A extends `not.${infer Base extends AssertionName}` ? AssertionArgs[Base] : A extends AssertionName ? AssertionArgs[A] : never;
+
+/**
+ * Argument types for each assertion.
+ */
+declare type AssertionArgs = {
+    "have.text": [expected: string];
+    "contain.text": [expected: string];
+    "be.empty": [];
+    "have.attr": [attr: string, value: string];
+    "have.value": [value: string];
+    "be.disabled": [];
+    "be.enabled": [];
+    "be.checked": [];
+    "be.selected": [];
+    "be.focused": [];
+    "be.visible": [];
+    "have.class": [className: string];
+};
+
+/**
+ * Types and interfaces for the TWD testing library.
+ *
+ * @module twd-types
+ */
+/**
+ * All supported assertion names for the `should` function.
+ *
+ * @example
+ * api.should("have.text", "Hello");
+ * api.should("be.empty");
+ */
+declare type AssertionName = "have.text" | "contain.text" | "be.empty" | "have.attr" | "have.value" | "be.disabled" | "be.enabled" | "be.checked" | "be.selected" | "be.focused" | "be.visible" | "have.class";
+
+export declare const configureScreenDom: typeof configure;
+
+export { expect }
+
+/**
+ * Initialize Vite test loading.
+ * @param testModules - The test modules to load.
+ * @param component - The React component to render the sidebar.
+ * @param createRoot - Function to create a React root.
+ * @example
+ * ```ts
+ * if (import.meta.env.DEV) {
+ *   const testModules = import.meta.glob("./example.twd.test.ts");
+ *   const { initTests, TWDSidebar } = await import('twd-js');
+ *   await initTests(testModules, <TWDSidebar open={true} position="left" />, createRoot);
+ * }
+ * ```
+ */
+export declare const initTests: (testModules: TestModule, Component: React.ReactNode, createRoot: (el: HTMLElement) => {
+    render: (el: React.ReactNode) => void;
+}) => Promise<void>;
+
+export declare function MockedComponent<TProps extends Record<string, any>>({ name, children, }: MockedComponentProps<TProps>): JSX.Element;
+
+declare interface MockedComponentProps<TProps = any> {
+    name: string;
+    children: React.ReactElement<TProps>;
+}
+
+/**
+ * Negatable assertion names (e.g., 'not.have.text').
+ */
+declare type Negatable<T extends string> = T | `not.${T}`;
+
+/**
+ * Negatable assertion names (e.g., 'not.have.text').
+ */
+declare type Negatable_2<T extends string> = T | `not.${T}`;
+
+declare interface Options {
+    method: string;
+    url: string | RegExp;
+    response: unknown;
+    status?: number;
+    responseHeaders?: Record<string, string>;
+    urlRegex?: boolean;
+}
+
+declare type Rule = {
+    method: string;
+    url: string | RegExp;
+    response: unknown;
+    alias: string;
+    executed?: boolean;
+    request?: any;
+    status?: number;
+    responseHeaders?: Record<string, string>;
+    urlRegex?: boolean;
+};
+
+declare type ScreenDom = typeof screen_2;
+
+export declare const screenDom: ScreenDom;
+
+/**
+ * Overloads for the `should` function, for best IntelliSense.
+ *
+ * @example
+ * twd.should("have.text", "Hello");
+ * twd.should("be.empty");
+ * twd.should("have.class", "active");
+ */
+declare type ShouldFn = {
+    (name: "have.text", expected: string): TWDElemAPI;
+    (name: "not.have.text", expected: string): TWDElemAPI;
+    (name: "contain.text", expected: string): TWDElemAPI;
+    (name: "not.contain.text", expected: string): TWDElemAPI;
+    (name: "be.empty"): TWDElemAPI;
+    (name: "not.be.empty"): TWDElemAPI;
+    (name: "have.attr", attr: string, value: string): TWDElemAPI;
+    (name: "not.have.attr", attr: string, value: string): TWDElemAPI;
+    (name: "have.value", value: string): TWDElemAPI;
+    (name: "not.have.value", value: string): TWDElemAPI;
+    (name: "be.disabled"): TWDElemAPI;
+    (name: "not.be.disabled"): TWDElemAPI;
+    (name: "be.enabled"): TWDElemAPI;
+    (name: "not.be.enabled"): TWDElemAPI;
+    (name: "be.checked"): TWDElemAPI;
+    (name: "not.be.checked"): TWDElemAPI;
+    (name: "be.selected"): TWDElemAPI;
+    (name: "not.be.selected"): TWDElemAPI;
+    (name: "be.focused"): TWDElemAPI;
+    (name: "not.be.focused"): TWDElemAPI;
+    (name: "be.visible"): TWDElemAPI;
+    (name: "not.be.visible"): TWDElemAPI;
+    (name: "have.class", className: string): TWDElemAPI;
+    (name: "not.have.class", className: string): TWDElemAPI;
+};
+
+/**
+ * A record of test module paths to their loader functions.
+ * Each function returns a promise that resolves when the module is loaded.
+ * This is typically used with Vite's `import.meta.glob` to dynamically import test modules.
+ * @example
+ * ```ts
+ * const testModules = {
+ *   './test1.twd.test.ts': () => import('./test1.twd.test.ts'),
+ *   './test2.twd.test.ts': () => import('./test2.twd.test.ts'),
+ * };
+ * ```
+ */
+declare type TestModule = Record<string, () => Promise<unknown>>;
+
+/**
+ * Mini Cypress-style helpers for DOM testing.
+ * @namespace twd
+ */
+export declare const twd: TWDAPI;
+
+declare 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>;
+    /**
+     * Sets the value of an input element and dispatches an input event. We recommend using this only for range, color, time inputs.
+     * @param el The input element
+     * @param value The value to set
+     *
+     * @example
+     * ```ts
+     * const input = await twd.get("input[type='time']");
+     * twd.setInputValue(input.el, "13:30");
+     *
+     * ```
+     */
+    setInputValue: (el: Element, value: string) => void;
+    /**
+     * 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
+     * @param [reload] Whether to force a reload even if already on the URL (optional)
+     *
+     * @example
+     * ```ts
+     * twd.visit("/contact");
+     * // visit with reload
+     * twd.visit("/contact", true);
+     * ```
+     */
+    visit: (url: string, reload?: boolean) => Promise<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) => Promise<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>;
+    /**
+     * Asserts something about the element.
+     * @param el The element to assert on
+     * @param name The name of the assertion.
+     * @param args Arguments for the assertion.
+     * @returns The same API for chaining.
+     * @example
+     * ```ts
+     * const button = await twd.get("button");
+     * const text = screenDom.getByText("Hello");
+     * twd.should(button.el, "have.text", "Hello");
+     * twd.should(text, "be.empty");
+     * twd.should(button.el, "have.class", "active");
+     * ```
+     */
+    should: (el: Element, name: AnyAssertion, ...args: ArgsFor<AnyAssertion>) => void;
+    /**
+     * Mock a component.
+     * @param name The name of the component to mock
+     * @param component The component to mock
+     * @returns The mocked component
+     * @example
+     * ```ts
+     * twd.mockComponent("Button", Button);
+     * ```
+     */
+    mockComponent: (name: string, component: React.ComponentType<any>) => void;
+    /**
+     * Clears all component mocks.
+     *
+     * @example
+     * ```ts
+     * twd.clearComponentMocks();
+     * ```
+     */
+    clearComponentMocks: () => void;
+    /**
+     * Asserts that an element does not exist in the DOM.
+     * @param selector CSS selector of the element to check
+     * @returns A promise that resolves if the element does not exist, or rejects if it does
+     *
+     * @example
+     * ```ts
+     * await twd.notExists(".non-existent");
+     * ```
+     */
+    notExists: (selector: string) => Promise<void>;
+}
+
+/**
+ * The main API returned by `twd.get()`.
+ *
+ * @example
+ * ```ts
+ * const btn = await twd.get("button");
+ * btn.should("have.text", "Clicked").click();
+ *
+ * ```
+ *
+ */
+declare interface TWDElemAPI {
+    /** The underlying DOM element. */
+    el: Element;
+    /**
+     * Asserts something about the element.
+     * @param name The name of the assertion.
+     * @param args Arguments for the assertion.
+     * @returns The same API for chaining.
+     *
+     * @example
+     * ```ts
+     * const btn = await twd.get("button");
+     * btn.should("have.text", "Click me").should("not.be.disabled");
+     *
+     * ```
+     *
+     */
+    should: ShouldFn;
+}
+
+export declare const TWDSidebar: ({ open, position }: TWDSidebarProps) => JSX.Element;
+
+declare interface TWDSidebarProps {
+    /**
+     * Whether the sidebar is open by default
+     */
+    open: boolean;
+    /**
+     * Sidebar position
+     * - left: Sidebar on the left side (default)
+     * - right: Sidebar on the right side
+     *
+     * @default "left"
+     */
+    position?: "left" | "right";
+}
+
+/**
+ * All supported assertion names for the `should` function in url command
+ *
+ * @example
+ * twd.url().should("contain.url", "/new-page");
+ * twd.url().should("eq", "http://localhost:3000/new-page");
+ */
+declare type URLAssertionName = "eq" | "contain.url";
+
+declare type URLCommandAPI = {
+    location: Location;
+    should: (name: AnyURLAssertion, value: string) => URLCommandAPI | string;
+};
+
+declare type UserEvent = typeof default_2;
+
+export declare const userEvent: UserEvent;
+
+export { }