pw-element-interactions 0.0.1

package/README.md

@@ -0,0 +1,116 @@
+# Playwright Element Interactions
+
+[![NPM Version](https://img.shields.io/npm/v/pw-element-interactions?color=rgb(88%2C%20171%2C%2070))](https://www.npmjs.com/package/pw-element-interactions)
+
+A robust set of Playwright steps for readable interaction and assertions.
+
+`pw-element-interactions` pairs perfectly with `pw-element-repository` to achieve a fully decoupled test automation architecture. By separating **Element Acquisition** from **Element Interaction**, your test scripts become highly readable, easily maintainable, and completely free of raw locators.
+
+### ✨ The Unified Steps API
+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.
+
+---
+
+## 📦 Installation
+
+Install the package via your preferred package manager:
+
+``` bash
+npm i pw-element-interactions
+```
+
+**Peer Dependencies:**
+This package requires `@playwright/test` to be installed in your project. If you are using the `Steps` API, you will also need `pw-element-repository`.
+
+---
+
+## 🚀 What is it good for?
+
+* **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`).
+* **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).
+
+---
+
+## 💻 Usage: The `Steps` API (Recommended)
+
+Initialize the `Steps` class by passing the current Playwright `page` object and your `ElementRepository` instance. 
+
+### Example Scenario
+
+``` ts
+import { test } from '@playwright/test';
+import { ElementRepository } from 'pw-element-repository';
+import { Steps } from 'pw-element-interactions';
+
+test('Add random product and verify image gallery', async ({ page }) => {
+  // 1. Initialize Repository & Steps
+  const repo = new ElementRepository('tests/data/locators.json');
+  const steps = new Steps(page, repo);
+
+  // 2. Navigate
+  await steps.navigateTo('/');
+
+  // 3. Direct Interaction (Fetches and clicks in one line)
+  await steps.click('HomePage', 'category-accessories');
+
+  // 4. Randomized Acquisition & Action
+  await steps.clickRandom('AccessoriesPage', 'product-cards');
+  await steps.verifyUrlContains('/product/');
+
+  // 5. Smart Dropdown Interaction
+  const selectedSize = await steps.selectDropdown('ProductDetailsPage', 'size-selector', { type: 'random' });
+  console.log(`Selected size: ${selectedSize}`);
+
+  // 6. Advanced Image Verification
+  await steps.verifyImages('ProductDetailsPage', 'gallery-images');
+});
+```
+
+---
+
+## 🛠️ API Reference: `Steps`
+
+The `Steps` class automatically handles fetching the Playwright `Locator` using your `pageName` and `elementName` keys from the repository.
+
+### 🧭 Navigation Steps
+* **`MapsTo(url)`**: Navigates the browser to the specified URL.
+* **`refresh()`**: Reloads the current page.
+
+### 🖱️ Interaction Steps
+* **`click(pageName, elementName)`**: Standard click. Automatically waits for actionability.
+* **`clickRandom(pageName, elementName)`**: Resolves a list of elements and clicks a random one.
+* **`clickIfPresent(pageName, elementName)`**: Safely clicks an element only if it is visible. Prevents failures on optional UI elements like cookie banners.
+* **`fill(pageName, elementName, text)`**: Clears the input and types the provided text.
+* **`uploadFile(pageName, elementName, filePath)`**: Uploads a local file to a specific `<input type="file">`.
+* **`selectDropdown(pageName, elementName, options?)`**: Interacts with `<select>` elements. Returns the selected value. 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.
+
+### ✅ Verification Steps
+* **`verifyPresence(pageName, elementName)`**: Asserts the element is visible in the DOM.
+* **`verifyAbsence(pageName, elementName)`**: Asserts the element is hidden or detached.
+* **`verifyText(pageName, elementName, expectedText)`**: Asserts exact text match.
+* **`verifyImages(pageName, elementName, scroll?)`**: Robust image verification. Scrolls into view, checks visibility, asserts `src`, checks `naturalWidth > 0`, and evaluates the native `HTMLImageElement.decode()` promise.
+* **`verifyUrlContains(text)`**: Asserts the active browser URL contains a specific substring.
+
+---
+
+## 🧱 Advanced Usage: Raw Interactions API
+
+If you need to bypass the repository or interact with custom locators dynamically generated in your tests, you can use the underlying `ElementInteractions` class directly.
+``` ts
+import { ElementInteractions } from 'pw-element-interactions';
+
+// Initialize
+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');
+```
+*Note: All core interaction (`interact`), verification (`verify`), and navigation (`Maps`) methods are available when using `ElementInteractions` directly.*

package/dist/ElementInteractions.d.ts

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,17 @@
+"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;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { ElementInteractions } from './ElementInteractions';

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ElementInteractions = void 0;
+var ElementInteractions_1 = require("./ElementInteractions");
+Object.defineProperty(exports, "ElementInteractions", { enumerable: true, get: function () { return ElementInteractions_1.ElementInteractions; } });

package/dist/interactions/Interaction.d.ts

@@ -0,0 +1,77 @@
+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;
+}
+/**
+ * The `Interactions` class provides a robust set of methods for interacting
+ * with DOM elements via Playwright Locators. It abstracts away common boilerplate
+ * and handles edge cases like overlapping elements or optional UI components.
+ */
+export declare class Interactions {
+    private page;
+    /**
+     * Initializes the Interactions class.
+     * @param page - The current Playwright Page object.
+     */
+    constructor(page: Page);
+    /**
+     * Performs a standard Playwright click on the given locator.
+     * Automatically waits for the element to be attached, visible, stable, and actionable.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    click(locator: Locator): Promise<void>;
+    /**
+     * Dispatches a native 'click' event directly to the element.
+     * This bypasses Playwright's default scrolling and intersection observer checks.
+     * Highly useful for clicking elements that might be artificially obscured by sticky headers or transparent overlays.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    clickWithoutScrolling(locator: Locator): Promise<void>;
+    /**
+     * Checks if an element is visible before attempting to click it.
+     * If the element is hidden or not in the DOM, it safely skips the action and logs a message
+     * without failing the test. Great for optional elements like cookie banners or promotional pop-ups.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    clickIfPresent(locator: Locator): Promise<void>;
+    /**
+     * Clears any existing value in the target input field and types the provided text.
+     * @param locator - The Playwright Locator pointing to the input element.
+     * @param text - The string to type into the input field.
+     */
+    fill(locator: Locator, text: string): Promise<void>;
+    /**
+     * Uploads a local file to an `<input type="file">` element.
+     * @param locator - The Playwright Locator pointing to the file input element.
+     * @param filePath - The local file system path to the file you want to upload.
+     */
+    uploadFile(locator: Locator, filePath: string): Promise<void>;
+    /**
+     * 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 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>;
+}

package/dist/interactions/Interaction.js

@@ -0,0 +1,116 @@
+"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 = {}));
+/**
+ * The `Interactions` class provides a robust set of methods for interacting
+ * with DOM elements via Playwright Locators. It abstracts away common boilerplate
+ * and handles edge cases like overlapping elements or optional UI components.
+ */
+class Interactions {
+    page;
+    /**
+     * Initializes the Interactions class.
+     * @param page - The current Playwright Page object.
+     */
+    constructor(page) {
+        this.page = page;
+    }
+    /**
+     * Performs a standard Playwright click on the given locator.
+     * Automatically waits for the element to be attached, visible, stable, and actionable.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async click(locator) {
+        await locator.click();
+    }
+    /**
+     * Dispatches a native 'click' event directly to the element.
+     * This bypasses Playwright's default scrolling and intersection observer checks.
+     * Highly useful for clicking elements that might be artificially obscured by sticky headers or transparent overlays.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async clickWithoutScrolling(locator) {
+        await locator.dispatchEvent('click');
+    }
+    /**
+     * Checks if an element is visible before attempting to click it.
+     * If the element is hidden or not in the DOM, it safely skips the action and logs a message
+     * without failing the test. Great for optional elements like cookie banners or promotional pop-ups.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async clickIfPresent(locator) {
+        if (await locator.isVisible()) {
+            await locator.click();
+        }
+        else {
+            console.log(`[Action] -> Locator was not visible. Skipping click.`);
+        }
+    }
+    /**
+     * Clears any existing value in the target input field and types the provided text.
+     * @param locator - The Playwright Locator pointing to the input element.
+     * @param text - The string to type into the input field.
+     */
+    async fill(locator, text) {
+        await locator.fill(text);
+    }
+    /**
+     * Uploads a local file to an `<input type="file">` element.
+     * @param locator - The Playwright Locator pointing to the file input element.
+     * @param filePath - The local file system path to the file you want to upload.
+     */
+    async uploadFile(locator, filePath) {
+        console.log(`[Action] -> Uploading file from path "${filePath}"`);
+        await locator.setInputFiles(filePath);
+    }
+    /**
+     * 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 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) {
+            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 });
+            return selected[0];
+        }
+        if (type === 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 });
+            return selected[0];
+        }
+        const enabledOptions = locator.locator('option:not([disabled]):not([value=""])');
+        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');
+        if (valueToSelect === null) {
+            throw new Error(`[Action] Error -> Option at index ${randomIndex} is missing a "value" attribute.`);
+        }
+        const selected = await locator.selectOption({ value: valueToSelect });
+        return selected[0];
+    }
+}
+exports.Interactions = Interactions;

package/dist/interactions/Navigation.d.ts

@@ -0,0 +1,37 @@
+import { Page } from '@playwright/test';
+/**
+ * The `Navigation` class provides a streamlined interface for managing browser
+ * navigation, history, and viewport settings within Playwright.
+ */
+export declare class Navigation {
+    private page;
+    /**
+     * Initializes the Navigation class.
+     * @param page - The current Playwright Page object.
+     */
+    constructor(page: Page);
+    /**
+     * Navigates the active browser page to the specified URL.
+     * Automatically waits for the page to reach the default 'load' state.
+     * @param url - The absolute or relative URL to navigate to.
+     */
+    toUrl(url: string): Promise<void>;
+    /**
+     * Reloads the current page.
+     * Useful for resetting application state or checking data persistence.
+     */
+    reload(): Promise<void>;
+    /**
+     * Navigates the browser history stack either backwards or forwards.
+     * Mirrors the behavior of the browser's native Back and Forward buttons.
+     * @param direction - The direction to move in history: either 'BACKWARDS' or 'FORWARDS'.
+     */
+    backOrForward(direction: 'BACKWARDS' | 'FORWARDS'): Promise<void>;
+    /**
+     * Resizes the browser viewport to the specified dimensions.
+     * Useful for simulating different device screen sizes or responsive breakpoints.
+     * @param width - The desired width of the viewport in pixels.
+     * @param height - The desired height of the viewport in pixels.
+     */
+    setViewport(width: number, height: number): Promise<void>;
+}

package/dist/interactions/Navigation.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Navigation = void 0;
+/**
+ * The `Navigation` class provides a streamlined interface for managing browser
+ * navigation, history, and viewport settings within Playwright.
+ */
+class Navigation {
+    page;
+    /**
+     * Initializes the Navigation class.
+     * @param page - The current Playwright Page object.
+     */
+    constructor(page) {
+        this.page = page;
+    }
+    /**
+     * Navigates the active browser page to the specified URL.
+     * Automatically waits for the page to reach the default 'load' state.
+     * @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);
+    }
+    /**
+     * Reloads the current page.
+     * Useful for resetting application state or checking data persistence.
+     */
+    async reload() {
+        console.log(`[Navigate] -> Refreshing the current page`);
+        await this.page.reload();
+    }
+    /**
+     * Navigates the browser history stack either backwards or forwards.
+     * Mirrors the behavior of the browser's native Back and Forward buttons.
+     * @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();
+        }
+        else {
+            await this.page.goForward();
+        }
+    }
+    /**
+     * Resizes the browser viewport to the specified dimensions.
+     * Useful for simulating different device screen sizes or responsive breakpoints.
+     * @param width - The desired width of the viewport in pixels.
+     * @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 });
+    }
+}
+exports.Navigation = Navigation;

package/dist/interactions/Verification.d.ts

@@ -0,0 +1,68 @@
+import { Page, Locator } from '@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
+ * (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;
+    /**
+     * Initializes the Verifications class.
+     * @param page - The current Playwright Page object.
+     */
+    constructor(page: Page);
+    /**
+     * Asserts that the specified element's text exactly matches the expected text.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param expectedText - The exact text string expected to be inside the element.
+     */
+    text(locator: Locator, expectedText: string): Promise<void>;
+    /**
+     * Asserts that the specified element contains the expected substring.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param expectedText - The substring expected to be present within the element's text.
+     */
+    textContains(locator: Locator, expectedText: string): Promise<void>;
+    /**
+     * Asserts that the specified element is attached to the DOM and is visible.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    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.
+     */
+    absence(locator: Locator): Promise<void>;
+    /**
+     * Asserts the interactive state of an element (whether it is enabled or disabled).
+     * Useful for checking buttons or input fields.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param state - The expected state: either 'enabled' or 'disabled'.
+     */
+    state(locator: Locator, state: 'enabled' | 'disabled'): Promise<void>;
+    /**
+     * Asserts that the current browser URL contains the expected substring.
+     * Evaluates using a case-insensitive regular expression.
+     * @param text - The substring expected to be present within the active URL.
+     */
+    urlContains(text: string): Promise<void>;
+    /**
+     * Asserts that an element has a specific HTML attribute with an exact value.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param attributeName - The name of the HTML attribute to check (e.g., 'href', 'class', 'alt').
+     * @param expectedValue - The exact expected value of the attribute.
+     */
+    attribute(locator: Locator, attributeName: string, expectedValue: string): Promise<void>;
+    /**
+     * Performs a rigorous, multi-step verification on one or more images.
+     * 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 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>;
+}

package/dist/interactions/Verification.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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
+ * (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;
+    /**
+     * Initializes the Verifications class.
+     * @param page - The current Playwright Page object.
+     */
+    constructor(page) {
+        this.page = page;
+    }
+    /**
+     * Asserts that the specified element's text exactly matches the expected text.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param expectedText - The exact text string expected to be inside the element.
+     */
+    async text(locator, expectedText) {
+        await (0, test_1.expect)(locator).toHaveText(expectedText, { timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+     * Asserts that the specified element contains the expected substring.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param expectedText - The substring expected to be present within the element's text.
+     */
+    async textContains(locator, expectedText) {
+        await (0, test_1.expect)(locator).toContainText(expectedText, { timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+     * Asserts that the specified element is attached to the DOM and is visible.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async presence(locator) {
+        await (0, test_1.expect)(locator).toBeVisible({ timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+     * Asserts that the specified element is either hidden or completely detached from the DOM.
+     * @param locator - The Playwright Locator pointing to the target element.
+     */
+    async absence(locator) {
+        console.log(`[Verify] -> Asserting absence of "${locator}"`);
+        await (0, test_1.expect)(locator).toBeHidden({ timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+     * Asserts the interactive state of an element (whether it is enabled or disabled).
+     * Useful for checking buttons or input fields.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @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 });
+        }
+        else {
+            await (0, test_1.expect)(locator).toBeDisabled({ timeout: this.ELEMENT_TIMEOUT });
+        }
+    }
+    /**
+     * Asserts that the current browser URL contains the expected substring.
+     * Evaluates using a case-insensitive regular expression.
+     * @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 });
+    }
+    /**
+     * Asserts that an element has a specific HTML attribute with an exact value.
+     * @param locator - The Playwright Locator pointing to the target element.
+     * @param attributeName - The name of the HTML attribute to check (e.g., 'href', 'class', 'alt').
+     * @param expectedValue - The exact expected value of the attribute.
+     */
+    async attribute(locator, attributeName, expectedValue) {
+        await (0, test_1.expect)(locator).toHaveAttribute(attributeName, expectedValue, { timeout: this.ELEMENT_TIMEOUT });
+    }
+    /**
+     * Performs a rigorous, multi-step verification on one or more images.
+     * 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 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.
+     */
+    async images(imagesLocator, scroll = true) {
+        const productImages = await imagesLocator.all();
+        if (productImages.length === 0) {
+            throw new Error(`[Verify] -> No images found for '${imagesLocator}'.`);
+        }
+        for (let i = 0; i < productImages.length; i++) {
+            const productImage = productImages[i];
+            if (scroll) {
+                await productImage.scrollIntoViewIfNeeded().catch(() => { });
+            }
+            await (0, test_1.expect)(productImage).toBeVisible({ timeout: this.ELEMENT_TIMEOUT });
+            await (0, test_1.expect)(productImage).toHaveAttribute('src', /.+/, { timeout: this.ELEMENT_TIMEOUT });
+            await (0, test_1.expect)(productImage).not.toHaveJSProperty('naturalWidth', 0, { timeout: this.ELEMENT_TIMEOUT });
+            const isDecoded = await productImage.evaluate(async (img) => {
+                if (!img.src)
+                    return false;
+                try {
+                    await img.decode();
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            });
+            (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}"`);
+    }
+}
+exports.Verifications = Verifications;

