pw-element-interactions 0.0.7 → 0.0.9

package/README.md

@@ -236,6 +236,7 @@ The `Steps` class automatically handles fetching the Playwright `Locator` using
 * **`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 }`).
+* **`typeSequentially(pageName: string, elementName: string, text: string, delay?: number)`**: Types the provided text into an element character by character with a configurable delay between key presses (defaults to `100ms`). Ideal for OTP inputs, search bars, or any field with `keyup` listeners that do not respond correctly to bulk `fill()` operations.
 
 ### 📊 Data Extraction
 
@@ -273,4 +274,74 @@ 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.*
+*Note: All core interaction (`interact`), verification (`verify`), and navigation (`navigate`) methods are also available when using `ElementInteractions` directly.*
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read the rules below carefully before opening a PR — they exist to keep the architecture clean, the test suite reliable, and the codebase consistent.
+
+### 🧪 Testing Locally Before Opening a PR
+
+Before pushing changes, verify your implementation works end-to-end in a real consumer project using [`yalc`](https://github.com/wclr/yalc) — a local package publishing tool that mirrors the npm install flow without actually publishing.
+
+```bash
+# 1. Install yalc globally (one-time setup)
+npm i -g yalc
+
+# 2. In the pw-element-interactions folder — publish to the local yalc store
+yalc publish
+
+# 3. In your consumer project — add the locally published package
+yalc add pw-element-interactions
+```
+
+After making further changes, push updates to the consumer project without re-adding:
+
+```bash
+# In pw-element-interactions
+yalc publish --push
+```
+
+To restore the original npm version when you're done:
+
+```bash
+# In your consumer project
+yalc remove pw-element-interactions
+npm install
+```
+
+### 📋 PR Guidelines
+
+PRs must respect the layered architecture of this library. Every new capability follows a strict implementation order:
+
+1. **Implement in the appropriate class first.** The core method must be added to the correct underlying class (`interact`, `verify`, `navigate`, or similar) before it is exposed anywhere else. Do not add a method only to `Steps` or `ElementInteractions` without first placing the logic in the right domain class.
+2. **Then expose it via `Steps`.** Once the core method exists in its proper class, add the corresponding wrapper to the `Steps` (CommonSteps) class so it is accessible through the unified API.
+
+PRs that skip step 1 and add convenience methods without a properly placed underlying implementation will not be merged.
+
+### 🪵 Logging
+
+The logging responsibility is clearly divided and must be respected:
+
+* **Interaction methods must not contain any logs.** Keep them focused purely on the mechanics of the action.
+* **`Steps` methods are responsible for logging.** Every `Steps` wrapper should log what action is being performed, providing observability at the right level of abstraction.
+
+### 🧬 Unit Tests
+
+Every new interaction method must be accompanied by a unit test.
+
+Unit tests are run against the proprietary Vue test application at [https://github.com/Umutayb/vue-test-app](https://github.com/Umutayb/vue-test-app). This app is built from its Docker image during the CI pipeline to serve as the test target. All new tests must use this app.
+
+If the component or UI element needed to test a new interaction does not exist in the Vue test app, **you must add it there first**:
+
+1. Open a PR against `vue-test-app` to add the required component.
+2. Wait for that PR to be merged.
+3. Only then open or update the PR in this repository that adds the interaction and its test.
+
+PRs that require a missing component but do not have a corresponding merged `vue-test-app` PR will not be merged.
+
+### 📝 Documentation
+
+Every new `Steps` method must be documented in the [API Reference](#️-api-reference-steps) section of this README. Add your method to the appropriate group (Navigation, Interaction, Data Extraction, Verification, or Wait) following the existing format: method signature, a plain-English description of what it does, and any relevant parameter or return value notes. PRs that add a public method without a corresponding README entry will not be merged.

package/dist/interactions/Interaction.d.ts

@@ -83,4 +83,13 @@ export declare class Interactions {
        * @returns A promise that resolves to the matched Playwright Locator, or null if not found.
        */
     getByText(baseLocator: Locator, pageName: string, elementName: string, desiredText: string, strict?: boolean): Promise<ReturnType<Page['locator']> | null>;
+    /**
+     * Types into the target element character by character with a specified delay.
+     * Use this for OTP inputs, search-as-you-type fields, or when `fill()`
+     * doesn't trigger necessary keyboard events (like 'keyup' or 'keydown').
+     * @param locator - The Playwright Locator pointing to the input element.
+     * @param text - The string of text to type sequentially.
+     * @param delay - Time in milliseconds to wait between key presses. Defaults to 100ms.
+     */
+    typeSequentially(locator: Locator, text: string, delay?: number): Promise<void>;
 }

package/dist/interactions/Interaction.js

@@ -196,5 +196,20 @@ class Interactions {
         }
         return locator;
     }
+    /**
+     * Types into the target element character by character with a specified delay.
+     * Use this for OTP inputs, search-as-you-type fields, or when `fill()`
+     * doesn't trigger necessary keyboard events (like 'keyup' or 'keydown').
+     * @param locator - The Playwright Locator pointing to the input element.
+     * @param text - The string of text to type sequentially.
+     * @param delay - Time in milliseconds to wait between key presses. Defaults to 100ms.
+     */
+    async typeSequentially(locator, text, delay = 100) {
+        await this.utils.waitForState(locator, 'visible');
+        await locator.pressSequentially(text, {
+            delay,
+            timeout: this.ELEMENT_TIMEOUT
+        });
+    }
 }
 exports.Interactions = Interactions;

package/dist/steps/CommonSteps.d.ts

@@ -183,4 +183,13 @@ export declare class Steps {
      * @param state - The state to wait for: 'visible' | 'attached' | 'hidden' | 'detached'. Defaults to 'visible'.
      */
     waitForState(pageName: string, elementName: string, state?: 'visible' | 'attached' | 'hidden' | 'detached'): Promise<void>;
+    /**
+     * Types text into a specific element character by character with a delay.
+     * Ideal for OTP inputs, search bars, or fields with sensitive 'keyup' listeners.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     * @param text - The string to type sequentially.
+     * @param delay - Optional delay between key presses in milliseconds (defaults to 100).
+     */
+    typeSequentially(pageName: string, elementName: string, text: string, delay?: number): Promise<void>;
 }

package/dist/steps/CommonSteps.js

@@ -298,5 +298,18 @@ class Steps {
         const locator = await this.repo.get(this.page, pageName, elementName);
         await this.utils.waitForState(locator, state);
     }
+    /**
+     * Types text into a specific element character by character with a delay.
+     * Ideal for OTP inputs, search bars, or fields with sensitive 'keyup' listeners.
+     * @param pageName - The page or component grouping name in your repository.
+     * @param elementName - The specific element name in your repository.
+     * @param text - The string to type sequentially.
+     * @param delay - Optional delay between key presses in milliseconds (defaults to 100).
+     */
+    async typeSequentially(pageName, elementName, text, delay = 100) {
+        console.log(`[Step] -> Typing "${text}" sequentially into '${elementName}' in '${pageName}' (Delay: ${delay}ms)`);
+        const locator = await this.repo.get(this.page, pageName, elementName);
+        await this.interact.typeSequentially(locator, text, delay);
+    }
 }
 exports.Steps = Steps;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pw-element-interactions",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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",
