twd-js 1.6.6 → 1.7.1

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,33 @@ 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 with the callback's return value when it succeeds
+     *
+     * @example
+     * ```ts
+     * // Wait for an analytics event and return it
+     * const event = await twd.waitFor(() => {
+     *   const ev = findEvent("purchase");
+     *   expect(ev).to.exist;
+     *   return ev;
+     * }, { message: "purchase event to fire" });
+     *
+     * // Wait for an element (single expression)
+     * const heading = await twd.waitFor(() => screenDom.getByRole("heading", { name: /checkout/i }));
+     *
+     * // Fire-and-forget (void) — still works as before
+     * await twd.waitFor(() => {
+     *   expect(submitButton.disabled).to.be.false;
+     * });
+     * ```
+     */
+    waitFor: <T>(callback: () => T | Promise<T>, options?: WaitForOptions) => Promise<T>;
     /**
      * Asserts something about the element.
      * @param el The element to assert on
@@ -622,4 +649,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 { }