pw-element-interactions 0.0.3 → 0.0.5

package/README.md

@@ -10,6 +10,32 @@ A robust set of Playwright steps for readable interaction and assertions.
 
 With the introduction of the `Steps` class, you can now combine your element repository and interactions into a single, flattened Facade. This eliminates repetitive locator fetching and transforms your tests into clean, plain-English steps.
 
+### 🤖 AI-Friendly Test Development & Boilerplate Reduction
+
+Stop writing the same three lines of code for every single interaction. This library handles the fetching, waiting, and acting automatically.
+
+Because the API is highly semantic and completely decoupled from the DOM, it is an **ideal framework for AI coding assistants**. AI models can easily generate robust test flows using plain-English strings (`'CheckoutPage'`, `'submitButton'`) without hallucinating complex CSS selectors, writing flaky interactions, or forgetting critical `waitFor` states.
+
+**Before (Raw Playwright):**
+
+```ts
+// 1. Hardcode or manage raw locators inside your test
+const submitBtn = page.locator('button[data-test="submit-order"]');
+
+// 2. Explicitly wait for DOM stability and visibility
+await submitBtn.waitFor({ state: 'visible', timeout: 30000 });
+
+// 3. Perform the interaction
+await submitBtn.click();
+```
+
+**Now (with pw-element-interactions):**
+
+```ts
+// 1. Locate, wait, and interact in a single, readable, AI-friendly line
+await steps.click('CheckoutPage', 'submitButton');
+```
+
 ---
 
 ## 📦 Installation
@@ -30,8 +56,11 @@ This package requires `@playwright/test` to be installed in your project. If you
 * **Zero Locator Boilerplate:** The new `Steps` API fetches elements and interacts with them in a single method call.
 * **Separation of Concerns:** Keep your interaction logic entirely detached from how elements are found on the page.
 * **Readable Tests:** Abstract away Playwright boilerplate into semantic methods (`clickIfPresent`, `verifyPresence`, `selectDropdown`).
+* **Standardized Waiting:** Easily wait for elements to reach specific DOM states (visible, hidden, attached, detached) with built-in utility methods.
 * **Advanced Visual Checks:** Includes a highly reliable `verifyImages` method that evaluates actual browser decoding and `naturalWidth` to ensure images aren't just in the DOM, but are properly rendered.
 * **Smart Dropdowns:** Easily select dropdown options by value, index, or completely randomly (skipping disabled or empty options automatically).
+* **Flexible Verifications:** Easily verify exact text, non-empty text, or dynamic element counts (greater than, less than, or exact).
+* **Advanced Drag & Drop:** Seamlessly drag elements to other elements, drop them at specific coordinate offsets, or combine both strategies natively.
 
 ---
 
@@ -44,7 +73,7 @@ Initialize the `Steps` class by passing the current Playwright `page` object and
 ```ts
 import { test } from '@playwright/test';
 import { ElementRepository } from 'pw-element-repository';
-import { Steps } from 'pw-element-interactions';
+import { Steps, DropdownSelectType } from 'pw-element-interactions';
 
 test('Add random product and verify image gallery', async ({ page }) => {
   // 1. Initialize Repository & Steps
@@ -62,11 +91,20 @@ test('Add random product and verify image gallery', async ({ page }) => {
   await steps.verifyUrlContains('/product/');
 
   // 5. Smart Dropdown Interaction
-  const selectedSize = await steps.selectDropdown('ProductDetailsPage', 'size-selector', { type: 'random' });
+  const selectedSize = await steps.selectDropdown('ProductDetailsPage', 'size-selector', { 
+    type: DropdownSelectType.RANDOM 
+  });
   console.log(`Selected size: ${selectedSize}`);
 
-  // 6. Advanced Image Verification
+  // 6. Flexible Assertions & Data Extraction
+  await steps.verifyCount('ProductDetailsPage', 'gallery-images', { greaterThan: 0 });
+  await steps.verifyText('ProductDetailsPage', 'product-title', undefined, { notEmpty: true });
+  
+  // 7. Advanced Image Verification
   await steps.verifyImages('ProductDetailsPage', 'gallery-images');
+  
+  // 8. Explicit Waits
+  await steps.waitForState('CheckoutPage', 'confirmation-modal', 'visible');
 });
 ```
 
