pw-element-interactions 0.0.8 → 0.1.0

package/README.md

@@ -8,7 +8,7 @@ A robust set of Playwright steps for readable interaction and assertions.
 
 ### ✨ 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.
+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
 
@@ -19,56 +19,82 @@ Because the API is highly semantic and completely decoupled from the DOM, it is
 **Before (Raw Playwright):**
 
 ```ts
-// 1. Hardcode or manage raw locators inside your test
+// 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
+// Explicitly wait for DOM stability and visibility
 await submitBtn.waitFor({ state: 'visible', timeout: 30000 });
 
-// 3. Perform the interaction
+// Perform the interaction
 await submitBtn.click();
 ```
 
-**Now (with pw-element-interactions):**
+**After (pw-element-interactions):**
 
 ```ts
-// 1. Locate, wait, and interact in a single, readable, AI-friendly line
+// Locate, wait, and interact — one line
 await steps.click('CheckoutPage', 'submitButton');
 ```
 
+Because the API is semantic and decoupled from the DOM, it also works exceptionally well with AI coding assistants. Models can generate robust test flows using plain-English strings (`'CheckoutPage'`, `'submitButton'`) without hallucinating CSS selectors or writing flaky interactions.
+
 ---
 
 ## 📦 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`.
+**Peer dependencies:** `@playwright/test` is required. The `Steps` API additionally requires `pw-element-repository`.
 
 ---
 
-## 🚀 What is it good for?
+## ✨ Features
 
-* **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.
+* **Zero locator boilerplate** — The `Steps` API fetches elements and interacts with them in a single call.
+* **Automatic failure screenshots** — `baseFixture` captures a full-page screenshot on every failed test and attaches it to the HTML report.
+* **Standardized waiting** — Built-in methods wait for elements to reach specific DOM states (visible, hidden, attached, detached).
+* **Advanced image verification** — `verifyImages` evaluates actual browser decoding and `naturalWidth`, not just DOM presence.
+* **Smart dropdowns** — Select by value, index, or randomly, with automatic skipping of disabled and empty options.
+* **Flexible assertions** — Verify exact text, non-empty text, URL substrings, or dynamic element counts (greater than, less than, exact).
+* **Drag and drop** — Drag to other elements, to coordinate offsets, or combine both strategies.
 
 ---
 
-## 💻 Usage: The `Steps` API (Recommended)
+## 🗂️ Defining Locators
+
+All selectors live in a page repository JSON file — the single source of truth for element locations. No raw selectors should appear in test code.
+
+```json
+{
+  "pages": [
+    {
+      "name": "HomePage",
+      "elements": [
+        {
+          "elementName": "submitButton",
+          "selector": {
+            "css": "button[data-test='submit']"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Each selector object supports `css`, `xpath`, `id`, or `text` as the locator strategy.
+
+**Naming conventions:**
+- `name` — PascalCase page identifier, e.g. `CheckoutPage`, `ProductDetailsPage`
+- `elementName` — camelCase element identifier, e.g. `submitButton`, `galleryImages`
 
-Initialize the `Steps` class by passing the current Playwright `page` object and your `ElementRepository` instance.
+---
+
+## 💻 Usage: The `Steps` API (Recommended)
 
-### Example Scenario
+Initialize `Steps` by passing the current Playwright `page` and your `ElementRepository` instance.
 
 ```ts
 import { test } from '@playwright/test';
@@ -76,34 +102,23 @@ import { ElementRepository } from 'pw-element-repository';
 import { Steps, DropdownSelectType } 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: DropdownSelectType.RANDOM 
+  const selectedSize = await steps.selectDropdown('ProductDetailsPage', 'size-selector', {
+    type: DropdownSelectType.RANDOM,
   });
   console.log(`Selected size: ${selectedSize}`);
 
-  // 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');
 });
 ```
@@ -112,9 +127,9 @@ test('Add random product and verify image gallery', async ({ page }) => {
 
 ## 🔧 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.
+For larger projects, manually initializing `repo` and `steps` in every test becomes repetitive. `baseFixture` injects all core dependencies automatically via Playwright's fixture system.
 
-### What's included
+### Included fixtures
 
 | Fixture | Type | Description |
 |---|---|---|
@@ -123,9 +138,27 @@ For larger projects, manually initializing `repo` and `steps` inside every test
 | `interactions` | `ElementInteractions` | Raw interactions API for custom locators |
 | `contextStore` | `ContextStore` | Shared in-memory store for passing data between steps |
 
-### 1. Create your fixture file
+`baseFixture` also attaches a full-page `failure-screenshot` to the Playwright HTML report on every failed test.
 
-Call `baseFixture` once, passing your own `test` base and the path to your locator repository:
+> **Note:** `reporter: 'html'` must be set in `playwright.config.ts` for screenshots to appear. Run `npx playwright show-report` after a failed run to inspect them.
+
+### 1. Playwright Config
+
+```ts
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests',
+  reporter: 'html',
+  use: {
+    baseURL: 'https://your-project-url.com',
+    headless: true,
+  },
+});
+```
+
+### 2. Create your fixture file
 
 ```ts
 // tests/fixtures/base.ts
