pw-element-interactions 0.0.5 → 0.0.6

package/README.md

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

package/dist/fixture/BaseFixture.d.ts

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

package/dist/fixture/BaseFixture.js

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

package/dist/steps/CommonSteps.d.ts

@@ -31,6 +31,19 @@ export declare class Steps {
      * Reloads the current page.
      */
     refresh(): 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>;
     /**
      * Retrieves an element from the repository and performs a standard click.
      * @param pageName - The page or component grouping name in your repository.

package/dist/steps/CommonSteps.js

@@ -50,6 +50,25 @@ class Steps {
         console.log(`[Step] -> Refreshing the current page`);
         await this.navigate.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(`[Step] -> Navigating browser: "${direction}"`);
+        await this.navigate.backOrForward(direction);
+    }
+    /**
+     * 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(`[Step] -> Setting viewport to ${width}x${height}`);
+        await this.navigate.setViewport(width, height);
+    }
     // ==========================================
     // 🖱️ INTERACTION STEPS
     // ==========================================

package/dist/utils/ElementUtilities.d.ts

@@ -15,8 +15,12 @@ export declare class Utils {
     /**
      * 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.
+     * If the locator resolves to multiple elements (strict mode violation),
+     * the wait is retried automatically on the first matched element.
+     * @param locator - The Playwright Locator to wait on.
+     * @param state - The DOM state to wait for. Defaults to `'visible'`.
+     * @returns A Promise that resolves when the element reaches the desired state,
+     * or silently continues if the timeout is exceeded.
      */
     waitForState(locator: Locator, state?: 'visible' | 'attached' | 'hidden' | 'detached'): Promise<void>;
 }

package/dist/utils/ElementUtilities.js

@@ -21,14 +21,29 @@ class Utils {
     /**
      * 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.
+     * If the locator resolves to multiple elements (strict mode violation),
+     * the wait is retried automatically on the first matched element.
+     * @param locator - The Playwright Locator to wait on.
+     * @param state - The DOM state to wait for. Defaults to `'visible'`.
+     * @returns A Promise that resolves when the element reaches the desired state,
+     * or silently continues if the timeout is exceeded.
      */
     async waitForState(locator, state = 'visible') {
         try {
             await locator.waitFor({ state, timeout: this.timeout });
         }
         catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (message.includes('strict mode violation')) {
+                console.warn(`[Warning] -> Locator resolved to multiple elements. Waiting on first element instead.`);
+                try {
+                    await locator.first().waitFor({ state, timeout: this.timeout });
+                }
+                catch {
+                    console.warn(`[Warning] -> First element failed to reach state '${state}' within ${this.timeout}ms. Proceeding...`);
+                }
+                return;
+            }
             console.warn(`[Warning] -> Element failed to reach state '${state}' within ${this.timeout}ms. Proceeding...`);
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-element-interactions",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "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",
@@ -14,6 +14,7 @@
     "dist"
   ],
   "peerDependencies": {
+    "@civitas-cerebrum/context-store": ">=0.0.2",
     "@playwright/test": ">=1.0.0",
     "pw-element-repository": ">=0.0.3"
   },
@@ -44,4 +45,4 @@
   },
   "author": "Umut Ay Bora",
   "license": "MIT"
-}
+}