@@ -8,10 +8,13 @@
     "clean": "rm -rf dist",
     "build": "npm run clean && tsc",
     "test": "npx playwright test",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "scripts/postinstall.js"
   ],
   "peerDependencies": {
     "@civitas-cerebrum/context-store": ">=0.0.2",

package/scripts/postinstall.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+const fs   = require('fs');
+const path = require('path');
+
+// Resolve the root of the consuming project (three levels up from
+// node_modules/pw-element-interactions/scripts/postinstall.js)
+const projectRoot = path.resolve(__dirname, '..', '..', '..');
+
+const src  = path.join(__dirname, '..', 'skills', 'SKILL.md');
+const dest = path.join(projectRoot, '.claude', 'skills', 'pw-element-interactions', 'SKILL.md');
+
+try {
+  if (!fs.existsSync(src)) {
+    console.warn('[pw-element-interactions] Skill file not found, skipping.');
+    process.exit(0);
+  }
+
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  console.log('[pw-element-interactions] ✔ Claude Code skill installed — restart Claude Code to pick it up.');
+} catch (err) {
+  // Never fail the install — skill copy is best-effort
+  console.warn(`[pw-element-interactions] Could not install Claude Code skill: ${err.message}`);
+}

package/skills/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: skills
+description: >
+  Use this skill whenever writing or generating Playwright tests in a project that uses
+  pw-element-interactions and pw-element-repository. Triggers on any request to write a
+  test, add a locator, create a page object, use the Steps API, or interact with elements
+  using this stack. Also use when asked to add entries to a page-repository JSON file,
+  use fixtures, select dropdowns, verify elements, wait for states, or perform any
+  browser interaction through this framework. Always consult this skill before generating
+  test code or locator JSON — do not guess API shapes or invent method signatures.
+---
+
+# pw-element-interactions — Test Authoring Reference
+
+This framework separates **where elements are defined** from **how they are used**. Selectors live in a JSON file; tests reference elements by readable string keys. No raw CSS or XPath ever appears in test code.
+
+---
+
+## 0. Understanding the Website Structure
+
+Before writing tests or adding locators for an unfamiliar page or component, use the **Playwright MCP** to inspect the live site. This is the only reliable way to discover real selectors, element hierarchy, and page behaviour — do not guess or invent selectors from memory.
+
+Typical uses:
+- Navigating to a page and reading its DOM to find the right CSS selector or text for a new locator entry
+- Verifying that an element is actually present and visible before writing an assertion
+- Understanding the flow between pages before writing a multi-step test
+
+If the Playwright MCP is not connected, ask the user to install it before proceeding:
+
+```
+I need the Playwright MCP to inspect the site and find accurate selectors.
+Please install it by adding the following to your Claude Code MCP settings:
+
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+
+Then restart Claude Code and try again.
+```
+
+Do not attempt to write locators or test steps for unknown pages without first using the Playwright MCP to confirm the structure.
+
+---
+
+## 1. Adding Locators
+
+All selectors are stored in a single JSON file (commonly `tests/data/page-repository.json`). Each page groups its elements by name. Provide as many selector strategies as you like — the repository uses the first one that resolves:
+
+```json
+{
+  "pages": [
+    {
+      "name": "HomePage",
+      "elements": [
+        {
+          "elementName": "submitButton",
+          "selector": {
+            "css": "button[data-test='submit']",
+            "xpath": "//button[@data-test='submit']",
+            "id": "submit-btn",
+            "text": "Submit"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Naming conventions:**
+- `name` — PascalCase page identifier, e.g. `CheckoutPage`, `ProductDetailsPage`
+- `elementName` — camelCase element identifier, e.g. `submitButton`, `gallery-images`
+
+---
+
+## 2. Setup
+
+### Option A — Fixtures (recommended)
+
+Define once in a fixture file; every test gets `steps`, `repo`, `interactions`, and `contextStore` for free:
+
+```ts
+// tests/fixtures/base.ts
+import { test as base } from '@playwright/test';
+import { baseFixture } from 'pw-element-interactions';
+
+export const test = baseFixture(base, 'tests/data/page-repository.json');
+export { expect } from '@playwright/test';
+```
+
+```ts
+// tests/checkout.spec.ts
+import { test } from '../fixtures/base';
+
+test('complete checkout', async ({ steps }) => {
+  await steps.navigateTo('/checkout');
+  await steps.click('CheckoutPage', 'submitButton');
+});
+```
+
+### Option B — Manual initialisation
+
+```ts
+import { ElementRepository } from 'pw-element-repository';
+import { Steps } from 'pw-element-interactions';
+
+const repo  = new ElementRepository('tests/data/page-repository.json', 15000);
+const steps = new Steps(page, repo);
+```
+
+---
+
+## 3. Steps API
+
+Every method takes `pageName` and `elementName` as its first two arguments, matching keys in your JSON file.
+
+### 🧭 Navigation
+
+```ts
+await steps.navigateTo('/path');
+await steps.refresh();
+await steps.backOrForward('BACKWARDS'); // or 'FORWARDS'
+await steps.setViewport(1280, 720);
+```
+
+### 🖱️ Interaction
+
+```ts
+// Standard click — waits for visible, stable, actionable
+await steps.click('PageName', 'elementName');
+
+// Click without scrolling — use for elements behind sticky headers or overlays
+await steps.clickWithoutScrolling('PageName', 'elementName');
+
+// Click only if the element is visible — silently skips if not (e.g. cookie banners)
+await steps.clickIfPresent('PageName', 'elementName');
+
+// Click a random element from a matched list (e.g. product cards)
+await steps.clickRandom('PageName', 'elementName');
+
+// Hover to trigger a tooltip or dropdown
+await steps.hover('PageName', 'elementName');
+
+// Scroll element into view
+await steps.scrollIntoView('PageName', 'elementName');
+
+// Clear and type text
+await steps.fill('PageName', 'elementName', 'my input');
+
+// Type character by character — use for OTP inputs or fields with keyup listeners
+await steps.typeSequentially('PageName', 'elementName', 'my input');
+await steps.typeSequentially('PageName', 'elementName', 'my input', 50); // custom delay ms
+
+// Upload a file
+await steps.uploadFile('PageName', 'elementName', 'tests/fixtures/file.pdf');
+
+// Select from a <select> dropdown — returns the selected value
+import { DropdownSelectType } from 'pw-element-interactions';
+
+const value = await steps.selectDropdown('PageName', 'elementName');                                         // random (default)
+const value = await steps.selectDropdown('PageName', 'elementName', { type: DropdownSelectType.RANDOM });
+const value = await steps.selectDropdown('PageName', 'elementName', { type: DropdownSelectType.VALUE, value: 'xl' });
+const value = await steps.selectDropdown('PageName', 'elementName', { type: DropdownSelectType.INDEX, index: 2 });
+
+// Drag and drop
+await steps.dragAndDrop('PageName', 'elementName', { target: otherLocator });
+await steps.dragAndDrop('PageName', 'elementName', { xOffset: 100, yOffset: 0 });
+
+// Drag a specific listed item by its text
+await steps.dragAndDropListedElement('PageName', 'elementName', 'Item Label', { target: otherLocator });
+```
+
+### 📊 Data Extraction
+
+```ts
+const text = await steps.getText('PageName', 'elementName');        // trimmed text; '' if null
+const href  = await steps.getAttribute('PageName', 'elementName', 'href'); // null if absent
+```
+
+### ✅ Verification
+
+```ts
+// Presence / absence
+await steps.verifyPresence('PageName', 'elementName');
+await steps.verifyAbsence('PageName', 'elementName');
+
+// Text — exact match or non-empty check
+await steps.verifyText('PageName', 'elementName', 'Expected text');
+await steps.verifyText('PageName', 'elementName', undefined, { notEmpty: true });
+
+// Count
+await steps.verifyCount('PageName', 'elementName', { exact: 3 });
+await steps.verifyCount('PageName', 'elementName', { greaterThan: 0 });
+await steps.verifyCount('PageName', 'elementName', { lessThan: 10 });
+
+// Images — checks visibility, valid src, naturalWidth > 0, and browser decode()
+await steps.verifyImages('PageName', 'elementName');
+await steps.verifyImages('PageName', 'elementName', false); // skip scroll-into-view
+
+// URL
+await steps.verifyUrlContains('/dashboard');
+```
+
+### ⏳ Waiting
+
+```ts
+await steps.waitForState('PageName', 'elementName');               // default: 'visible'
+await steps.waitForState('PageName', 'elementName', 'hidden');
+await steps.waitForState('PageName', 'elementName', 'attached');
+await steps.waitForState('PageName', 'elementName', 'detached');
+```
+
+---
+
+## 4. Accessing the Repository Directly
+
+When you need more than a simple locator lookup — filtering by visible text, iterating all matches, or picking a random item — use `repo` directly alongside `steps`:
+
+```ts
+test('navigate to Forms', async ({ page, repo, steps }) => {
+  await steps.navigateTo('/');
+
+  // Resolve a locator by the visible text it contains
+  const formsLink = await repo.getByText(page, 'HomePage', 'categories', 'Forms');
+  await formsLink?.click();
+
+  await steps.verifyAbsence('HomePage', 'categories');
+});
+```
+
+### Repository API
+
+```ts
+// Single locator — waits for DOM attachment
+await repo.get(page, 'PageName', 'elementName');
+
+// All matching locators — use for iteration
+await repo.getAll(page, 'PageName', 'elementName');
+
+// A random locator from the matched set — waits for visibility
+await repo.getRandom(page, 'PageName', 'elementName');
+
+// First locator whose visible text contains the given string
+await repo.getByText(page, 'PageName', 'elementName', 'Desired Text');
+
+// Sync — returns the raw selector string, e.g. "css=.btn"
+repo.getSelector('PageName', 'elementName');
+```
+
+---
+
+## 5. Complete Test Example
+
+```ts
+import { test } from '../fixtures/base';
+import { DropdownSelectType } from 'pw-element-interactions';
+
+test('add product to cart and verify', async ({ page, repo, steps }) => {
+  await steps.navigateTo('/');
+
+  // Click a category by its visible label
+  const accessories = await repo.getByText(page, 'HomePage', 'categories', 'Accessories');
+  await accessories?.click();
+
+  // Pick a random product
+  await steps.clickRandom('AccessoriesPage', 'productCards');
+  await steps.verifyUrlContains('/product/');
+
+  // Select a size from the dropdown
+  const size = await steps.selectDropdown('ProductPage', 'sizeSelector', {
+    type: DropdownSelectType.RANDOM,
+  });
+  console.log(`Selected size: ${size}`);
+
+  // Verify the image gallery loaded correctly
+  await steps.verifyCount('ProductPage', 'galleryImages', { greaterThan: 0 });
+  await steps.verifyImages('ProductPage', 'galleryImages');
+
+  // Verify product title is not blank
+  await steps.verifyText('ProductPage', 'productTitle', undefined, { notEmpty: true });
+
+  // Add to cart and wait for confirmation
+  await steps.click('ProductPage', 'addToCartButton');
+  await steps.waitForState('ProductPage', 'confirmationModal', 'visible');
+});
+```
+
+---
+
+## 6. Extending Fixtures
+
+Add your own fixtures on top of the base without losing `steps`, `repo`, or `contextStore`:
+
+```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 };
+
+export const test = baseFixture(base, 'tests/data/page-repository.json')
+  .extend<MyFixtures>({
+    authService: async ({ page }, use) => {
+      await use(new AuthService(page));
+    },
+  });
+
+export { expect } from '@playwright/test';
+```
+
+```ts
+test('authenticated flow', async ({ steps, authService }) => {
+  await authService.login('user@test.com', 'secret');
+  await steps.verifyUrlContains('/dashboard');
+});
+```