@@ -83,26 +121,36 @@ The `Steps` class automatically handles fetching the Playwright `Locator` using
 
 ### 🖱️ Interaction
 
-* **`click(pageName: string, elementName: string)`**: Retrieves an element from the repository and performs a standard click. Automatically waits for actionability.
+* **`click(pageName: string, elementName: string)`**: Retrieves an element from the repository and performs a standard Playwright click. Automatically waits for the element to be attached, visible, stable, and actionable.
+* **`clickWithoutScrolling(pageName: string, elementName: string)`**: Dispatches a native `click` event directly to the element, bypassing Playwright's default scrolling and intersection observer checks. Highly useful for clicking elements obscured by sticky headers or transparent overlays.
+* **`clickIfPresent(pageName: string, elementName: string)`**: Checks if an element is visible before attempting to click it. Safely skips the action without failing the test if the element is hidden. Great for optional elements like cookie banners.
 * **`clickRandom(pageName: string, elementName: string)`**: Retrieves a random element from a resolved list of locators and clicks it. Useful for clicking random items in a list or grid.
-* **`clickIfPresent(pageName: string, elementName: string)`**: Retrieves an element and clicks it only if it is visible. Prevents test failures on optional UI elements like cookie banners or promotional pop-ups.
-* **`fill(pageName: string, elementName: string, text: string)`**: Retrieves an input field and fills it with the provided text, replacing any existing value.
-* **`uploadFile(pageName: string, elementName: string, filePath: string)`**: Retrieves an `<input type="file">` and uploads the file from the provided local `filePath`.
-* **`selectDropdown(pageName: string, elementName: string, options?: DropdownSelectOptions)`**: Interacts with `<select>` dropdown elements. Returns the exact `value` attribute of the selected option. Accepts:
-* `{ type: 'random' }` *(Default)* - Selects a random, non-disabled option with a valid value.
-* `{ type: 'value', value: 'string' }` - Selects by exact value.
-* `{ type: 'index', index: 1 }` - Selects by index.
+* **`hover(pageName: string, elementName: string)`**: Retrieves an element and hovers over it. Useful for triggering dropdowns or tooltips.
+* **`scrollIntoView(pageName: string, elementName: string)`**: Retrieves an element and smoothly scrolls it into the viewport if it is not already visible.
+* **`dragAndDrop(pageName: string, elementName: string, options: DragAndDropOptions)`**: Drags an element to a specified destination. Supports dropping onto another element (`{ target: Locator }`), dragging by coordinates (`{ xOffset: number, yOffset: number }`), or dropping onto a target at a specific offset.
+* **`dragAndDropListedElement(pageName: string, elementName: string, elementText: string, options: DragAndDropOptions)`**: Finds a specific element by its text from a list of elements and drags it to a specified destination based on the provided options.
+* **`fill(pageName: string, elementName: string, text: string)`**: Clears any existing value in the target input field and types the provided text.
+* **`uploadFile(pageName: string, elementName: string, filePath: string)`**: Uploads a local file from the provided `filePath` to an `<input type="file">` element.
+* **`selectDropdown(pageName: string, elementName: string, options?: DropdownSelectOptions)`**: Selects an option from a `<select>` element and returns its `value`. Defaults to a random, non-disabled option (`{ type: DropdownSelectType.RANDOM }`). Alternatively, select by exact value (`{ type: DropdownSelectType.VALUE, value: '...' }`) or zero-based index (`{ type: DropdownSelectType.INDEX, index: 1 }`).
 
+### 📊 Data Extraction
 