@@ -136,9 +169,7 @@ 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:
+### 3. Use fixtures in your tests
 
 ```ts
 // tests/checkout.spec.ts
@@ -161,9 +192,7 @@ test('Complete checkout flow', async ({ steps }) => {
 });
 ```
 
-### 3. Access `repo` directly when needed
-
-For advanced queries like resolving a locator by visible text, destructure `repo` alongside `steps`:
+### 4. Access `repo` directly when needed
 
 ```ts
 test('Navigate to Forms category', async ({ page, repo, steps }) => {
@@ -176,9 +205,9 @@ test('Navigate to Forms category', async ({ page, repo, steps }) => {
 });
 ```
 
-### 4. Extend with your own fixtures
+### 5. Extend with your own fixtures
 
-Because `baseFixture` returns a standard Playwright `test` object, you can chain your own fixtures on top of it cleanly:
+Because `baseFixture` returns a standard Playwright `test` object, you can layer your own fixtures on top:
 
 ```ts
 // tests/fixtures/base.ts
@@ -201,8 +230,6 @@ export const test = testWithBase.extend<MyFixtures>({
 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');
@@ -214,63 +241,111 @@ test('Authenticated flow', async ({ steps, authService }) => {
 
 ## 🛠️ API Reference: `Steps`
 
-The `Steps` class automatically handles fetching the Playwright `Locator` using your `pageName` and `elementName` keys from the repository.
+Every method below automatically fetches the Playwright `Locator` using your `pageName` and `elementName` keys from the repository.
 
 ### 🧭 Navigation
 
-* **`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.
+* **`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 in the given direction.
+* **`setViewport(width: number, height: number)`** — Resizes the browser viewport to the specified pixel dimensions.
 
 ### 🖱️ Interaction
 
-* **`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.
-* **`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 }`).
+* **`click(pageName, elementName)`** — Clicks an element. Automatically waits for the element to be attached, visible, stable, and actionable.
+* **`clickWithoutScrolling(pageName, elementName)`** — Dispatches a native `click` event directly, bypassing Playwright's scrolling and intersection observer checks. Useful for elements obscured by sticky headers or overlays.
+* **`clickIfPresent(pageName, elementName)`** — Clicks an element only if it is visible; skips silently otherwise. Ideal for optional elements like cookie banners.
+* **`clickRandom(pageName, elementName)`** — Clicks a random element from all matches. Useful for lists or grids.
+* **`hover(pageName, elementName)`** — Hovers over an element to trigger dropdowns or tooltips.
+* **`scrollIntoView(pageName, elementName)`** — Smoothly scrolls an element into the viewport.
+* **`dragAndDrop(pageName, elementName, options: DragAndDropOptions)`** — Drags an element to a target element (`{ target: Locator }`), by coordinate offset (`{ xOffset, yOffset }`), or both.
+* **`dragAndDropListedElement(pageName, elementName, elementText, options: DragAndDropOptions)`** — Finds a specific element by its text from a list, then drags it to a destination.
+* **`fill(pageName, elementName, text: string)`** — Clears and fills an input field with the provided text.
+* **`uploadFile(pageName, elementName, filePath: string)`** — Uploads a file to an `<input type="file">` element.
+* **`selectDropdown(pageName, elementName, options?: DropdownSelectOptions)`** — Selects an option from a `<select>` element and returns its `value`. Defaults to `{ type: DropdownSelectType.RANDOM }`. Also supports `VALUE` (exact match) and `INDEX` (zero-based).
+* **`typeSequentially(pageName, elementName, text: string, delay?: number)`** — Types text character by character with a configurable delay (default `100ms`). Ideal for OTP inputs or fields with `keyup` listeners.
 
 ### 📊 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.