package/dist/steps/CommonSteps.d.ts

@@ -0,0 +1,107 @@
+import { Page } from '@playwright/test';
+import { ElementRepository } from 'pw-element-repository';
+import { DropdownSelectOptions } from '../interactions/Interaction';
+/**
+ * The `Steps` class serves as a unified Facade for test orchestration.
+ * It combines element acquisition (via `pw-element-repository`) with
+ * Playwright interactions, navigation, and verifications to keep test files clean,
+ * readable, and free of raw locators.
+ */
+export declare class Steps {
+    private page;
+    private repo;
+    private interact;
+    private navigate;
+    private verify;
+    /**
+     * Initializes the Steps class with the required Playwright page and element repository.
+     * * @param page - The current Playwright Page object.
+     * @param repo - An initialized instance of `ElementRepository` containing your locators.
+     */
+    constructor(page: Page, repo: ElementRepository);
+    /**
+     * Navigates the browser to the specified URL.
+     * * @param url - The absolute or relative URL to navigate to.
+     */
+    navigateTo(url: string): Promise<void>;
+    /**
+     * Reloads the current page.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Retrieves an element from the repository and performs a standard click.
+     * * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     */
+    click(pageName: string, elementName: string): Promise<void>;
+    /**
+     * 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 elementName - The specific element name in your repository representing multiple elements.
+     */
+    clickRandom(pageName: string, elementName: string): Promise<void>;
+    /**
+     * 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 elementName - The specific element name in your repository.
+     */
+    clickIfPresent(pageName: string, elementName: string): Promise<void>;
+    /**
+     * 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 elementName - The specific element name in your repository.
+     * @param text - The text to type into the input field.
+     */
+    fill(pageName: string, elementName: string, text: string): Promise<void>;
+    /**
+     * Retrieves an input element of type `file` and sets its files.
+     * * @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.
+     */
+    uploadFile(pageName: string, elementName: string, filePath: string): Promise<void>;
+    /**
+     * 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 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.
+     */
+    selectDropdown(pageName: string, elementName: string, options?: DropdownSelectOptions): Promise<string>;
+    /**
+     * 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 elementName - The specific element name in your repository.
+     */
+    verifyPresence(pageName: string, elementName: string): Promise<void>;
+    /**
+     * 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 elementName - The specific element name in your repository.
+     */
+    verifyAbsence(pageName: string, elementName: string): Promise<void>;
+    /**
+     * Asserts that the specified element exactly matches the expected text.
+     * * @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.
+     */
+    verifyText(pageName: string, elementName: string, expectedText: string): Promise<void>;
+    /**
+     * 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 elementName - The specific element name in your repository.
+     * @param scroll - Whether to smoothly scroll the image(s) into view before verifying (default: true).
+     */
+    verifyImages(pageName: string, elementName: string, scroll?: boolean): Promise<void>;
+    /**
+     * Asserts that the current browser URL contains the expected substring.
+     * * @param text - The substring expected to be present within the active URL.
+     */
+    verifyUrlContains(text: string): Promise<void>;
+}