+* **`getText(pageName: string, elementName: string)`**: Safely retrieves and trims the text content of a specified element. Returns an empty string if null.
+* **`getAttribute(pageName: string, elementName: string, attributeName: string)`**: Retrieves the value of a specified HTML attribute (e.g., `href`, `aria-pressed`) from an element. Returns `null` if the attribute doesn't exist.
 
 ### ✅ Verification
 
 * **`verifyPresence(pageName: string, elementName: string)`**: Asserts that a specified element is attached to the DOM and is visible.
 * **`verifyAbsence(pageName: string, elementName: string)`**: Asserts that a specified element is hidden or completely detached from the DOM.
-* **`verifyText(pageName: string, elementName: string, expectedText: string)`**: Asserts that the specified element exactly matches the expected text.
+* **`verifyText(pageName: string, elementName: string, expectedText?: string, options?: TextVerifyOptions)`**: Asserts the text of an element. Provide `expectedText` for an exact match, or pass `{ notEmpty: true }` in the options to simply assert that the dynamically generated text is not blank.
+* **`verifyCount(pageName: string, elementName: string, options: CountVerifyOptions)`**: Asserts the number of elements matching the locator. Accepts a configuration object to evaluate: `{ exact: number }`, `{ greaterThan: number }`, or `{ lessThan: number }`.
 * **`verifyImages(pageName: string, elementName: string, scroll?: boolean)`**: Performs a rigorous verification of one or more images. Asserts visibility, checks for a valid `src` attribute, ensures `naturalWidth > 0`, and evaluates the native browser `decode()` promise. Smoothly scrolls into view by default (`scroll: true`).
 * **`verifyUrlContains(text: string)`**: Asserts that the active browser URL contains the expected substring.
 
+### ⏳ Wait
+
+* **`waitForState(pageName: string, elementName: string, state?: 'visible' | 'attached' | 'hidden' | 'detached')`**: Waits for an element to reach a specific state in the DOM. Defaults to `'visible'`.
+
 ---
 
 ## 🧱 Advanced Usage: Raw Interactions API
@@ -118,7 +166,7 @@ const interactions = new ElementInteractions(page);
 // Pass Playwright Locators directly
 const customLocator = page.locator('button.dynamic-class');
 await interactions.interact.clickWithoutScrolling(customLocator);
