pw-element-interactions 0.0.4 → 0.0.6

package/dist/interactions/Interaction.js

@@ -1,18 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Interactions = exports.DropdownSelectType = void 0;
-/**
- * Defines the strategy for selecting an option from a dropdown element.
- */
-var DropdownSelectType;
-(function (DropdownSelectType) {
-    /** Selects a completely random, non-disabled option with a valid value. */
-    DropdownSelectType["RANDOM"] = "random";
-    /** Selects an option based on its zero-based index in the dropdown. */
-    DropdownSelectType["INDEX"] = "index";
-    /** Selects an option based on its exact 'value' attribute. */
-    DropdownSelectType["VALUE"] = "value";
-})(DropdownSelectType || (exports.DropdownSelectType = DropdownSelectType = {}));
+exports.Interactions = void 0;
+const Options_1 = require("../enum/Options");
+const ElementUtilities_1 = require("../utils/ElementUtilities");
 /**
  * The `Interactions` class provides a robust set of methods for interacting
  * with DOM elements via Playwright Locators. It abstracts away common boilerplate
@@ -20,12 +10,17 @@ var DropdownSelectType;
  */
 class Interactions {
     page;
+    ELEMENT_TIMEOUT;
+    utils;
     /**
      * Initializes the Interactions class.
      * @param page - The current Playwright Page object.
+     * @param timeout - Optional override for the default element timeout.
      */
-    constructor(page) {
+    constructor(page, timeout = 30000) {
         this.page = page;
+        this.ELEMENT_TIMEOUT = timeout;
+        this.utils = new ElementUtilities_1.Utils(this.ELEMENT_TIMEOUT);
     }
     /**
      * Performs a standard Playwright click on the given locator.
@@ -33,7 +28,8 @@ class Interactions {
      * @param locator - The Playwright Locator pointing to the target element.
      */
     async click(locator) {
-        await locator.click();
+        await this.utils.waitForState(locator, 'visible');
+        await locator.click({ timeout: this.ELEMENT_TIMEOUT });
     }
     /**
      * Dispatches a native 'click' event directly to the element.
@@ -42,6 +38,7 @@ class Interactions {
      * @param locator - The Playwright Locator pointing to the target element.
      */
     async clickWithoutScrolling(locator) {
+        await this.utils.waitForState(locator, 'attached');
         await locator.dispatchEvent('click');
     }
     /**
@@ -52,7 +49,7 @@ class Interactions {
      */
     async clickIfPresent(locator) {
         if (await locator.isVisible()) {
-            await locator.click();
+            await locator.click({ timeout: this.ELEMENT_TIMEOUT });
         }
         else {
             console.log(`[Action] -> Locator was not visible. Skipping click.`);
@@ -64,7 +61,8 @@ class Interactions {
      * @param text - The string to type into the input field.
      */
     async fill(locator, text) {
-        await locator.fill(text);
+        await this.utils.waitForState(locator, 'visible');
+        await locator.fill(text, { timeout: this.ELEMENT_TIMEOUT });
     }
     /**
      * Uploads a local file to an `<input type="file">` element.
@@ -72,45 +70,131 @@ class Interactions {
      * @param filePath - The local file system path to the file you want to upload.
      */
     async uploadFile(locator, filePath) {
+        await this.utils.waitForState(locator, 'attached');
         console.log(`[Action] -> Uploading file from path "${filePath}"`);
-        await locator.setInputFiles(filePath);
+        await locator.setInputFiles(filePath, { timeout: this.ELEMENT_TIMEOUT });
     }
     /**
      * Unified method to interact with `<select>` dropdown elements based on the specified `DropdownSelectType`.
      * If no options are provided, it safely defaults to randomly selecting an enabled, non-empty option.
-     * * @param locator - The Playwright Locator pointing to the `<select>` element.
+     * @param locator - The Playwright Locator pointing to the `<select>` element.
      * @param options - Configuration specifying whether to select by 'random', 'index', or 'value'.
      * @returns A promise that resolves to the exact 'value' attribute of the newly selected option.
      * @throws Error if 'value' or 'index' is missing when their respective types are chosen, or if no enabled options exist.
      */
-    async selectDropdown(locator, options = { type: DropdownSelectType.RANDOM }) {
-        const type = options.type ?? DropdownSelectType.RANDOM;
-        if (type === DropdownSelectType.VALUE) {
+    async selectDropdown(locator, options = { type: Options_1.DropdownSelectType.RANDOM }) {
+        await this.utils.waitForState(locator, 'visible');
+        const type = options.type ?? Options_1.DropdownSelectType.RANDOM;
+        if (type === Options_1.DropdownSelectType.VALUE) {
             if (options.value === undefined) {
                 throw new Error('[Action] Error -> "value" must be provided when using DropdownSelectType.VALUE.');
             }
-            const selected = await locator.selectOption({ value: options.value });
+            const selected = await locator.selectOption({ value: options.value }, { timeout: this.ELEMENT_TIMEOUT });
             return selected[0];
         }
-        if (type === DropdownSelectType.INDEX) {
+        if (type === Options_1.DropdownSelectType.INDEX) {
             if (options.index === undefined) {
                 throw new Error('[Action] Error -> "index" must be provided when using DropdownSelectType.INDEX.');
             }
-            const selected = await locator.selectOption({ index: options.index });
+            const selected = await locator.selectOption({ index: options.index }, { timeout: this.ELEMENT_TIMEOUT });
             return selected[0];
         }
         const enabledOptions = locator.locator('option:not([disabled]):not([value=""])');
+        await this.utils.waitForState(enabledOptions.first(), 'attached').catch(() => { });
         const count = await enabledOptions.count();
         if (count === 0) {
             throw new Error('[Action] Error -> No enabled options found to select!');
         }
         const randomIndex = Math.floor(Math.random() * count);
-        const valueToSelect = await enabledOptions.nth(randomIndex).getAttribute('value');
+        const valueToSelect = await enabledOptions.nth(randomIndex).getAttribute('value', { timeout: this.ELEMENT_TIMEOUT });
         if (valueToSelect === null) {
             throw new Error(`[Action] Error -> Option at index ${randomIndex} is missing a "value" attribute.`);
         }
-        const selected = await locator.selectOption({ value: valueToSelect });
+        const selected = await locator.selectOption({ value: valueToSelect }, { timeout: this.ELEMENT_TIMEOUT });
         return selected[0];
     }
+    /**
+     * Hovers over the specified element. Useful for triggering dropdowns or tooltips.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async hover(locator) {
+        await this.utils.waitForState(locator, 'visible');
+        await locator.hover({ timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+     * Scrolls the element into view if it is not already visible in the viewport.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async scrollIntoView(locator) {
+        await this.utils.waitForState(locator, 'attached');
+        await locator.scrollIntoViewIfNeeded({ timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+    * Drags an element either to a specified target element, a target element with an offset, or by a coordinate offset.
+    * @param locator - The Playwright Locator pointing to the element to drag.
+    * @param options - Configuration specifying a 'targetLocator', offsets, or both.
+    */
+    async dragAndDrop(locator, options) {
+        await this.utils.waitForState(locator, 'visible');
+        if (options.target) {
+            await this.utils.waitForState(options.target, 'visible');
+            if (options.xOffset !== undefined && options.yOffset !== undefined) {
+                const targetBox = await options.target.boundingBox();
+                if (!targetBox) {
+                    throw new Error(`[Action] Error -> Unable to get bounding box for target element.`);
+                }
+                const targetPosition = {
+                    x: (targetBox.width / 2) + options.xOffset,
+                    y: (targetBox.height / 2) + options.yOffset
+                };
+                await locator.dragTo(options.target, {
+                    targetPosition,
+                    timeout: this.ELEMENT_TIMEOUT
+                });
+                return;
+            }
+            await locator.dragTo(options.target, { timeout: this.ELEMENT_TIMEOUT });
+            return;
+        }
+        if (options.xOffset !== undefined && options.yOffset !== undefined) {
+            const box = await locator.boundingBox();
+            if (!box) {
+                throw new Error(`[Action] Error -> Unable to get bounding box for element to perform drag action.`);
+            }
+            const startX = box.x + box.width / 2;
+            const startY = box.y + box.height / 2;
+            await this.page.mouse.move(startX, startY);
+            await this.page.mouse.down();
+            await this.page.mouse.move(startX + options.xOffset, startY + options.yOffset, { steps: 10 });
+            await this.page.mouse.up();
+            return;
+        }
+        throw new Error(`[Action] Error -> You must provide either 'targetLocator', or both 'xOffset' and 'yOffset' in DragAndDropOptions.`);
+    }
+    /**
+       * Filters a locator list and returns the first element that contains the specified text.
+       * If the element is not found, it prints the available text contents of the base locator for debugging.
+       * @param baseLocator The base Playwright Locator.
+       * @param pageName The name of the page block in the JSON repository.
+       * @param elementName The specific element name to look up.
+       * @param desiredText The string of text to search for within the elements.
+       * @param strict If true, throws an error if the element is not found. Defaults to false.
+       * @returns A promise that resolves to the matched Playwright Locator, or null if not found.
+       */
+    async getByText(baseLocator, pageName, elementName, desiredText, strict = false) {
+        const locator = baseLocator.filter({ hasText: desiredText }).first();
+        if ((await locator.count()) === 0) {
+            const rawTexts = await baseLocator.allInnerTexts();
+            const availableTexts = rawTexts
+                .map((text) => text.trim())
+                .filter((text) => text.length > 0);
+            const msg = `Element '${elementName}' on '${pageName}' with text "${desiredText}" not found.\nAvailable texts found in locator: ${availableTexts.length > 0 ? `\n- ${availableTexts.join('\n- ')}` : 'None (Base locator found no elements or elements had no text)'}`;
+            if (strict)
+                throw new Error(msg);
+            console.warn(msg);
+            return null;
+        }
+        return locator;
+    }
 }
 exports.Interactions = Interactions;

package/dist/interactions/Navigation.js

@@ -20,7 +20,6 @@ class Navigation {
      * @param url - The absolute or relative URL to navigate to.
      */
     async toUrl(url) {
-        console.log(`[Navigate] -> Navigating to URL: ${url}`);
         await this.page.goto(url);
     }
     /**
@@ -28,7 +27,6 @@ class Navigation {
      * Useful for resetting application state or checking data persistence.
      */
     async reload() {
-        console.log(`[Navigate] -> Refreshing the current page`);
         await this.page.reload();
     }
     /**
@@ -37,7 +35,6 @@ class Navigation {
      * @param direction - The direction to move in history: either 'BACKWARDS' or 'FORWARDS'.
      */
     async backOrForward(direction) {
-        console.log(`[Navigate] -> Moving browser history ${direction.toLowerCase()}`);
         if (direction === 'BACKWARDS') {
             await this.page.goBack();
         }
@@ -52,7 +49,6 @@ class Navigation {
      * @param height - The desired height of the viewport in pixels.
      */
     async setViewport(width, height) {
-        console.log(`[Navigate] -> Setting viewport size to ${width}x${height}`);
         await this.page.setViewportSize({ width, height });
     }
 }

package/dist/interactions/Verification.d.ts

@@ -1,24 +1,28 @@
 import { Page, Locator } from '@playwright/test';
+import { CountVerifyOptions, TextVerifyOptions } from '../enum/Options';
 /**
  * The `Verifications` class provides a unified wrapper around Playwright's `expect` assertions.
- * It standardizes timeouts, adds helpful logging, and includes advanced custom verifications
+ * It standardizes timeouts and includes advanced custom, robust verifications
  * (like image decoding) to keep your test assertions clean and reliable.
  */
 export declare class Verifications {
     private page;
     /** The standard timeout applied to all verifications in this class. */
-    private readonly ELEMENT_TIMEOUT;
+    private ELEMENT_TIMEOUT;
     /**
      * Initializes the Verifications class.
      * @param page - The current Playwright Page object.
+     * @param timeout - Optional override for the default element timeout.
      */
-    constructor(page: Page);
+    constructor(page: Page, timeout?: number);
     /**
-     * Asserts that the specified element's text exactly matches the expected text.
+     * Asserts the text content of an element.
+     * Can verify exact text matches or simply check that the element contains some text.
      * @param locator - The Playwright Locator pointing to the target element.
-     * @param expectedText - The exact text string expected to be inside the element.
+     * @param expectedText - The exact text string expected (optional if checking 'notEmpty').
+     * @param options - Configuration to alter the verification behavior.
      */
-    text(locator: Locator, expectedText: string): Promise<void>;
+    text(locator: Locator, expectedText?: string, options?: TextVerifyOptions): Promise<void>;
     /**
      * Asserts that the specified element contains the expected substring.
      * @param locator - The Playwright Locator pointing to the target element.
@@ -32,9 +36,10 @@ export declare class Verifications {
     presence(locator: Locator): Promise<void>;
     /**
      * Asserts that the specified element is either hidden or completely detached from the DOM.
-     * @param locator - The Playwright Locator pointing to the target element.
+     * Accepts a Locator or a raw selector string to prevent unnecessary repository waits.
+     * @param selectorOrLocator - The Playwright Locator or raw selector string.
      */
-    absence(locator: Locator): Promise<void>;
+    absence(selectorOrLocator: Locator | string): Promise<void>;
     /**
      * Asserts the interactive state of an element (whether it is enabled or disabled).
      * Useful for checking buttons or input fields.
@@ -60,9 +65,15 @@ export declare class Verifications {
      * It checks for visibility, ensures a valid 'src' attribute exists, confirms the
      * 'naturalWidth' is greater than 0, and evaluates the browser's native `decode()`
      * promise to guarantee the image is fully rendered and not a broken link.
-     * * @param imagesLocator - The Playwright Locator pointing to the image element(s).
+     * @param imagesLocator - The Playwright Locator pointing to the image element(s).
      * @param scroll - Whether to smoothly scroll the image(s) into the viewport before verifying (default: true).
      * @throws Will throw an error if no images are found matching the locator or if any image fails to decode.
      */
     images(imagesLocator: Locator, scroll?: boolean): Promise<void>;
+    /**
+    * Asserts the number of elements matching the locator based on the provided conditions.
+    * @param locator - The Playwright Locator pointing to the target elements.
+    * @param options - Configuration specifying 'exact', 'greaterThan', or 'lessThan' logic.
+    */
+    count(locator: Locator, options: CountVerifyOptions): Promise<void>;
 }

package/dist/interactions/Verification.js

@@ -4,26 +4,40 @@ exports.Verifications = void 0;
 const test_1 = require("@playwright/test");
 /**
  * The `Verifications` class provides a unified wrapper around Playwright's `expect` assertions.
- * It standardizes timeouts, adds helpful logging, and includes advanced custom verifications
+ * It standardizes timeouts and includes advanced custom, robust verifications
  * (like image decoding) to keep your test assertions clean and reliable.
  */
 class Verifications {
     page;
     /** The standard timeout applied to all verifications in this class. */
-    ELEMENT_TIMEOUT = 10000;
+    ELEMENT_TIMEOUT;
     /**
      * Initializes the Verifications class.
      * @param page - The current Playwright Page object.
+     * @param timeout - Optional override for the default element timeout.
      */
-    constructor(page) {
+    constructor(page, timeout = 30000) {
         this.page = page;
+        this.ELEMENT_TIMEOUT = timeout;
     }
+    // ==========================================
+    // Standard Assertions
+    // ==========================================
     /**
-     * Asserts that the specified element's text exactly matches the expected text.
+     * Asserts the text content of an element.
+     * Can verify exact text matches or simply check that the element contains some text.
      * @param locator - The Playwright Locator pointing to the target element.
-     * @param expectedText - The exact text string expected to be inside the element.
+     * @param expectedText - The exact text string expected (optional if checking 'notEmpty').
+     * @param options - Configuration to alter the verification behavior.
      */
-    async text(locator, expectedText) {
+    async text(locator, expectedText, options) {
+        if (options?.notEmpty) {
+            await (0, test_1.expect)(locator).not.toBeEmpty({ timeout: this.ELEMENT_TIMEOUT });
+            return;
+        }
+        if (expectedText === undefined) {
+            throw new Error(`[Verify] -> You must provide either an 'expectedText' string or set '{ notEmpty: true }' in options.`);
+        }
         await (0, test_1.expect)(locator).toHaveText(expectedText, { timeout: this.ELEMENT_TIMEOUT });
     }
     /**
@@ -43,10 +57,13 @@ class Verifications {
     }
     /**
      * Asserts that the specified element is either hidden or completely detached from the DOM.
-     * @param locator - The Playwright Locator pointing to the target element.
+     * Accepts a Locator or a raw selector string to prevent unnecessary repository waits.
+     * @param selectorOrLocator - The Playwright Locator or raw selector string.
      */
-    async absence(locator) {
-        console.log(`[Verify] -> Asserting absence of "${locator}"`);
+    async absence(selectorOrLocator) {
+        const locator = typeof selectorOrLocator === 'string'
+            ? this.page.locator(selectorOrLocator)
+            : selectorOrLocator;
         await (0, test_1.expect)(locator).toBeHidden({ timeout: this.ELEMENT_TIMEOUT });
     }
     /**
@@ -56,7 +73,6 @@ class Verifications {
      * @param state - The expected state: either 'enabled' or 'disabled'.
      */
     async state(locator, state) {
-        console.log(`[Verify] -> Asserting state of "${locator}" is: "${state}"`);
         if (state === 'enabled') {
             await (0, test_1.expect)(locator).toBeEnabled({ timeout: this.ELEMENT_TIMEOUT });
         }
@@ -70,7 +86,6 @@ class Verifications {
      * @param text - The substring expected to be present within the active URL.
      */
     async urlContains(text) {
-        console.log(`[Verify] -> Asserting current URL contains: "${text}"`);
         await (0, test_1.expect)(this.page).toHaveURL(new RegExp(text, 'i'), { timeout: this.ELEMENT_TIMEOUT });
     }
     /**
@@ -87,7 +102,7 @@ class Verifications {
      * It checks for visibility, ensures a valid 'src' attribute exists, confirms the
      * 'naturalWidth' is greater than 0, and evaluates the browser's native `decode()`
      * promise to guarantee the image is fully rendered and not a broken link.
-     * * @param imagesLocator - The Playwright Locator pointing to the image element(s).
+     * @param imagesLocator - The Playwright Locator pointing to the image element(s).
      * @param scroll - Whether to smoothly scroll the image(s) into the viewport before verifying (default: true).
      * @throws Will throw an error if no images are found matching the locator or if any image fails to decode.
      */
@@ -117,7 +132,37 @@ class Verifications {
             });
             (0, test_1.expect)(isDecoded, `Image ${i + 1} failed to decode for ${imagesLocator}`).toBe(true);
         }
-        console.log(`[Verify] -> Successfully verified ${productImages.length} images for "${imagesLocator}"`);
+    }
+    /**
+    * Asserts the number of elements matching the locator based on the provided conditions.
+    * @param locator - The Playwright Locator pointing to the target elements.
+    * @param options - Configuration specifying 'exact', 'greaterThan', or 'lessThan' logic.
+    */
+    async count(locator, options) {
+        if (options.exactly !== undefined && options.exactly < 0) {
+            throw new Error(`[Verify] -> 'exact' count cannot be negative.`);
+        }
+        if (options.greaterThan !== undefined && options.greaterThan < 0) {
+            throw new Error(`[Verify] -> 'greaterThan' count cannot be negative.`);
+        }
+        if (options.lessThan !== undefined && options.lessThan <= 0) {
+            throw new Error(`[Verify] -> 'lessThan' must be greater than 0. Element counts cannot be negative.`);
+        }
+        if (options.exactly !== undefined) {
+            await (0, test_1.expect)(locator).toHaveCount(options.exactly, { timeout: this.ELEMENT_TIMEOUT });
+            return;
+        }
+        if (options.greaterThan === undefined && options.lessThan === undefined) {
+            throw new Error(`[Verify] -> You must provide 'exact', 'greaterThan', or 'lessThan' in CountVerifyOptions.`);
+        }
+        await locator.first().waitFor({ state: 'attached', timeout: this.ELEMENT_TIMEOUT }).catch(() => { });
+        const actualCount = await locator.count();
+        if (options.greaterThan !== undefined) {
+            (0, test_1.expect)(actualCount, `Expected count > ${options.greaterThan}, but got ${actualCount}`).toBeGreaterThan(options.greaterThan);
+        }
+        if (options.lessThan !== undefined) {
+            (0, test_1.expect)(actualCount, `Expected count < ${options.lessThan}, but got ${actualCount}`).toBeLessThan(options.lessThan);
+        }
     }
 }
 exports.Verifications = Verifications;

package/dist/interactions/facade/ElementInteractions.d.ts

@@ -0,0 +1,24 @@
+import { Page } from '@playwright/test';
+import { Interactions } from '../Interaction';
+import { Navigation } from '../Navigation';
+import { Verifications } from '../Verification';
+import { Extractions } from '../Extraction';
+import { Utils } from '../../utils/ElementUtilities';
+/**
+ * A facade class that centralizes package capabilities.
+ * It provides access to navigation, interaction, verification,
+ * extraction, and utility functions through a single interface.
+ */
+export declare class ElementInteractions {
+    interact: Interactions;
+    verify: Verifications;
+    extract: Extractions;
+    navigate: Navigation;
+    utils: Utils;
+    /**
+     * Initializes the ElementInteractions facade.
+     * @param page - The current Playwright Page object.
+     * @param timeout - Optional global timeout override (in milliseconds) for all interactions and verifications. Defaults to 30000 ms (30 seconds).
+     */
+    constructor(page: Page, timeout?: number);
+}

package/dist/interactions/facade/ElementInteractions.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementInteractions = void 0;
+const Interaction_1 = require("../Interaction");
+const Navigation_1 = require("../Navigation");
+const Verification_1 = require("../Verification");
+const Extraction_1 = require("../Extraction");
+const ElementUtilities_1 = require("../../utils/ElementUtilities");
+/**
+ * A facade class that centralizes package capabilities.
+ * It provides access to navigation, interaction, verification,
+ * extraction, and utility functions through a single interface.
+ */
+class ElementInteractions {
+    interact;
+    verify;
+    extract;
+    navigate;
+    utils;
+    /**
+     * Initializes the ElementInteractions facade.
+     * @param page - The current Playwright Page object.
+     * @param timeout - Optional global timeout override (in milliseconds) for all interactions and verifications. Defaults to 30000 ms (30 seconds).
+     */
+    constructor(page, timeout) {
+        this.interact = new Interaction_1.Interactions(page, timeout);
+        this.verify = new Verification_1.Verifications(page, timeout);
+        this.navigate = new Navigation_1.Navigation(page);
+        this.extract = new Extraction_1.Extractions(page);
+        this.utils = new ElementUtilities_1.Utils(timeout);
+    }
+}
+exports.ElementInteractions = ElementInteractions;