+* **`getText(pageName, elementName)`** — Returns the trimmed text content of an element, or an empty string if null.
+* **`getAttribute(pageName, elementName, attributeName: string)`** — Returns the value of an HTML attribute (e.g. `href`, `aria-pressed`), or `null` if it 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, 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.
+* **`verifyPresence(pageName, elementName)`** — Asserts that an element is attached to the DOM and visible.
+* **`verifyAbsence(pageName, elementName)`** — Asserts that an element is hidden or detached from the DOM.
+* **`verifyText(pageName, elementName, expectedText?, options?: TextVerifyOptions)`** — Asserts element text. Provide `expectedText` for an exact match, or `{ notEmpty: true }` to assert the text is not blank.
+* **`verifyCount(pageName, elementName, options: CountVerifyOptions)`** — Asserts element count. Accepts `{ exact: number }`, `{ greaterThan: number }`, or `{ lessThan: number }`.
+* **`verifyImages(pageName, elementName, scroll?: boolean)`** — Verifies image rendering: checks visibility, valid `src`, `naturalWidth > 0`, and the browser's native `decode()` promise. Scrolls into view by default.
+* **`verifyUrlContains(text: string)`** — Asserts that the current 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'`.
+* **`waitForState(pageName, elementName, state?: 'visible' | 'attached' | 'hidden' | 'detached')`** — Waits for an element to reach a specific DOM state. Defaults to `'visible'`.
 
 ---
 