-await interactions.verify.state(customLocator, 'enabled');
+await interactions.verify.count(customLocator, { greaterThan: 2 });
 ```
 
-*Note: All core interaction (`interact`), verification (`verify`), and navigation (`Maps`) methods are also available when using `ElementInteractions` directly.*
+*Note: All core interaction (`interact`), verification (`verify`), and navigation (`Maps`) methods are also available when using `ElementInteractions` directly.*

package/dist/enum/Options.d.ts

@@ -0,0 +1,53 @@
+import { Locator } from '@playwright/test';
+/**
+ * Defines the strategy for selecting an option from a dropdown element.
+ */
+export declare enum DropdownSelectType {
+    /** Selects a completely random, non-disabled option with a valid value. */
+    RANDOM = "random",
+    /** Selects an option based on its zero-based index in the dropdown. */
+    INDEX = "index",
+    /** Selects an option based on its exact 'value' attribute. */
+    VALUE = "value"
+}
+/**
+ * Configuration options for the `selectDropdown` method.
+ */
+export interface DropdownSelectOptions {
+    /** The selection strategy to use. Defaults to RANDOM. */
+    type?: DropdownSelectType;
+    /** The specific value attribute to select (Required if type is VALUE). */
+    value?: string;
+    /** The index of the option to select (Required if type is INDEX). */
+    index?: number;
+}
+/**
+ * Configuration options for the `text` verification method.
+ */
+export interface TextVerifyOptions {
+    /** If true, asserts that the element has text content, ignoring 'expectedText' */
+    notEmpty?: boolean;
+}
+/**
+ * Configuration options for the `count` verification method.
+ */
+export interface CountVerifyOptions {
+    /** Asserts that the element count exactly matches this value */
+    exactly?: number;
+    /** Asserts that the element count is strictly greater than this value */
+    greaterThan?: number;
+    /** Asserts that the element count is strictly less than this value */
+    lessThan?: number;
+}
+/**
+ * Configuration options for the `dragAndDrop` method.
+ * You must provide either a `targetLocator` OR both `xOffset` and `yOffset`.
+ */
+export interface DragAndDropOptions {
+    /** The destination element to drop the dragged element onto. */
+    target?: Locator;
+    /** The horizontal offset from the center of the element (positive moves right). */
+    xOffset?: number;
+    /** The vertical offset from the center of the element (positive moves down). */
+    yOffset?: number;
+}

package/dist/enum/Options.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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 = {}));

package/dist/index.d.ts

@@ -1,2 +1,9 @@
-export { ElementInteractions } from './ElementInteractions';
+export * from './enum/Options';
+export { Navigation } from './interactions/Navigation';
+export { Verifications } from './interactions/Verification';
+export { Interactions } from './interactions/Interaction';
+export { Extractions } from './interactions/Extraction';
+export { DateUtilities } from './utils/DateUtilities';
+export { Utils } from './utils/ElementUtilities';
+export { ElementInteractions } from './interactions/facade/ElementInteractions';
 export { Steps } from './steps/CommonSteps';

package/dist/index.js

@@ -1,7 +1,39 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Steps = exports.ElementInteractions = void 0;
-var ElementInteractions_1 = require("./ElementInteractions");
+exports.Steps = exports.ElementInteractions = exports.Utils = exports.DateUtilities = exports.Extractions = exports.Interactions = exports.Verifications = exports.Navigation = void 0;
+// Enums
+__exportStar(require("./enum/Options"), exports);
+// Supporting Action Classes
+var Navigation_1 = require("./interactions/Navigation");
+Object.defineProperty(exports, "Navigation", { enumerable: true, get: function () { return Navigation_1.Navigation; } });
+var Verification_1 = require("./interactions/Verification");
+Object.defineProperty(exports, "Verifications", { enumerable: true, get: function () { return Verification_1.Verifications; } });
+var Interaction_1 = require("./interactions/Interaction");
+Object.defineProperty(exports, "Interactions", { enumerable: true, get: function () { return Interaction_1.Interactions; } });
+var Extraction_1 = require("./interactions/Extraction");
+Object.defineProperty(exports, "Extractions", { enumerable: true, get: function () { return Extraction_1.Extractions; } });
+// Utilities
+var DateUtilities_1 = require("./utils/DateUtilities");
+Object.defineProperty(exports, "DateUtilities", { enumerable: true, get: function () { return DateUtilities_1.DateUtilities; } });
+var ElementUtilities_1 = require("./utils/ElementUtilities");
+Object.defineProperty(exports, "Utils", { enumerable: true, get: function () { return ElementUtilities_1.Utils; } });
+// Element Interactions Facade
+var ElementInteractions_1 = require("./interactions/facade/ElementInteractions");
 Object.defineProperty(exports, "ElementInteractions", { enumerable: true, get: function () { return ElementInteractions_1.ElementInteractions; } });
+// Test Steps Facade
 var CommonSteps_1 = require("./steps/CommonSteps");
 Object.defineProperty(exports, "Steps", { enumerable: true, get: function () { return CommonSteps_1.Steps; } });

package/dist/interactions/Extraction.d.ts

@@ -0,0 +1,25 @@
+import { Page, Locator } from '@playwright/test';
+export declare class Extractions {
+    private page;
+    private ELEMENT_TIMEOUT;
+    private utils;
+    /**
+     * Initializes the Extractions class.
+     * @param page - The current Playwright Page object.
+     * @param timeout - Optional override for the default element timeout.
+     */
+    constructor(page: Page, timeout?: number);
+    /**
+     * Safely retrieves and trims the text content of an element.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @returns The trimmed string, or an empty string if null.
+     */
+    getText(locator: Locator): Promise<string | null>;
+    /**
+     * Retrieves the value of a specified attribute (e.g., 'href', 'aria-pressed').
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param attributeName - The name of the attribute to retrieve.
+     * @returns The attribute value as a string, or null if it doesn't exist.
+     */
+    getAttribute(locator: Locator, attributeName: string): Promise<string | null>;
+}

package/dist/interactions/Extraction.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Extractions = void 0;
+const ElementUtilities_1 = require("../utils/ElementUtilities");
+class Extractions {
+    page;
+    ELEMENT_TIMEOUT;
+    utils;
+    /**
+     * Initializes the Extractions class.
+     * @param page - The current Playwright Page object.
+     * @param timeout - Optional override for the default element timeout.
+     */
+    constructor(page, timeout = 30000) {
+        this.page = page;
+        this.ELEMENT_TIMEOUT = timeout;
+        this.utils = new ElementUtilities_1.Utils(this.ELEMENT_TIMEOUT);
+    }
+    /**
+     * Safely retrieves and trims the text content of an element.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @returns The trimmed string, or an empty string if null.
+     */
+    async getText(locator) {
+        await this.utils.waitForState(locator, 'attached');
+        const text = await locator.textContent({ timeout: this.ELEMENT_TIMEOUT });
+        return text?.trim() ?? null;
+    }
+    /**
+     * Retrieves the value of a specified attribute (e.g., 'href', 'aria-pressed').
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param attributeName - The name of the attribute to retrieve.
+     * @returns The attribute value as a string, or null if it doesn't exist.
+     */
+    async getAttribute(locator, attributeName) {
+        await this.utils.waitForState(locator, 'attached');
+        return await locator.getAttribute(attributeName, { timeout: this.ELEMENT_TIMEOUT });
+    }
+}
+exports.Extractions = Extractions;

package/dist/interactions/Interaction.d.ts

@@ -1,26 +1,5 @@
 import { Page, Locator } from '@playwright/test';
-/**
- * Defines the strategy for selecting an option from a dropdown element.
- */
-export declare enum DropdownSelectType {
-    /** Selects a completely random, non-disabled option with a valid value. */
-    RANDOM = "random",
-    /** Selects an option based on its zero-based index in the dropdown. */
-    INDEX = "index",
-    /** Selects an option based on its exact 'value' attribute. */
-    VALUE = "value"
-}
-/**
- * Configuration options for the `selectDropdown` method.
- */
-export interface DropdownSelectOptions {
-    /** The selection strategy to use. Defaults to RANDOM. */
-    type?: DropdownSelectType;
-    /** The specific value attribute to select (Required if type is VALUE). */
-    value?: string;
-    /** The index of the option to select (Required if type is INDEX). */
-    index?: number;
-}
+import { DropdownSelectOptions, DragAndDropOptions } from '../enum/Options';
 /**
  * The `Interactions` class provides a robust set of methods for interacting
  * with DOM elements via Playwright Locators. It abstracts away common boilerplate
@@ -28,11 +7,14 @@ export interface DropdownSelectOptions {
  */
 export declare class Interactions {
     private page;
+    private ELEMENT_TIMEOUT;
+    private utils;
     /**
      * Initializes the Interactions 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);
     /**
      * Performs a standard Playwright click on the given locator.
      * Automatically waits for the element to be attached, visible, stable, and actionable.
@@ -68,10 +50,37 @@ export declare class Interactions {
     /**
      * 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.
      */
     selectDropdown(locator: Locator, options?: DropdownSelectOptions): Promise<string>;
+    /**
+     * Hovers over the specified element. Useful for triggering dropdowns or tooltips.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    hover(locator: Locator): Promise<void>;
+    /**
+     * Scrolls the element into view if it is not already visible in the viewport.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    scrollIntoView(locator: Locator): Promise<void>;
+    /**
+    * 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.
+    */
+    dragAndDrop(locator: Locator, options: DragAndDropOptions): Promise<void>;
+    /**
+       * 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.
+       */
+    getByText(baseLocator: Locator, pageName: string, elementName: string, desiredText: string, strict?: boolean): Promise<ReturnType<Page['locator']> | null>;
 }

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;