@umbraco/playwright-testhelpers 17.0.19 → 17.1.0-beta.1

package/dist/lib/helpers/BasePage.d.ts

@@ -0,0 +1,447 @@
+import { Locator, Page } from "@playwright/test";
+/**
+ * Base page class providing common UI interaction methods.
+ * All methods follow best practices for reliability:
+ * - click: Always checks element visibility before clicking
+ * - enterText: Always clears before filling text
+ * - select: Waits for element visibility before selecting
+ *
+ * @example
+ * ```typescript
+ * class MyPage extends BasePage {
+ *   readonly submitBtn: Locator;
+ *
+ *   constructor(page: Page) {
+ *     super(page);
+ *     this.submitBtn = page.getByRole('button', { name: 'Submit' });
+ *   }
+ *
+ *   async submit() {
+ *     await this.click(this.submitBtn);
+ *   }
+ * }
+ * ```
+ */
+export declare class BasePage {
+    readonly page: Page;
+    constructor(page: Page);
+    /**
+     * Clicks an element after verifying it is visible.
+     * @param locator - The element to click
+     * @param options - Optional click configuration
+     */
+    click(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Double-clicks an element after verifying it is visible.
+     * @param locator - The element to double-click
+     * @param options - Optional configuration
+     */
+    doubleClick(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Right-clicks an element after verifying it is visible.
+     * @param locator - The element to right-click
+     * @param options - Optional configuration
+     */
+    rightClick(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Clicks an element using JavaScript (bypasses actionability checks).
+     * Use when standard click doesn't work due to overlapping elements.
+     * @param locator - The element to click
+     */
+    forceClick(locator: Locator): Promise<void>;
+    /**
+     * Enters text into an input field after clearing it.
+     * Verifies element visibility before interaction.
+     * @param locator - The input element
+     * @param text - The text to enter
+     * @param options - Optional configuration
+     */
+    enterText(locator: Locator, text: string, options?: {
+        clearFirst?: boolean;
+        verify?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Types text character by character (simulates real typing).
+     * Useful when fill() doesn't trigger necessary events.
+     * @param locator - The input element
+     * @param text - The text to type
+     * @param options - Optional configuration
+     */
+    typeText(locator: Locator, text: string, options?: {
+        clearFirst?: boolean;
+        delay?: number;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Clears an input field.
+     * @param locator - The input element to clear
+     */
+    clearText(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Presses a keyboard key while focused on an element.
+     * @param locator - The element to focus
+     * @param key - The key to press (e.g., 'Enter', 'Tab', 'Escape')
+     */
+    pressKey(locator: Locator, key: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects an option from a dropdown by value.
+     * @param locator - The select element
+     * @param value - The option value to select
+     */
+    selectByValue(locator: Locator, value: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects an option from a dropdown by visible text.
+     * @param locator - The select element
+     * @param text - The option text to select
+     */
+    selectByText(locator: Locator, text: string, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects an option from a dropdown by index.
+     * @param locator - The select element
+     * @param index - The option index to select (0-based)
+     */
+    selectByIndex(locator: Locator, index: number, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Selects multiple options from a multi-select dropdown.
+     * @param locator - The select element
+     * @param values - Array of option values to select
+     */
+    selectMultiple(locator: Locator, values: string[], options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Checks a checkbox if it's not already checked.
+     * @param locator - The checkbox element
+     */
+    check(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Unchecks a checkbox if it's currently checked.
+     * @param locator - The checkbox element
+     */
+    uncheck(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Sets a checkbox to a specific state.
+     * @param locator - The checkbox element
+     * @param checked - Whether the checkbox should be checked
+     */
+    setChecked(locator: Locator, checked: boolean, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Hovers over an element.
+     * @param locator - The element to hover over
+     */
+    hover(locator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Focuses on an element.
+     * @param locator - The element to focus
+     */
+    focus(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Hovers over one element and clicks another (for menus that appear on hover).
+     * @param hoverLocator - The element to hover over
+     * @param clickLocator - The element to click after hover
+     */
+    hoverAndClick(hoverLocator: Locator, clickLocator: Locator, options?: {
+        force?: boolean;
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Waits for an element to be visible.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForVisible(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be hidden.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForHidden(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be attached to the DOM.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForAttached(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be detached from the DOM.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForDetached(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for the page to finish loading (network idle).
+     */
+    waitForPageLoad(): Promise<void>;
+    /**
+     * Waits for the DOM to be fully loaded.
+     */
+    waitForDOMContentLoaded(): Promise<void>;
+    /**
+     * Waits for all network requests to complete.
+     */
+    waitForLoadState(): Promise<void>;
+    /**
+     * Waits for an element to be enabled.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForEnabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be disabled.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForDisabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to contain specific text.
+     * @param locator - The element to wait for
+     * @param text - The text to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForText(locator: Locator, text: string, timeout?: number): Promise<void>;
+    /**
+     * Waits for an input to have a specific value.
+     * @param locator - The input element to wait for
+     * @param value - The value to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForValue(locator: Locator, value: string, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to have a specific attribute value.
+     * @param locator - The element to wait for
+     * @param name - The attribute name
+     * @param value - The expected attribute value
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForAttribute(locator: Locator, name: string, value: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to have a specific CSS class.
+     * @param locator - The element to wait for
+     * @param className - The CSS class to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForClass(locator: Locator, className: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be editable.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForEditable(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be checked.
+     * @param locator - The checkbox/radio element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForChecked(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be unchecked.
+     * @param locator - The checkbox/radio element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForUnchecked(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for a specific URL or URL pattern.
+     * @param url - The URL string or regex pattern to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForURL(url: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Waits for a navigation to complete.
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForNavigation(timeout?: number): Promise<void>;
+    /**
+     * Waits for a specific time (use sparingly, prefer explicit waits).
+     * @param milliseconds - Time to wait in milliseconds
+     */
+    waitForTimeout(milliseconds: number): Promise<void>;
+    /**
+     * Waits for a network request to a specific URL.
+     * @param urlOrPredicate - URL string, regex, or predicate function
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForRequest(urlOrPredicate: string | RegExp | ((request: any) => boolean), timeout?: number): Promise<any>;
+    /**
+     * Waits for a network response from a specific URL.
+     * @param urlOrPredicate - URL string, regex, or predicate function
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForResponse(urlOrPredicate: string | RegExp | ((response: any) => boolean), timeout?: number): Promise<any>;
+    /**
+     * Waits for an element to be focused.
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForFocused(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to be empty (no text content).
+     * @param locator - The element to wait for
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForEmpty(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Waits for a function to return true.
+     * @param predicate - Function that returns a boolean or Promise<boolean>
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForFunction(predicate: () => boolean | Promise<boolean>, timeout?: number): Promise<void>;
+    /**
+     * Waits for an element to have a specific CSS property value.
+     * @param locator - The element to wait for
+     * @param property - The CSS property name
+     * @param value - The expected CSS property value
+     * @param timeout - Maximum time to wait in milliseconds
+     */
+    waitForCSS(locator: Locator, property: string, value: string | RegExp, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element is visible.
+     * @param locator - The element to check
+     * @param isVisible - Whether the element should be visible (default: true)
+     */
+    isVisible(locator: Locator, isVisible?: boolean, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element is enabled.
+     * @param locator - The element to check
+     */
+    isEnabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element is disabled.
+     * @param locator - The element to check
+     */
+    isDisabled(locator: Locator, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element contains specific text.
+     * @param locator - The element to check
+     * @param text - The text to look for
+     */
+    containsText(locator: Locator, text: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element has specific text.
+     * @param locator - The element to check
+     * @param text - The exact text expected
+     */
+    hasText(locator: Locator, text: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an input has a specific value.
+     * @param locator - The input element to check
+     * @param value - The expected value
+     */
+    hasValue(locator: Locator, value: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that an element has a specific attribute value.
+     * @param locator - The element to check
+     * @param name - The attribute name
+     * @param value - The expected attribute value
+     */
+    hasAttribute(locator: Locator, name: string, value: string, timeout?: number): Promise<void>;
+    /**
+     * Asserts that a specific number of elements exist.
+     * @param locator - The locator to count
+     * @param count - The expected count
+     */
+    hasCount(locator: Locator, count: number, timeout?: number): Promise<void>;
+    /**
+     * Gets the text content of an element.
+     * @param locator - The element to get text from
+     * @returns The text content
+     */
+    getText(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Gets the value of an input element.
+     * @param locator - The input element
+     * @returns The input value
+     */
+    getValue(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<string>;
+    /**
+     * Gets an attribute value from an element.
+     * @param locator - The element
+     * @param attributeName - The attribute name
+     * @returns The attribute value or null
+     */
+    getAttribute(locator: Locator, attributeName: string, options?: {
+        timeout?: number;
+    }): Promise<string | null>;
+    /**
+     * Checks if an element is currently visible.
+     * @param locator - The element to check
+     * @returns True if visible, false otherwise
+     */
+    checkIsVisible(locator: Locator): Promise<boolean>;
+    /**
+     * Checks if a checkbox is checked.
+     * @param locator - The checkbox element
+     * @returns True if checked, false otherwise
+     */
+    isChecked(locator: Locator): Promise<boolean>;
+    /**
+     * Scrolls an element into view.
+     * @param locator - The element to scroll to
+     */
+    scrollIntoView(locator: Locator, options?: {
+        timeout?: number;
+    }): Promise<void>;
+    /**
+     * Sets files on a file input element.
+     * @param locator - The file input element
+     * @param filePath - Path to the file(s) to set
+     */
+    setInputFiles(locator: Locator, filePath: string | string[]): Promise<void>;
+    /**
+     * Clears files from a file input.
+     * @param locator - The file input element
+     */
+    clearInputFiles(locator: Locator): Promise<void>;
+    /**
+     * Drags an element and drops it on another element.
+     * @param source - The element to drag
+     * @param target - The element to drop on
+     */
+    dragTo(source: Locator, target: Locator, options?: {
+        sourcePosition?: {
+            x: number;
+            y: number;
+        };
+        targetPosition?: {
+            x: number;
+            y: number;
+        };
+    }): Promise<void>;
+}