pw-element-interactions 0.0.4 → 0.0.6

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,122 @@ 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');
+});
+```
+
+---
+
+## 🔧 Fixtures: Zero-Setup Tests (Recommended)
+
+For larger projects, manually initializing `repo` and `steps` inside every test quickly becomes repetitive. `pw-element-interactions` ships a `baseFixture` factory that injects all core dependencies automatically via Playwright's fixture system.
+
+### What's included
+
+| Fixture | Type | Description |
+|---|---|---|
+| `steps` | `Steps` | The full Steps API, ready to use |
+| `repo` | `ElementRepository` | Direct repository access for advanced locator queries |
+| `interactions` | `ElementInteractions` | Raw interactions API for custom locators |
+| `contextStore` | `ContextStore` | Shared in-memory store for passing data between steps |
+
+### 1. Create your fixture file
+
+Call `baseFixture` once, passing your own `test` base and the path to your locator repository:
+
+```ts
+// tests/fixtures/base.ts
+import { test as base, expect } from '@playwright/test';
+import { baseFixture } from 'pw-element-interactions';
+
+export const test = baseFixture(base, 'tests/data/page-repository.json');
+export { expect };
+```
+
+### 2. Use fixtures in your tests
+
+Import `test` from your fixture file. All four fixtures are available as named parameters — no setup code required:
+
+```ts
+// tests/checkout.spec.ts
+import { test, expect } from '../fixtures/base';
+import { DropdownSelectType } from 'pw-element-interactions';
+
+test('Complete checkout flow', async ({ steps }) => {
+  await steps.navigateTo('/');
+  await steps.click('HomePage', 'category-accessories');
+  await steps.clickRandom('AccessoriesPage', 'product-cards');
+  await steps.verifyUrlContains('/product/');
+
+  const selectedSize = await steps.selectDropdown('ProductDetailsPage', 'size-selector', {
+    type: DropdownSelectType.RANDOM,
+  });
+
+  await steps.verifyImages('ProductDetailsPage', 'gallery-images');
+  await steps.click('ProductDetailsPage', 'add-to-cart-button');
+  await steps.waitForState('CheckoutPage', 'confirmation-modal', 'visible');
+});
+```
+
+### 3. Access `repo` directly when needed
+
+For advanced queries like resolving a locator by visible text, destructure `repo` alongside `steps`:
+
+```ts
+test('Navigate to Forms category', async ({ page, repo, steps }) => {
+  await steps.navigateTo('/');
+
+  const formsLink = await repo.getByText(page, 'HomePage', 'categories', 'Forms');
+  await formsLink?.click();
+
+  await steps.verifyAbsence('HomePage', 'categories');
+});
+```
+
+### 4. Extend with your own fixtures
+
+Because `baseFixture` returns a standard Playwright `test` object, you can chain your own fixtures on top of it cleanly:
+
+```ts
+// tests/fixtures/base.ts
+import { test as base } from '@playwright/test';
+import { baseFixture } from 'pw-element-interactions';
+import { AuthService } from '../services/AuthService';
+
+type MyFixtures = {
+  authService: AuthService;
+};
+
+const testWithBase = baseFixture(base, 'tests/data/page-repository.json');
+
+export const test = testWithBase.extend<MyFixtures>({
+  authService: async ({ page }, use) => {
+    await use(new AuthService(page));
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+All fixtures are then available together in any test:
+
+```ts
+test('Authenticated flow', async ({ steps, authService }) => {
+  await authService.login('user@test.com', 'secret');
+  await steps.verifyUrlContains('/dashboard');
 });
 ```
 
@@ -78,31 +218,43 @@ The `Steps` class automatically handles fetching the Playwright `Locator` using
 
 ### 🧭 Navigation
 
-* **`MapsTo(url: string)`**: Navigates the browser to the specified absolute or relative URL.
+* **`navigateTo(url: string)`**: Navigates the browser to the specified absolute or relative URL.
 * **`refresh()`**: Reloads the current page.
+* **`backOrForward(direction: 'BACKWARDS' | 'FORWARDS')`**: Navigates the browser history stack either backwards or forwards. Mirrors the behavior of the browser's native Back and Forward buttons.
+* **`setViewport(width: number, height: number)`**: Resizes the browser viewport to the specified pixel dimensions. Useful for simulating different device screen sizes or responsive breakpoints.
 
 ### 🖱️ 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 +270,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 (`navigate`) 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/fixture/BaseFixture.d.ts

@@ -0,0 +1,13 @@
+import { ElementInteractions } from '../interactions/facade/ElementInteractions';
+import { ContextStore } from '@civitas-cerebrum/context-store';
+import { ElementRepository } from 'pw-element-repository';
+import { test as base } from '@playwright/test';
+import { Steps } from '../steps/CommonSteps';
+type StepFixture = {
+    interactions: ElementInteractions;
+    contextStore: ContextStore;
+    repo: ElementRepository;
+    steps: Steps;
+};
+export declare function baseFixture<T extends {}>(baseTest: ReturnType<typeof base.extend<T>>, locatorPath: string): import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions & StepFixture, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+export {};

package/dist/fixture/BaseFixture.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baseFixture = baseFixture;
+const ElementInteractions_1 = require("../interactions/facade/ElementInteractions");
+const context_store_1 = require("@civitas-cerebrum/context-store");
+const pw_element_repository_1 = require("pw-element-repository");
+const CommonSteps_1 = require("../steps/CommonSteps");
+function baseFixture(baseTest, locatorPath) {
+    return baseTest.extend({
+        repo: async ({}, use) => {
+            await use(new pw_element_repository_1.ElementRepository(locatorPath));
+        },
+        steps: async ({ page }, use) => {
+            const repo = new pw_element_repository_1.ElementRepository(locatorPath);
+            await use(new CommonSteps_1.Steps(page, repo));
+        },
+        interactions: async ({ page }, use) => {
+            await use(new ElementInteractions_1.ElementInteractions(page));
+        },
+        contextStore: async ({}, use) => {
+            await use(new context_store_1.ContextStore());
+        },
+    });
+}

package/dist/index.d.ts

@@ -1,6 +1,9 @@
-export { ElementInteractions } from './ElementInteractions';
-export { Interactions, DropdownSelectType, DropdownSelectOptions } from './interactions/Interaction';
+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,21 +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.DateUtilities = exports.Verifications = exports.Navigation = exports.DropdownSelectType = exports.Interactions = exports.ElementInteractions = void 0;
-// Main Entry Point (The Facade)
-var ElementInteractions_1 = require("./ElementInteractions");
-Object.defineProperty(exports, "ElementInteractions", { enumerable: true, get: function () { return ElementInteractions_1.ElementInteractions; } });
-// Interaction logic and associated Types/Enums
-var Interaction_1 = require("./interactions/Interaction");
-Object.defineProperty(exports, "Interactions", { enumerable: true, get: function () { return Interaction_1.Interactions; } });
-Object.defineProperty(exports, "DropdownSelectType", { enumerable: true, get: function () { return Interaction_1.DropdownSelectType; } });
+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"); // Adjust path if necessary
+var DateUtilities_1 = require("./utils/DateUtilities");
 Object.defineProperty(exports, "DateUtilities", { enumerable: true, get: function () { return DateUtilities_1.DateUtilities; } });
-// Test Steps / Page Objects
+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>;
 }