-## 🧱 Advanced Usage: Raw Interactions API
+## 🧱 Advanced: 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.
+To bypass the repository or work with dynamically generated locators, use `ElementInteractions` 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.count(customLocator, { greaterThan: 2 });
 ```
 
-*Note: All core interaction (`interact`), verification (`verify`), and navigation (`navigate`) methods are also available when using `ElementInteractions` directly.*
+All core `interact`, `verify`, and `navigate` methods are available on `ElementInteractions`.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read the guidelines below before opening a PR.
+
+### 🧪 Testing locally
+
+Verify your changes end-to-end in a real consumer project using [`yalc`](https://github.com/wclr/yalc):
+
+```bash
+# Install yalc globally (one-time)
+npm i -g yalc
+
+# In the pw-element-interactions folder
+yalc publish
+
+# In your consumer project
+yalc add pw-element-interactions
+```
+
+Push updates without re-adding:
+
+```bash
+yalc publish --push
+```
+
+Restore the original npm version when done:
+
+```bash
+yalc remove pw-element-interactions
+npm install
+```
+
+### 📋 PR guidelines
+
+**Architecture.** Every new capability must follow this order:
+
+1. Implement the core method in the appropriate domain class (`interact`, `verify`, `navigate`, etc.).
+2. Expose it via a `Steps` wrapper.
+
+PRs that skip step 1 will not be merged.
+
+**Logging.** Core interaction methods must not contain any logs. `Steps` wrappers are responsible for logging what action is being performed.
+
+**Unit tests.** Every new method must include a unit test. Tests run against the [Vue test app](https://github.com/Umutayb/vue-test-app), which is built from its Docker image during CI. If the component you need doesn't exist in the test app, open a PR there first and wait for it to merge before updating this repository.
+
+**Documentation.** Every new `Steps` method must be added to the [API Reference](#️-api-reference-steps) section of this README, following the existing format. PRs without documentation will not be merged.

package/dist/fixture/BaseFixture.js

@@ -20,5 +20,15 @@ function baseFixture(baseTest, locatorPath) {
         contextStore: async ({}, use) => {
             await use(new context_store_1.ContextStore());
         },
+        page: async ({ page }, use, testInfo) => {
+            await use(page);
+            if (testInfo.status !== testInfo.expectedStatus) {
+                const screenshot = await page.screenshot({ fullPage: true });
+                await testInfo.attach('failure-screenshot', {
+                    body: screenshot,
+                    contentType: 'image/png',
+                });
+            }
+        },
     });
 }

package/dist/interactions/Interaction.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Interactions = void 0;
 const Options_1 = require("../enum/Options");
 const ElementUtilities_1 = require("../utils/ElementUtilities");
+const Logger_1 = require("../logger/Logger");
+const log = (0, Logger_1.createLogger)('interactions');
 /**
  * The `Interactions` class provides a robust set of methods for interacting
  * with DOM elements via Playwright Locators. It abstracts away common boilerplate
@@ -52,7 +54,7 @@ class Interactions {
             await locator.click({ timeout: this.ELEMENT_TIMEOUT });
         }
         else {
-            console.log(`[Action] -> Locator was not visible. Skipping click.`);
+            log('Locator was not visible, skipping click');
         }
     }
     /**
@@ -71,7 +73,7 @@ class Interactions {
      */
     async uploadFile(locator, filePath) {
         await this.utils.waitForState(locator, 'attached');
-        console.log(`[Action] -> Uploading file from path "${filePath}"`);
+        log('Uploading file from path "%s"', filePath);
         await locator.setInputFiles(filePath, { timeout: this.ELEMENT_TIMEOUT });
     }
     /**
@@ -191,7 +193,7 @@ class Interactions {
             const msg = `Element '${elementName}' on '${pageName}' with text "${desiredText}" not found.\nAvailable texts found in locator: ${availableTexts.length > 0 ? `\n- ${availableTexts.join('\n- ')}` : 'None (Base locator found no elements or elements had no text)'}`;
             if (strict)
                 throw new Error(msg);
-            console.warn(msg);
+            log('⚠ %s', msg);
             return null;
         }
         return locator;
@@ -206,7 +208,6 @@ class Interactions {
      */
     async typeSequentially(locator, text, delay = 100) {
         await this.utils.waitForState(locator, 'visible');
-        console.log(`[Action] -> Typing "${text}" sequentially with a ${delay}ms delay.`);
         await locator.pressSequentially(text, {
             delay,
             timeout: this.ELEMENT_TIMEOUT

package/dist/interactions/Navigation.d.ts

@@ -11,10 +11,14 @@ export declare class Navigation {
      */
     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.
-     */
+    * 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.
+    * Relative URLs (e.g. '/path') are resolved against `baseURL` from playwright.config.ts.
+    * Protocol-relative URLs (e.g. '//example.com') are passed directly to the browser.
+    * ⚠️ If a relative URL is passed and no baseURL is configured, an error will be thrown.
+    * Prefer fully qualified URLs to avoid ambiguity.
+    */
     toUrl(url: string): Promise<void>;
     /**
      * Reloads the current page.

package/dist/interactions/Navigation.js

@@ -15,12 +15,24 @@ class Navigation {
         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.
-     */
+    * 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.
+    * Relative URLs (e.g. '/path') are resolved against `baseURL` from playwright.config.ts.
+    * Protocol-relative URLs (e.g. '//example.com') are passed directly to the browser.
+    * ⚠️ If a relative URL is passed and no baseURL is configured, an error will be thrown.
+    * Prefer fully qualified URLs to avoid ambiguity.
+    */
     async toUrl(url) {
-        await this.page.goto(url);
+        let resolved = url;
+        if (!url.startsWith('http')) {
+            const baseURL = this.page.context()._options?.baseURL;
+            if (!baseURL) {
+                throw new Error(`Cannot resolve relative URL "${url}" — no baseURL is configured in playwright.config.ts.`);
+            }
+            resolved = new URL(url, baseURL).href;
+        }
+        await this.page.goto(resolved);
     }
     /**
      * Reloads the current page.

package/dist/interactions/Verification.js

@@ -36,7 +36,7 @@ class Verifications {
             return;
         }
         if (expectedText === undefined) {
-            throw new Error(`[Verify] -> You must provide either an 'expectedText' string or set '{ notEmpty: true }' in options.`);
+            throw new Error(`You must provide either an 'expectedText' string or set '{ notEmpty: true }' in options.`);
         }
         await (0, test_1.expect)(locator).toHaveText(expectedText, { timeout: this.ELEMENT_TIMEOUT });
     }
@@ -109,7 +109,7 @@ class Verifications {
     async images(imagesLocator, scroll = true) {
         const productImages = await imagesLocator.all();
         if (productImages.length === 0) {
-            throw new Error(`[Verify] -> No images found for '${imagesLocator}'.`);
+            throw new Error(`No images found for '${imagesLocator}'.`);
         }
         for (let i = 0; i < productImages.length; i++) {
             const productImage = productImages[i];
@@ -140,20 +140,20 @@ class Verifications {
     */
     async count(locator, options) {
         if (options.exactly !== undefined && options.exactly < 0) {
-            throw new Error(`[Verify] -> 'exact' count cannot be negative.`);
+            throw new Error(`'exact' count cannot be negative.`);
         }
         if (options.greaterThan !== undefined && options.greaterThan < 0) {
-            throw new Error(`[Verify] -> 'greaterThan' count cannot be negative.`);
+            throw new Error(`'greaterThan' count cannot be negative.`);
         }
         if (options.lessThan !== undefined && options.lessThan <= 0) {
-            throw new Error(`[Verify] -> 'lessThan' must be greater than 0. Element counts cannot be negative.`);
+            throw new Error(`'lessThan' must be greater than 0. Element counts cannot be negative.`);
         }
         if (options.exactly !== undefined) {
             await (0, test_1.expect)(locator).toHaveCount(options.exactly, { timeout: this.ELEMENT_TIMEOUT });
             return;
         }
         if (options.greaterThan === undefined && options.lessThan === undefined) {
-            throw new Error(`[Verify] -> You must provide 'exact', 'greaterThan', or 'lessThan' in CountVerifyOptions.`);
+            throw new Error(`You must provide 'exact', 'greaterThan', or 'lessThan' in CountVerifyOptions.`);
         }
         await locator.first().waitFor({ state: 'attached', timeout: this.ELEMENT_TIMEOUT }).catch(() => { });
         const actualCount = await locator.count();

package/dist/logger/Logger.d.ts

@@ -0,0 +1,25 @@
+import Debug from 'debug';
+/**
+ * Creates a namespaced debug logger with a padded label for aligned output.
+ *
+ * Namespaces shorter than `NAMESPACE_PAD` are right-padded with spaces so
+ * that log messages from different loggers line up in the terminal:
+ *
+ *   tester:navigate    Navigating to URL: "/"
+ *   tester:interact    Clicking on "submitButton" in "FormsPage"
+ *   tester:verify      Verifying presence of "table" in "FormsPage"
+ *   tester:wait        Waiting for "modal" in "FormsPage" to be "visible"
+ *
+ * @param namespace - A colon-delimited scope appended to the library prefix.
+ *                    Examples: 'navigate', 'interact', 'verify', 'wait'
+ * @returns A `debug` instance bound to `tester:<namespace>` (padded).
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from '../logger/Logger';
+ *
+ * const log = createLogger('interact');
+ * log('Clicking on "%s" in "%s"', elementName, pageName);
+ * ```
+ */
+export declare function createLogger(namespace: string): Debug.Debugger;

