@playq/core 0.2.77

package/dist/helper/actions/web/waitActions.d.ts

@@ -0,0 +1,191 @@
+import { Page, Locator } from "@playwright/test";
+/**
+ * Comm: Wait-In-Milli-Seconds -seconds: {param}
+ *
+ * Pauses execution for the given number of milliseconds.
+ * Delegates to `comm.waitInMilliSeconds`.
+ *
+ * @param ms Milliseconds to wait
+ */
+export declare function wait(ms: number): Promise<void>;
+/**
+ * Web: Wait For Condition -timeout: {param}
+ *
+ * Polls a predicate until it returns true or times out.
+ *
+ * @param page Playwright Page instance
+ * @param predicate Async function returning a boolean
+ * @param options Optional JSON string or object ({ timeout, interval })
+ */
+export declare function waitForCondition(page: Page, predicate: (page: Page) => Promise<boolean>, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Waits for the page to fully load by checking multiple browser states:
+ * - `domcontentloaded`: Ensures DOM is parsed and ready.
+ * - `load`: Waits for all resources like images and scripts to load.
+ * - `requestIdleCallback`: Ensures the browser is idle before proceeding.
+ *
+ * This function is useful after navigation, form submission, or any page transition
+ * to ensure stable element interaction.
+ *
+ * @param page - The Playwright Page instance.
+ * @param actionTimeout - Optional timeout (in ms) to wait for each load state. Default: 10000.
+ *
+ */
+export declare function waitForPageToLoad(page: Page, actionTimeout?: number): Promise<void>;
+/**
+ * Waits for a given locator (element) to become enabled within the specified timeout.
+ * Useful before interacting with inputs, buttons, or other dynamic UI elements.
+ *
+ * @param locator - The Playwright Locator to wait for (e.g., input field, button).
+ * @param actionTimeout - Optional timeout (in ms). Default: 5000.
+ *
+ * @throws Error if the locator does not become enabled within the timeout.
+ *
+ */
+export declare function waitForEnabled(locator: Locator, actionTimeout?: number): Promise<void>;
+/**
+ * Web: Wait for displayed -field: {param} -options: {param}
+ *
+ * Waits for an element to become visible on the page.
+ *
+ * @param page - Playwright Page instance
+ * @param field - The label, id, name, or selector of the element to wait for
+ * @param options - Optional JSON string or object:
+ *   - actionTimeout: [number] Optional timeout in milliseconds. Default: Configured timeout.
+ *   - pattern: [string] Optional pattern to refine element search.
+ *   - fieldType: [string] Type of field (e.g., input, button, etc.)
+ *   - screenshot: [boolean] Capture screenshot after waiting. Default: false.
+ *   - screenshotText: [string] Description for screenshot.
+ *   - screenshotFullPage: [boolean] Full page screenshot. Default: true.
+ */
+export declare function waitForDisplayed(page: Page, field: string | Locator, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for disappear -field: {param} -options: {param}
+ *
+ * Waits for an element to disappear (become hidden or removed) from the page.
+ *
+ * @param page - Playwright Page instance
+ * @param field - The label, id, name, or selector of the element to wait for
+ * @param options - Optional JSON string or object:
+ *   - actionTimeout: [number] Optional timeout in milliseconds. Default: Configured timeout.
+ *   - pattern: [string] Optional pattern to refine element search.
+ *   - fieldType: [string] Type of field (e.g., input, button, etc.)
+ *   - screenshot: [boolean] Capture screenshot after waiting. Default: false.
+ *   - screenshotText: [string] Description for screenshot.
+ *   - screenshotFullPage: [boolean] Full page screenshot. Default: true.
+ */
+export declare function waitForDisappear(page: Page, field: string | Locator, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for Text at Location -field: {param} -text: {param} -options: {param}
+ *
+ * Waits until the specified text appears at the given field/locator.
+ *
+ * @param page - Playwright Page instance
+ * @param field - The selector or Locator where the text should appear
+ * @param expectedText - The text to wait for
+ * @param options - Optional string or object:
+ *   - actionTimeout: [number] Timeout in ms (default: 30000)
+ *   - partialMatch: [boolean] If true, waits for substring match (default: false)
+ *   - caseSensitive: [boolean] If true, match is case-sensitive (default: true)
+ *   - screenshot: [boolean] Capture screenshot after waiting (default: false)
+ *   - screenshotText: [string] Description for screenshot
+ *   - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ *
+ * @example
+ *   await waitForTextAtLocation(page, 'h1', 'Welcome', { actionTimeout: 10000, partialMatch: true });
+ */
+export declare function waitForTextAtLocation(page: Page, field: string | Locator, expectedText: string, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for Text to Disappear at Location -field: {param} -text: {param} -options: {param}
+ *
+ * Waits until the specified text disappears from the given field/locator.
+ *
+ * @param page - Playwright Page instance
+ * @param field - The selector or Locator where the text should disappear
+ * @param textToDisappear - The text to wait for disappearance
+ * @param options - Optional string or object:
+ *   - actionTimeout: [number] Timeout in ms (default: 30000)
+ *   - partialMatch: [boolean] If true, waits for substring match (default: false)
+ *   - ignoreCase: [boolean] If true, match is case-insensitive (default: true)
+ *   - screenshot: [boolean] Capture screenshot after waiting (default: false)
+ *   - screenshotText: [string] Description for screenshot
+ *   - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ */
+export declare function waitForTextToDisappearAtLocation(page: Page, field: string | Locator, textToDisappear: string, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for Selector -field: {param} -options: {param}
+ *
+ * Waits for a selector or locator to reach a specific state.
+ *
+ * @param page - Playwright Page instance
+ * @param field - The selector string or Locator to wait for
+ * @param options - Optional string or object:
+ *   - fieldType: [string] Type of field (e.g., 'button', 'input') for pattern resolution
+ *   - state: [string] 'attached' | 'detached' | 'visible' | 'hidden' (default: 'visible')
+ *   - actionTimeout: [number] Timeout in ms (default: 30000)
+ *   - pattern: [string] Optional pattern for locator resolution
+ *   - screenshot: [boolean] Capture screenshot after waiting (default: false)
+ *   - screenshotText: [string] Description for screenshot
+ *   - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ *
+ * @example
+ *   await waitForSelector(page, 'img[alt="~"]', { state: 'hidden', actionTimeout: 10000 });
+ */
+export declare function waitForSelector(page: Page, field: string | Locator, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for Header -header: {param} -text: {param} -options: {param}
+ *
+ * Waits until a specific header element contains the expected text.
+ * The header parameter should be a locator or will use pattern resolution.
+ *
+ * @param page - Playwright Page instance
+ * @param header - The locator of the header element (e.g., "h1", "xpath=//h1[@class='title']", or Locator object)
+ * @param headerText - The expected header text to wait for (e.g., "Welcome", "Dashboard")
+ * @param options - Optional string or object:
+ *   - actionTimeout: [number] Timeout in ms (default: 30000)
+ *   - partialMatch: [boolean] If true, waits for substring match (default: false)
+ *   - ignoreCase: [boolean] If true, case-insensitive match (default: true)
+ *   - pattern: [string] Optional pattern to refine element search
+ *   - screenshot: [boolean] Capture screenshot after waiting (default: false)
+ *   - screenshotText: [string] Description for screenshot
+ *   - screenshotFullPage: [boolean] Full page screenshot (default: true)
+ *
+ * @example
+ *   await waitForHeader(page, 'h1', 'Welcome Back!', {
+ *     partialMatch: true,
+ *     screenshot: true
+ *   });
+ */
+export declare function waitForHeader(page: Page, header: string | Locator, headerText: string, options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for Input -field: {param} -state: {param} (enabled or disabled) -options: {param}
+ *
+ * Waits for an input field to become 'enabled' or 'disabled'.
+ *
+ * @param page - Playwright Page instance
+ * @param field - Locator or label of the input field
+ * @param state - Desired state: 'enabled' or 'disabled'
+ * @param options - Optional string or object:
+ *   - actionTimeout: [number] Optional timeout in milliseconds for waiting. Default: from [config] or 30000.
+ *   - pattern: [string] Optional pattern to refine element search.
+ *   - screenshot: [boolean] Capture a screenshot. Default: true.
+ *   - screenshotText: [string] Description for the screenshot.
+ *   - screenshotFullPage: [boolean] Capture full page screenshot. Default: true.
+ *   - smartIQ_refreshLoc: optional override for locator refresh key
+ */
+export declare function waitForInputState(page: Page, field: string | Locator, state: "enabled" | "disabled", options?: string | Record<string, any>): Promise<void>;
+/**
+ * Web: Wait for URL -url: {param} -options: {param}
+ *
+ * Waits until the current page URL matches or contains the specified string or regex.
+ *
+ * @param url - The expected URL or substring/regex to match (e.g., "/dashboard", "https://example.com/page").
+ * @param options - Optional JSON string or object:
+ *   - actionTimeout: [number] Timeout in ms to wait for URL. Default: 30000.
+ *   - match: [string] "exact" | "contains" . Default: "contains".
+ *   - assert: [boolean] If false, logs the failure but does not throw. Default: true.
+ *   - screenshot: [boolean] If true, captures screenshot. Default: false.
+ *   - screenshotText: [string] Custom screenshot label.
+ *   - screenshotFullPage: [boolean] Full page screenshot. Default: true.
+ */
+export declare function waitForUrl(page: Page, url: string, options?: string | Record<string, any>): Promise<void>;