twd-js 1.6.6 → 1.7.0

package/dist/index.d.ts

@@ -288,7 +288,7 @@ declare interface TWDAPI {
     /**
      * Mock a network request.
      *
-     * @param alias Identifier for the mock rule. Useful for `waitFor()`.
+     * @param alias Identifier for the mock rule. Useful for `waitForRequest()`.
      * @param options Options to configure the mock:
      *  - `method`: HTTP method ("GET", "POST", …)
      *  - `url`: URL string or RegExp to match
@@ -318,9 +318,9 @@ declare interface TWDAPI {
      *
      * @example
      * ```ts
-     * const rule = await twd.waitFor("aliasId");
+     * const rule = await twd.waitForRequest("aliasId");
      * console.log(rule.body);
-     * const rule = await twd.waitFor("aliasId", 5, 100);
+     * const rule = await twd.waitForRequest("aliasId", 5, 100);
      * console.log(rule.body);
      *
      * ```
@@ -412,6 +412,30 @@ declare interface TWDAPI {
      * ```
      */
     wait: (time: number) => Promise<void>;
+    /**
+     * Retries a callback until it stops throwing or the timeout expires.
+     * Use this instead of `twd.wait(ms)` to wait for conditions rather than fixed delays.
+     *
+     * @param callback Function to retry — can be sync or async. Should throw if the condition is not yet met.
+     * @param options Optional timeout, interval, and message settings
+     * @returns A promise that resolves when the callback succeeds
+     *
+     * @example
+     * ```ts
+     * // Wait for an analytics event
+     * await twd.waitFor(() => {
+     *   const event = findEvent("purchase");
+     *   expect(event).to.exist;
+     * }, { message: "purchase event to fire" });
+     *
+     * // Wait with custom timeout
+     * await twd.waitFor(() => {
+     *   const el = document.querySelector(".loaded");
+     *   if (!el) throw new Error("not loaded");
+     * }, { timeout: 5000 });
+     * ```
+     */
+    waitFor: (callback: () => void | Promise<void>, options?: WaitForOptions) => Promise<void>;
     /**
      * Asserts something about the element.
      * @param el The element to assert on
@@ -622,4 +646,16 @@ declare type UserEvent = typeof default_2;
 
 export declare const userEvent: UserEvent;
 
+/**
+ * Options for `twd.waitFor()`.
+ */
+declare interface WaitForOptions {
+    /** Max time to wait in ms. Default: 2000 */
+    timeout?: number;
+    /** Poll interval in ms. Default: 50 */
+    interval?: number;
+    /** Context message included in timeout errors */
+    message?: string;
+}
+
 export { }