package/dist/steps/CommonSteps.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Steps = void 0;
+const ElementInteractions_1 = require("../ElementInteractions");
+/**
+ * The `Steps` class serves as a unified Facade for test orchestration.
+ * It combines element acquisition (via `pw-element-repository`) with
+ * Playwright interactions, navigation, and verifications to keep test files clean,
+ * readable, and free of raw locators.
+ */
+class Steps {
+    page;
+    repo;
+    interact;
+    navigate;
+    verify;
+    /**
+     * Initializes the Steps class with the required Playwright page and element repository.
+     * * @param page - The current Playwright Page object.
+     * @param repo - An initialized instance of `ElementRepository` containing your locators.
+     */
+    constructor(page, repo) {
+        this.page = page;
+        this.repo = repo;
+        const interactions = new ElementInteractions_1.ElementInteractions(page);
+        this.interact = interactions.interact;
+        this.navigate = interactions.navigate;
+        this.verify = interactions.verify;
+    }
+    // ==========================================
+    // 🧭 NAVIGATION STEPS
+    // ==========================================
+    /**
+     * Navigates the browser to the specified URL.
+     * * @param url - The absolute or relative URL to navigate to.
+     */
+    async navigateTo(url) {
+        console.log(`[Step] -> Navigating to URL: "${url}"`);
+        await this.navigate.toUrl(url);
+    }
+    /**
+     * Reloads the current page.
+     */
+    async refresh() {
+        console.log(`[Step] -> Refreshing the current page`);
+        await this.navigate.reload();
+    }
+    // ==========================================
+    // 🖱️ INTERACTION STEPS
+    // ==========================================
+    /**
+     * Retrieves an element from the repository and performs a standard click.
+     * * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     */
+    async click(pageName, elementName) {
+        console.log(`[Step] -> Clicking on '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.click(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 elementName - The specific element name in your repository representing multiple elements.
+     */
+    async clickRandom(pageName, elementName) {
+        console.log(`[Step] -> Clicking a random element from '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.getRandom(this.page, pageName, elementName);
+        await this.interact.click(locator);
+    }
+    /**
+     * 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 elementName - The specific element name in your repository.
+     */
+    async clickIfPresent(pageName, elementName) {
+        console.log(`[Step] -> Clicking on '${elementName}' in '${pageName}' (if present)`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.clickIfPresent(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 elementName - The specific element name in your repository.
+     * @param text - The text to type into the input field.
+     */
+    async fill(pageName, elementName, text) {
+        console.log(`[Step] -> Filling '${elementName}' in '${pageName}' with text: "${text}"`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.fill(locator, text);
+    }
+    /**
+     * Retrieves an input element of type `file` and sets its files.
+     * * @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.
+     */
+    async uploadFile(pageName, elementName, filePath) {
+        console.log(`[Step] -> Uploading file "${filePath}" to '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.uploadFile(locator, filePath);
+    }
+    /**
+     * 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 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.
+     */
+    async selectDropdown(pageName, elementName, options) {
+        const optLog = options ? JSON.stringify(options) : 'default (random)';
+        console.log(`[Step] -> Selecting dropdown option for '${elementName}' in '${pageName}' using options: ${optLog}`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        return await this.interact.selectDropdown(locator, options);
+    }
+    // ==========================================
+    // ✅ 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 elementName - The specific element name in your repository.
+     */
+    async verifyPresence(pageName, elementName) {
+        console.log(`[Step] -> Verifying presence of '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.verify.presence(locator);
+    }
+    /**
+     * 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 elementName - The specific element name in your repository.
+     */
+    async verifyAbsence(pageName, elementName) {
+        console.log(`[Step] -> Verifying absence of '${elementName}' in '${pageName}'`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.verify.absence(locator);
+    }
+    /**
+     * Asserts that the specified element exactly matches the expected text.
+     * * @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.
+     */
+    async verifyText(pageName, elementName, expectedText) {
+        console.log(`[Step] -> Verifying text of '${elementName}' in '${pageName}' matches: "${expectedText}"`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.verify.text(locator, expectedText);
+    }
+    /**
+     * 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 elementName - The specific element name in your repository.
+     * @param scroll - Whether to smoothly scroll the image(s) into view before verifying (default: true).
+     */
+    async verifyImages(pageName, elementName, scroll = true) {
+        console.log(`[Step] -> Verifying images for '${elementName}' in '${pageName}' (Scroll: ${scroll})`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.verify.images(locator, scroll);
+    }
+    /**
+     * Asserts that the current browser URL contains the expected substring.
+     * * @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);
+    }
+}
+exports.Steps = Steps;

package/dist/utils/DateUtilities.d.ts

@@ -0,0 +1,7 @@
+export declare class DateUtilities {
+    /**
+     * Reformats a recognizable date string into a target format.
+     * Mirrors the Java DateUtilities.reformatDateString method.
+     */
+    static reformatDateString(rawDate: string, format: string): string;
+}

package/dist/utils/DateUtilities.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DateUtilities = void 0;
+class DateUtilities {
+    /**
+     * Reformats a recognizable date string into a target format.
+     * 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}`;
+            case 'dd-MM-yyyy':
+                return `${dd}-${MM}-${yyyy}`;
+            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
+                return `${yyyy}-${M}-${d}`;
+            default:
+                console.warn(`Format ${format} not fully supported, returning ISO date.`);
+                return `${yyyy}-${MM}-${dd}`;
+        }
+    }
+}
+exports.DateUtilities = DateUtilities;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "pw-element-interactions",
+  "version": "0.0.1",
+  "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",
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc",
+    "test": "npx playwright test",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@playwright/test": ">=1.0.0",
+    "pw-element-repository": ">=0.0.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.58.2",
+    "@types/node": "^20.0.0",
+    "pw-element-repository": "^0.0.3",
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "playwright",
+    "automation",
+    "interactions",
+    "assertions",
+    "clean-code",
+    "facade-pattern",
+    "test-automation",
+    "steps-api"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Umutayb/pw-element-interactions.git"
+  },
+  "author": "Umut Ay Bora",
+  "license": "MIT"
+}