pw-element-interactions 0.0.3 → 0.0.5

package/dist/steps/CommonSteps.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Steps = void 0;
-const ElementInteractions_1 = require("../ElementInteractions");
+const ElementInteractions_1 = require("../interactions/facade/ElementInteractions");
 /**
  * The `Steps` class serves as a unified Facade for test orchestration.
  * It combines element acquisition (via `pw-element-repository`) with
@@ -13,26 +13,31 @@ class Steps {
     repo;
     interact;
     navigate;
+    extract;
     verify;
+    utils;
     /**
      * Initializes the Steps class with the required Playwright page and element repository.
-     * * @param page - The current Playwright Page object.
+     * @param page - The current Playwright Page object.
      * @param repo - An initialized instance of `ElementRepository` containing your locators.
+     * @param timeout - Optional global timeout override (in milliseconds).
      */
-    constructor(page, repo) {
+    constructor(page, repo, timeout) {
         this.page = page;
         this.repo = repo;
-        const interactions = new ElementInteractions_1.ElementInteractions(page);
+        const interactions = new ElementInteractions_1.ElementInteractions(page, timeout);
         this.interact = interactions.interact;
         this.navigate = interactions.navigate;
+        this.extract = interactions.extract;
         this.verify = interactions.verify;
+        this.utils = interactions.utils;
     }
     // ==========================================
     // 🧭 NAVIGATION STEPS
     // ==========================================
     /**
      * Navigates the browser to the specified URL.
-     * * @param url - The absolute or relative URL to navigate to.
+     * @param url - The absolute or relative URL to navigate to.
      */
     async navigateTo(url) {
         console.log(`[Step] -> Navigating to URL: "${url}"`);
@@ -50,7 +55,7 @@ class Steps {
     // ==========================================
     /**
      * Retrieves an element from the repository and performs a standard click.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      */
     async click(pageName, elementName) {
@@ -58,10 +63,21 @@ class Steps {
         const locator = await this.repo.get(this.page, pageName, elementName);
         await this.interact.click(locator);
     }
+    /**
+     * Retrieves an element and dispatches a native 'click' event directly to it.
+     * Bypasses default scrolling and intersection checks. Useful for obscured elements.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     */
+    async clickWithoutScrolling(pageName, elementName) {
+        console.log(`[Step] -> Clicking (no scroll) on '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.clickWithoutScrolling(locator);
+    }
     /**
      * Retrieves a random element from a resolved list of locators and clicks it.
      * Useful for clicking random items in a list or grid (e.g., product cards).
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository representing multiple elements.
      */
     async clickRandom(pageName, elementName) {
@@ -72,7 +88,7 @@ class Steps {
     /**
      * Retrieves an element and clicks it only if it is visible.
      * Prevents test failures on optional elements like cookie banners or promotional pop-ups.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      */
     async clickIfPresent(pageName, elementName) {
@@ -80,9 +96,29 @@ class Steps {
         const locator = await this.repo.get(this.page, pageName, elementName);
         await this.interact.clickIfPresent(locator);
     }
+    /**
+     * Retrieves an element and hovers over it. Useful for triggering dropdowns or tooltips.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     */
+    async hover(pageName, elementName) {
+        console.log(`[Step] -> Hovering over '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.hover(locator);
+    }
+    /**
+     * Retrieves an element and scrolls it into view if it is not already visible.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     */
+    async scrollIntoView(pageName, elementName) {
+        console.log(`[Step] -> Scrolling '${elementName}' in '${pageName}' into view`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.scrollIntoView(locator);
+    }
     /**
      * Retrieves an input field and fills it with the provided text, replacing any existing value.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      * @param text - The text to type into the input field.
      */
@@ -93,7 +129,7 @@ class Steps {
     }
     /**
      * Retrieves an input element of type `file` and sets its files.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      * @param filePath - The local file path of the file to be uploaded.
      */
@@ -105,7 +141,7 @@ class Steps {
     /**
      * Retrieves a `<select>` dropdown element and selects an option based on the provided strategy.
      * Defaults to selecting a random, non-disabled option if no strategy is specified.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      * @param options - Configuration specifying whether to select by 'random', 'index', or 'value'.
      * @returns The exact value attribute of the selected option.
@@ -116,12 +152,60 @@ class Steps {
         const locator = await this.repo.get(this.page, pageName, elementName);
         return await this.interact.selectDropdown(locator, options);
     }
+    /**
+     * Drags an element either to a specified target element, a target element with an offset, or by a coordinate offset.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository (the element to drag).
+     * @param options - Configuration specifying a 'targetLocator', offsets, or both.
+     */
+    async dragAndDrop(pageName, elementName, options) {
+        console.log(`[Step] -> Dragging and dropping '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.dragAndDrop(locator, options);
+    }
+    /**
+     * Drags an element either to a specified target element, a target element with an offset, or by a coordinate offset.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository (the element to drag).
+     * @param options - Configuration specifying a 'targetLocator', offsets, or both.
+     */
+    async dragAndDropListedElement(pageName, elementName, elementText, options) {
+        console.log(`[Step] -> Dragging and dropping '${elementText}' in '${pageName}'`);
+        const locator = await this.repo.getByText(this.page, pageName, elementName, elementText);
+        await this.interact.dragAndDrop(locator, options);
+    }
+    // ==========================================
+    // 📊 DATA EXTRACTION STEPS
+    // ==========================================
+    /**
+     * Safely retrieves and trims the text content of a specified element.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     * @returns The trimmed string, or an empty string if null.
+     */
+    async getText(pageName, elementName) {
+        console.log(`[Step] -> Getting text from '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        return await this.extract.getText(locator);
+    }
+    /**
+     * Retrieves the value of a specified attribute (e.g., 'href', 'aria-pressed') from an element.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     * @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(pageName, elementName, attributeName) {
+        console.log(`[Step] -> Getting attribute '${attributeName}' from '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        return await this.extract.getAttribute(locator, attributeName);
+    }
     // ==========================================
     // ✅ VERIFICATION STEPS
     // ==========================================
     /**
      * Asserts that a specified element is attached to the DOM and is visible.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      */
     async verifyPresence(pageName, elementName) {
@@ -131,30 +215,43 @@ class Steps {
     }
     /**
      * Asserts that a specified element is hidden or completely detached from the DOM.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      */
     async verifyAbsence(pageName, elementName) {
         console.log(`[Step] -> Verifying absence of '${elementName}' in '${pageName}'`);
+        const selector = await this.repo.getSelector(pageName, elementName);
+        await this.verify.absence(selector);
+    }
+    /**
+     * Asserts that the specified element exactly matches the expected text, or optionally checks if it is not empty.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     * @param expectedText - The exact string expected inside the element (optional if checking 'notEmpty').
+     * @param options - Configuration to alter the verification behavior.
+     */
+    async verifyText(pageName, elementName, expectedText, options) {
+        const logDetail = options?.notEmpty ? `is not empty` : `matches: "${expectedText}"`;
+        console.log(`[Step] -> Verifying text of '${elementName}' in '${pageName}' ${logDetail}`);
         const locator = await this.repo.get(this.page, pageName, elementName);
-        await this.verify.absence(locator);
+        await this.verify.text(locator, expectedText, options);
     }
     /**
-     * Asserts that the specified element exactly matches the expected text.
-     * * @param pageName - The page or component grouping name in your repository.
+     * Asserts the number of elements matching the locator based on the provided conditions.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
-     * @param expectedText - The exact string expected inside the element.
+     * @param options - Configuration specifying 'exact', 'greaterThan', or 'lessThan' logic.
      */
-    async verifyText(pageName, elementName, expectedText) {
-        console.log(`[Step] -> Verifying text of '${elementName}' in '${pageName}' matches: "${expectedText}"`);
+    async verifyCount(pageName, elementName, options) {
+        console.log(`[Step] -> Verifying count for '${elementName}' in '${pageName}' with options: ${JSON.stringify(options)}`);
         const locator = await this.repo.get(this.page, pageName, elementName);
-        await this.verify.text(locator, expectedText);
+        await this.verify.count(locator, options);
     }
     /**
      * Performs a rigorous verification of one or more images.
      * Asserts visibility, checks for a valid 'src' attribute, ensures a positive 'naturalWidth',
      * and evaluates the native browser `decode()` promise to ensure the image isn't broken.
-     * * @param pageName - The page or component grouping name in your repository.
+     * @param pageName - The page or component grouping name in your repository.
      * @param elementName - The specific element name in your repository.
      * @param scroll - Whether to smoothly scroll the image(s) into view before verifying (default: true).
      */
@@ -165,11 +262,22 @@ class Steps {
     }
     /**
      * Asserts that the current browser URL contains the expected substring.
-     * * @param text - The substring expected to be present within the active URL.
+     * @param text - The substring expected to be present within the active URL.
      */
     async verifyUrlContains(text) {
         console.log(`[Step] -> Verifying current URL contains: "${text}"`);
         await this.verify.urlContains(text);
     }
+    /**
+     * Waits for an element to reach a specific state in the DOM.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     * @param state - The state to wait for: 'visible' | 'attached' | 'hidden' | 'detached'. Defaults to 'visible'.
+     */
+    async waitForState(pageName, elementName, state = 'visible') {
+        console.log(`[Step] -> Waiting for '${elementName}' in '${pageName}' to be '${state}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.utils.waitForState(locator, state);
+    }
 }
 exports.Steps = Steps;

package/dist/utils/DateUtilities.js

@@ -7,19 +7,15 @@ class DateUtilities {
      * Mirrors the Java DateUtilities.reformatDateString method.
      */
     static reformatDateString(rawDate, format) {
-        // Parse the raw date string into a JS Date object
         const date = new Date(rawDate);
-        // Guard clause: Check if the date is valid before formatting
         if (isNaN(date.getTime())) {
             throw new Error(`Invalid date string provided: ${rawDate}`);
         }
         const yyyy = date.getFullYear().toString();
         const MM = String(date.getMonth() + 1).padStart(2, '0');
         const dd = String(date.getDate()).padStart(2, '0');
-        // Unpadded variables for single-digit months/days
         const M = String(date.getMonth() + 1);
         const d = String(date.getDate());
-        // You can expand this switch/if statement as your framework's formatting needs grow
         switch (format) {
             case 'yyyy-MM-dd':
                 return `${yyyy}-${MM}-${dd}`;
@@ -28,7 +24,7 @@ class DateUtilities {
             case 'dd MMM yyyy':
                 const monthNames = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
                 return `${dd} ${monthNames[date.getMonth()]} ${yyyy}`;
-            case 'yyyy-M-d': // 💡 New format matching the modal's output
+            case 'yyyy-M-d':
                 return `${yyyy}-${M}-${d}`;
             default:
                 console.warn(`Format ${format} not fully supported, returning ISO date.`);

package/dist/utils/ElementUtilities.d.ts

@@ -0,0 +1,22 @@
+import { Locator } from '@playwright/test';
+/**
+ * Utility class to handle standardized waiting logic across the framework.
+ */
+export declare class Utils {
+    private readonly timeout;
+    /**
+     * @param timeout - Optional timeout in milliseconds. Defaults to 30000.
+     */
+    constructor(timeout?: number);
+    /**
+     * Returns the current timeout value.
+     */
+    getTimeout(): number;
+    /**
+     * Standardized wait logic for element states.
+     * Does not fail the test on timeout; logs a warning instead.
+     * @param locator - The Playwright Locator.
+     * @param state - The state to wait for.
+     */
+    waitForState(locator: Locator, state?: 'visible' | 'attached' | 'hidden' | 'detached'): Promise<void>;
+}

package/dist/utils/ElementUtilities.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Utils = void 0;
+/**
+ * Utility class to handle standardized waiting logic across the framework.
+ */
+class Utils {
+    timeout;
+    /**
+     * @param timeout - Optional timeout in milliseconds. Defaults to 30000.
+     */
+    constructor(timeout = 30000) {
+        this.timeout = timeout;
+    }
+    /**
+     * Returns the current timeout value.
+     */
+    getTimeout() {
+        return this.timeout;
+    }
+    /**
+     * Standardized wait logic for element states.
+     * Does not fail the test on timeout; logs a warning instead.
+     * @param locator - The Playwright Locator.
+     * @param state - The state to wait for.
+     */
+    async waitForState(locator, state = 'visible') {
+        try {
+            await locator.waitFor({ state, timeout: this.timeout });
+        }
+        catch (error) {
+            console.warn(`[Warning] -> Element failed to reach state '${state}' within ${this.timeout}ms. Proceeding...`);
+        }
+    }
+}
+exports.Utils = Utils;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-element-interactions",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "description": "A robust, readable interaction and assertion Facade for Playwright. Abstract away boilerplate into semantic, English-like methods, making your test automation framework cleaner, easier to maintain, and accessible to non-developers.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +18,7 @@
     "pw-element-repository": ">=0.0.3"
   },
   "devDependencies": {
+    "@civitas-cerebrum/context-store": "^0.0.2",
     "@playwright/test": "^1.58.2",
     "@types/node": "^20.0.0",
     "pw-element-repository": "^0.0.3",

package/dist/ElementInteractions.d.ts

@@ -1,10 +0,0 @@
-import { Page } from '@playwright/test';
-import { Interactions } from './interactions/Interaction';
-import { Navigation } from './interactions/Navigation';
-import { Verifications } from './interactions/Verification';
-export declare class ElementInteractions {
-    navigate: Navigation;
-    interact: Interactions;
-    verify: Verifications;
-    constructor(page: Page);
-}

package/dist/ElementInteractions.js

@@ -1,17 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ElementInteractions = void 0;
-const Interaction_1 = require("./interactions/Interaction");
-const Navigation_1 = require("./interactions/Navigation");
-const Verification_1 = require("./interactions/Verification");
-class ElementInteractions {
-    navigate;
-    interact;
-    verify;
-    constructor(page) {
-        this.navigate = new Navigation_1.Navigation(page);
-        this.interact = new Interaction_1.Interactions(page);
-        this.verify = new Verification_1.Verifications(page);
-    }
-}
-exports.ElementInteractions = ElementInteractions;