package/dist/logger/Logger.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLogger = createLogger;
+const debug_1 = __importDefault(require("debug"));
+/**
+ * The library-wide namespace prefix.
+ * All loggers created by this factory are scoped under this prefix.
+ *
+ * Logging is ON by default for all tester:* namespaces.
+ * To narrow output, set the DEBUG environment variable:
+ *
+ *   DEBUG=tester:steps:*              → Steps output only
+ *   DEBUG=tester:steps:interact       → interaction steps only
+ *   DEBUG=tester:interactions         → raw Interaction class
+ *   DEBUG=tester:steps:*,tester:interactions → combine multiple scopes
+ *
+ * To disable logging entirely:
+ *
+ *   TESTER_DEBUG=false npx playwright test   → suppress all tester:* logs
+ *
+ * Or in playwright.config.ts / your test setup file:
+ *
+ *   process.env.TESTER_DEBUG = 'false';
+ */
+const PREFIX = 'tester';
+const logsDisabled = process.env.TESTER_DEBUG === 'false';
+if (!logsDisabled && !process.env.DEBUG) {
+    debug_1.default.enable(`${PREFIX}:*`);
+}
+/**
+ * The column width used to pad namespace labels in log output.
+ * All namespaces are right-padded to this length so log columns align.
+ *
+ * If you add a namespace longer than this value, increase it to match.
+ */
+const NAMESPACE_PAD = 9; // 'interactions' is the longest built-in namespace
+/**
+ * Creates a namespaced debug logger with a padded label for aligned output.
+ *
+ * Namespaces shorter than `NAMESPACE_PAD` are right-padded with spaces so
+ * that log messages from different loggers line up in the terminal:
+ *
+ *   tester:navigate    Navigating to URL: "/"
+ *   tester:interact    Clicking on "submitButton" in "FormsPage"
+ *   tester:verify      Verifying presence of "table" in "FormsPage"
+ *   tester:wait        Waiting for "modal" in "FormsPage" to be "visible"
+ *
+ * @param namespace - A colon-delimited scope appended to the library prefix.
+ *                    Examples: 'navigate', 'interact', 'verify', 'wait'
+ * @returns A `debug` instance bound to `tester:<namespace>` (padded).
+ *
+ * @example
+ * ```ts
+ * import { createLogger } from '../logger/Logger';
+ *
+ * const log = createLogger('interact');
+ * log('Clicking on "%s" in "%s"', elementName, pageName);
+ * ```
+ */
+function createLogger(namespace) {
+    const padded = namespace.padEnd(NAMESPACE_PAD);
+    return (0, debug_1.default)(`${PREFIX}:${padded}`);
+}