playwright-healing-locators 1.0.0

package/.github/workflows/playwright.yml

@@ -0,0 +1,27 @@
+name: Playwright Tests
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+jobs:
+  test:
+    timeout-minutes: 60
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v5
+    - uses: actions/setup-node@v5
+      with:
+        node-version: lts/*
+    - name: Install dependencies
+      run: npm ci
+    - name: Install Playwright Browsers
+      run: npx playwright install --with-deps
+    - name: Run Playwright tests
+      run: npx playwright test
+    - uses: actions/upload-artifact@v5
+      if: ${{ !cancelled() }}
+      with:
+        name: playwright-report
+        path: playwright-report/
+        retention-days: 30

package/README.md

@@ -0,0 +1,177 @@
+# 🎭 Playwright Healing Locators
+
+A robust, easy-to-use helper library for Playwright that improves test stability by automatically resolving broken selectors.
+
+When web UI structure changes are frequent (class renaming, attribute updates, dynamic ids), normal selectors break tests. This package helps by:
+
+- ✅ Trying a second locator when primary fails (`regularHeal`)
+- 🤖 Detecting similar elements based on selector keywords (`autoHeal`)
+- 🎯 Supporting common locator methods (CSS, XPath, text, ARIA, role)
+- 👀 Only continuing once a visible element is found, reducing false positives
+
+## 🔍 The Problem & Solution
+
+### ⚠️ Common Problem: Brittle selectors break tests
+- UI changes happen all the time (CSS classes change, DOM structure shifts, IDs get regenerated, attributes are refactored).
+- Traditional Playwright selectors (`page.locator('#x')`, `getByRole...`) fail immediately if the exact path is gone.
+- Teams spend time constantly updating tests, creating flakiness and maintenance debt.
+
+### 💡 Why This Package is Needed
+- It reduces **fast failure** when the first selector is invalid.
+- It avoids **unnecessary rework** by attempting recovery first.
+- It gives a **safe second chance** to selectors without manual intervention.
+
+### 🎉 What We Improved After Using This Package
+- ✨ **Resilient tests**: a bad primary selector can change to fallback instead of failing test.
+- 🔧 **Less maintenance**: one failing selector does not require immediate test patching.
+- 🛡️ **Better coverage**: both normal (`regularHeal`) and self-healing (`autoHeal`) paths are protected.
+- 🔐 **Higher confidence**: tests now verify actual element exists before action (`waitFor visible`).
+- 📊 **Faster debugging**: healing logs show which attempt worked.
+
+## ⭐ Features
+
+- `regularHeal`: manual fallback locators (primary + fallback array)
+- `autoHeal`: automatic healing by keyword matching and candidate scoring
+- Supports CSS, XPath, text, ARIA label, and role-based selectors
+- Built-in retry with visibility wait
+
+## 📦 Installation
+
+```bash
+npm install playwright-healing-locators
+```
+
+## 🚀 Usage
+
+```js
+import { test, expect } from '@playwright/test';
+import { regularHeal, autoHeal } from 'playwright-healing-locators';
+
+test('Regular Healing with fallback', async ({ page }) => {
+  await page.goto('https://practicetestautomation.com/practice-test-login/');
+
+  await regularHeal.fill(page, {
+    primary: '#wrong-username',
+    fallbacks: [
+      { type: 'role', value: 'textbox', name: 'Username' }
+    ]
+  }, 'student');
+
+  await regularHeal.fill(page, {
+    primary: '#wrong-password',
+    fallbacks: [
+      { type: 'role', value: 'textbox', name: 'Password' }
+    ]
+  }, 'Password123');
+
+  await regularHeal.click(page, {
+    primary: '#wrong-submit',
+    fallbacks: [
+      { type: 'role', value: 'button', name: 'Submit' }
+    ]
+  });
+
+  await expect(page.getByText('Logged In Successfully')).toBeVisible();
+});
+```
+
+```js
+test('Auto Healing with keyword-based candidate search', async ({ page }) => {
+  await page.goto('https://practicetestautomation.com/practice-test-login/');
+
+  await autoHeal.fill(page, {
+    primary: '#username-field-invalid'
+  }, 'student');
+
+  await autoHeal.fill(page, {
+    primary: '#password-field-invalid'
+  }, 'Password123');
+
+  await autoHeal.click(page, {
+    primary: '#submit-btn-invalid'
+  });
+
+  await expect(page.getByText('Logged In Successfully')).toBeVisible();
+});
+```
+
+## 📚 API
+
+### ✍️ `regularHeal.fill(page, options, value)`
+- `page`: Playwright page
+- `options.primary`: CSS/XPath primary selector
+- `options.fallbacks`: Array of fallback { type, value, name? }
+- `value`: text to fill
+
+### 🖱️ `regularHeal.click(page, options)`
+- `page`: Playwright page
+- `options.primary`: CSS/XPath primary selector
+- `options.fallbacks`: Array of fallback { type, value, name? }
+
+### ✍️ `autoHeal.fill(page, options, value)`
+- `page`: Playwright page
+- `options.primary`: primary selector to auto-heal from
+- `value`: text to fill
+
+### 🖱️ `autoHeal.click(page, options)`
+- `page`: Playwright page
+- `options.primary`: primary selector to auto-heal from
+
+## 🤝 Contribution
+
+1. 🍴 Fork repository
+2. 🌿 Create feature branch
+3. ✅ Add tests in `tests/*.spec.ts`
+4. 📤 Submit PR
+
+## ⚠️ Limitations & Known Issues
+
+While this package improves test resilience, be aware of these considerations:
+
+### ⏱️ Performance Impact
+- `autoHeal` searches the DOM for candidate elements, which may be slower on large/complex pages
+- Multiple fallback attempts in `regularHeal` add execution time
+- Consider using `regularHeal` for known stable fallbacks vs `autoHeal` for unpredictable UIs
+
+### 🎯 Accuracy Risks
+- `autoHeal` keyword matching might select incorrect elements if multiple similar elements exist
+- Always verify healing results in test reports and adjust primary selectors when possible
+- False positives possible if element attributes match but context differs
+
+### 🔄 Maintenance Overhead
+- `regularHeal` requires manual fallback definitions that need updates when UI changes
+- Auto-healing might mask underlying selector problems that should be fixed
+- Regular review of healing logs recommended to identify patterns
+
+### 🐛 Debugging Challenges
+- When healing fails completely, error messages may not pinpoint the exact issue
+- Healing logs help but require interpretation
+- Complex DOM structures may confuse keyword extraction
+
+### 🌐 Browser Compatibility
+- Tested on Chromium, Firefox, and WebKit as configured
+- XPath support may vary slightly between browsers
+- Mobile testing not yet validated
+
+### 📦 Dependencies
+- Requires Playwright `^1.59.1` (may work with newer but not guaranteed)
+- ES modules required (not CommonJS compatible)
+
+## 💻 Best Practices
+
+- Use `regularHeal` for predictable, stable fallbacks
+- Use `autoHeal` for dynamic content or when exact selectors are unreliable
+- Monitor healing logs to identify frequently failing selectors
+- Combine with good locator strategies (prefer roles/ARIA over fragile CSS)
+- Don't rely solely on healing - fix underlying UI issues when possible
+
+## 📝 Notes
+
+- Use a stable version of Playwright `^1.59.1`.
+- Ensure `playwright.config.js` uses `reporter: 'html'` if you need HTML test reports.
+
+## 📄 License
+
+This project is released under the **ISC License** - a permissive open-source license suitable for commercial and open-source projects.
+
+See the [LICENSE](LICENSE) file for details.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "playwright-healing-locators",
+  "version": "1.0.0",
+  "description": "A robust helper library for Playwright that improves test stability by automatically resolving broken selectors through fallback strategies and auto-healing.",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "test": "npx playwright test",
+    "test:headed": "npx playwright test --headed",
+    "report": "npx playwright show-report"
+  },
+  "keywords": [
+    "playwright",
+    "testing",
+    "automation",
+    "selectors",
+    "healing",
+    "resilient",
+    "fallback",
+    "auto-heal",
+    "test-stability",
+    "e2e-testing"
+  ],
+  "author": "Iniyavan",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iniyavans/playwright-healing-locators.git"
+  },
+  "homepage": "https://github.com/iniyavans/playwright-healing-locators#readme",
+  "bugs": {
+    "url": "https://github.com/iniyavans/playwright-healing-locators/issues"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.59.0"
+  },
+  "dependencies": {
+    "playwright": "^1.59.1"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.59.1",
+    "@types/node": "^25.5.0",
+    "playwright": "^1.59.1"
+  }
+}

package/playwright.config.js

@@ -0,0 +1,102 @@
+// TypeScript type checking for this config file
+// @ts-check
+
+// Import Playwright's configuration helper and device presets
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Optional: Read environment variables from a .env file.
+ * Uncomment the lines below if you want to use environment variables.
+ * https://github.com/motdotla/dotenv
+ */
+// import dotenv from 'dotenv';
+// import path from 'path';
+// dotenv.config({ path: path.resolve(__dirname, '.env') });
+
+/**
+ * Playwright test configuration
+ * This file configures how Playwright runs your tests.
+ * @see https://playwright.dev/docs/test-configuration
+ */
+export default defineConfig({
+  // Directory where test files are located
+  testDir: './tests',
+
+  /* Run tests in files in parallel for faster execution */
+  fullyParallel: true,
+
+  /* Fail the build on CI if you accidentally left test.only in the source code.
+     This prevents focused tests from being committed to CI. */
+  forbidOnly: !!process.env.CI,
+
+  /* Retry failed tests: only retry on CI, not locally */
+  retries: process.env.CI ? 2 : 0,
+
+  /* Limit workers on CI to avoid resource conflicts.
+     Locally, use undefined to let Playwright decide. */
+  workers: process.env.CI ? 1 : undefined,
+
+  /* Reporter to use: 'html' generates a visual report */
+  reporter: 'html',
+
+  /* Shared settings for all test projects */
+  use: {
+    /* Base URL to use in actions like `await page.goto('')`.
+       Uncomment and set if all tests use the same domain. */
+    // baseURL: 'http://localhost:3000',
+
+    /* Collect trace when retrying the failed test.
+       Traces help debug failures. See https://playwright.dev/docs/trace-viewer */
+    trace: 'on-first-retry',
+  },
+
+  /* Configure projects for different browsers */
+  projects: [
+    {
+      // Test configuration for Google Chrome desktop browser
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+
+    // {
+    //   // Test configuration for Mozilla Firefox desktop browser
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+
+    // {
+    //   // Test configuration for Apple Safari desktop browser
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+
+    /* Test against mobile viewports. */
+    // {
+    //   name: 'Mobile Chrome',
+    //   use: { ...devices['Pixel 5'] },
+    // },
+    // {
+    //   name: 'Mobile Safari',
+    //   use: { ...devices['iPhone 12'] },
+    // },
+
+    /* Test against branded browsers. */
+    // {
+    //   name: 'Microsoft Edge',
+    //   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+    // },
+    // {
+    //   name: 'Google Chrome',
+    //   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+    // },
+  ],
+
+  /* Run your local dev server before starting the tests.
+     Uncomment and configure if you need to start a local server for testing. */
+  // webServer: {
+  //   command: 'npm run start',           // Command to start the server
+  //   url: 'http://localhost:3000',       // URL to wait for before running tests
+  //   reuseExistingServer: !process.env.CI, // Reuse server if already running (not on CI)
+  // },
+});
+

package/src/core/autoHeal.js

@@ -0,0 +1,111 @@
+/**
+ * Auto-Healing Utilities Module
+ * This module contains functions for automatically finding alternative elements
+ * when a selector fails. It extracts keywords from selectors and searches the DOM
+ * for similar elements that might be the intended target.
+ */
+
+/**
+ * Extracts meaningful keywords from a selector string for auto-healing.
+ * Supports both CSS and XPath selectors by parsing them differently.
+ * @param {string} selector - The CSS or XPath selector to analyze
+ * @returns {string[]} Array of lowercase keywords extracted from the selector
+ */
+function extractKeywords(selector) {
+  // Check if this is an XPath selector (starts with / or //)
+  if (selector.startsWith('/') || selector.startsWith('//')) {
+    // XPath parsing logic
+    const keywords = [];
+
+    // Extract tag names like 'input', 'button' from //tagName
+    const tagMatch = selector.match(/\/\/(\w+)/);
+    if (tagMatch) keywords.push(tagMatch[1]);
+
+    // Extract attribute values like @id='username' -> 'username'
+    const attrMatches = selector.match(/@[\w-]+='([^']+)'/g);
+    if (attrMatches) {
+      attrMatches.forEach(match => {
+        const value = match.match(/'([^']+)'/)?.[1];
+        if (value) keywords.push(value);
+      });
+    }
+
+    // Extract text content like text()='Submit' -> 'Submit'
+    const textMatch = selector.match(/text\(\)='([^']+)'/);
+    if (textMatch) keywords.push(textMatch[1]);
+
+    // Convert all keywords to lowercase for case-insensitive matching
+    return keywords.map(word => word.toLowerCase());
+  } else {
+    // CSS parsing logic
+    return selector
+      .replace(/[#._-]/g, ' ')  // Replace special chars with spaces
+      .split(' ')               // Split into words
+      .filter(Boolean)          // Remove empty strings
+      .map(word => word.toLowerCase()); // Convert to lowercase
+  }
+}
+
+/**
+ * Finds candidate elements in the DOM that match the extracted keywords.
+ * Searches for elements likely to be interactive based on the intended action.
+ * @param {Page} page - The Playwright page object
+ * @param {string[]} keywords - Keywords extracted from the failed selector
+ * @param {string} [action='click'] - The intended action ('click' or 'fill') to optimize search
+ * @returns {Locator[]} Array of candidate element locators, sorted by relevance
+ */
+async function findCandidates(page, keywords, action = 'click') {
+  let selector;
+
+  // Choose different element types based on the intended action
+  if (action === 'fill') {
+    // For filling, look for input elements that can receive text
+    selector = 'input, textarea, select';
+  } else {
+    // For clicking, look for clickable elements
+    selector = 'button, a, input[type="button"], input[type="submit"]';
+  }
+
+  // Get all matching elements on the page
+  const elements = await page.locator(selector).all();
+
+  const matches = [];
+
+  // Evaluate each element to see how well it matches our keywords
+  for (const el of elements) {
+    // Get the visible text content (if any)
+    const text = (await el.innerText().catch(() => '')).toLowerCase();
+    // Get the aria-label attribute (if any)
+    const aria = (await el.getAttribute('aria-label') || '').toLowerCase();
+    // Get the name attribute (common for form inputs)
+    const name = (await el.getAttribute('name') || '').toLowerCase();
+    // Get the id attribute
+    const id = (await el.getAttribute('id') || '').toLowerCase();
+    // Get the placeholder attribute (for inputs)
+    const placeholder = (await el.getAttribute('placeholder') || '').toLowerCase();
+
+    let score = 0; // Relevance score for this element
+
+    // Check each keyword against various element properties
+    for (const key of keywords) {
+      if (text.includes(key)) score += 2;        // Text content is most important
+      if (aria.includes(key)) score += 1;       // ARIA label is helpful
+      if (name.includes(key)) score += 1;       // Name attribute
+      if (id.includes(key)) score += 1;         // ID attribute
+      if (placeholder.includes(key)) score += 1; // Placeholder text
+    }
+
+    // If the element has any matching keywords, add it to candidates
+    if (score > 0) {
+      matches.push({ el, score });
+    }
+  }
+
+  // Sort candidates by score (highest first) and return just the elements
+  matches.sort((a, b) => b.score - a.score);
+
+  return matches.map(m => m.el);
+}
+
+// Export the functions for use in other modules
+export { extractKeywords, findCandidates };

package/src/core/healer.js

@@ -0,0 +1,70 @@
+/**
+ * Core Healing Logic Module
+ * This module contains the fundamental healing algorithms used by both regular and auto modes.
+ * It handles the process of trying multiple locators until one works.
+ */
+
+// Import functions for resolving locators and detecting selector types
+import { resolveLocator, detectSelectorType } from './strategies.js';
+// Import logging utility
+import { log } from './logger.js';
+
+/**
+ * Core healing function that tries multiple locators in sequence.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} options - Healing configuration
+ * @param {string} options.primary - The primary selector to try first
+ * @param {Array} options.fallbacks - Array of fallback selector configurations
+ * @param {number} [options.timeout=2000] - Timeout in ms for each locator attempt
+ * @param {boolean} [options.log=true] - Whether to enable logging
+ * @returns {Locator} The first working locator found
+ * @throws {Error} If no locators work
+ */
+async function regularHeal(page, options) {
+  // Extract configuration options with default values
+  const {
+    primary,        // The main selector to try
+    fallbacks = [], // Additional selectors to try if primary fails
+    timeout = 2000, // How long to wait for each selector
+    log: enableLog = true // Whether to show progress logs
+  } = options;
+
+  // Create an array of all locator attempts, starting with the primary
+  // Automatically detect if primary is CSS or XPath
+  const attempts = [
+    { type: detectSelectorType(primary), value: primary },
+    ...fallbacks // Add all fallback locators
+  ];
+
+  // Try each locator in order until one works
+  for (let attempt of attempts) {
+    try {
+      // Log which locator we're trying
+      log(`Trying: ${JSON.stringify(attempt)}`, enableLog);
+
+      // Convert the locator configuration to a Playwright locator
+      const locator = resolveLocator(page, attempt);
+
+      // Wait for the element to be visible (this will throw if not found/visible)
+      await locator.waitFor({
+        state: 'visible',
+        timeout
+      });
+
+      // Success! Log and return the working locator
+      log(`✅ Success`, enableLog);
+
+      return locator;
+
+    } catch (err) {
+      // This locator failed, log the failure and try the next one
+      log(`❌ Failed`, enableLog);
+    }
+  }
+
+  // All locators failed, throw an error with details
+  throw new Error('Regular mode failed: All locators failed');
+}
+
+// Export the main healing function
+export { regularHeal };

package/src/core/logger.js

@@ -0,0 +1,21 @@
+/**
+ * Logging Utility Module
+ * Provides a simple logging function for the healing process.
+ * All log messages are prefixed with '[Healing]' for easy identification.
+ */
+
+/**
+ * Logs a message to the console if logging is enabled.
+ * @param {string} message - The message to log
+ * @param {boolean} [enabled=true] - Whether to actually log the message
+ */
+function log(message, enabled = true) {
+  // Only log if logging is enabled (default is true)
+  if (enabled) {
+    // Prefix all messages with '[Healing]' for easy filtering
+    console.log(`[Healing] ${message}`);
+  }
+}
+
+// Export the logging function
+export { log };

package/src/core/strategies.js

@@ -0,0 +1,64 @@
+/**
+ * Locator Strategies Module
+ * This module handles different types of element selectors and converts them
+ * to Playwright locators. It supports CSS, XPath, text, ARIA labels, and roles.
+ */
+
+/**
+ * Detects the type of selector string (CSS or XPath).
+ * @param {string} selector - The selector string to analyze
+ * @returns {string} 'xpath' if it starts with '/' or '//', otherwise 'css'
+ */
+function detectSelectorType(selector) {
+  // XPath selectors always start with '/' or '//'
+  if (selector.startsWith('/') || selector.startsWith('//')) {
+    return 'xpath';
+  }
+  // Default to CSS for all other selectors
+  // Could be extended to detect other types like data-testid, etc.
+  return 'css';
+}
+
+/**
+ * Converts a strategy configuration to a Playwright locator.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} strategy - The locator strategy configuration
+ * @param {string} strategy.type - The type of locator ('css', 'xpath', 'text', 'aria', 'role')
+ * @param {string} strategy.value - The selector value
+ * @param {string} [strategy.name] - For role strategies, the accessible name
+ * @returns {Locator} A Playwright locator object
+ * @throws {Error} If the strategy type is not supported
+ */
+function resolveLocator(page, strategy) {
+  // Use a switch statement to handle different locator types
+  switch (strategy.type) {
+    case 'css':
+      // Standard CSS selector like '#id', '.class', 'input[type="text"]'
+      return page.locator(strategy.value);
+
+    case 'xpath':
+      // XPath selector like '//input[@id="username"]'
+      return page.locator(strategy.value);
+
+    case 'text':
+      // Find element by its visible text content
+      return page.getByText(strategy.value);
+
+    case 'aria':
+      // Find element by its aria-label attribute
+      return page.getByLabel(strategy.value);
+
+    case 'role':
+      // Find element by ARIA role and accessible name
+      return page.getByRole(strategy.value, {
+        name: strategy.name // The accessible name for the role
+      });
+
+    default:
+      // Unknown strategy type, throw an error with details
+      throw new Error(`Unsupported strategy: ${JSON.stringify(strategy)}`);
+  }
+}
+
+// Export the functions for use in other modules
+export { resolveLocator, detectSelectorType };

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * Main entry point for the Playwright Healing Locators library.
+ * This library provides self-healing locator strategies for Playwright tests,
+ * allowing tests to automatically find alternative selectors when the primary one fails.
+ */
+
+// Import the regular healing mode module, which provides fill and click methods with fallback support
+import * as regular from './modes/regular.js';
+
+// Import the auto-healing mode module, which provides intelligent self-healing without manual fallbacks
+import * as auto from './modes/auto.js';
+
+// Export the healing modules with descriptive names
+// regularHeal: Use this for tests where you want to specify fallback locators manually
+// autoHeal: Use this for tests where you want automatic healing based on element analysis
+export { regular as regularHeal, auto as autoHeal };

package/src/modes/auto.js

@@ -0,0 +1,98 @@
+/**
+ * Auto-Healing Mode Module
+ * This module provides intelligent, automatic healing for Playwright locators.
+ * When a selector fails, it analyzes the selector to extract keywords and finds
+ * similar elements on the page that might be the intended target.
+ */
+
+// Import the core healing function for basic locator resolution
+import { regularHeal } from '../core/healer.js';
+// Import functions for keyword extraction and candidate finding
+import { extractKeywords, findCandidates } from '../core/autoHeal.js';
+// Import logging utility for debugging and progress tracking
+import { log } from '../core/logger.js';
+
+/**
+ * Core auto-healing logic that tries to find a working locator automatically.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} options - Configuration object
+ * @param {string} options.primary - The failed selector to analyze
+ * @param {number} [options.timeout=2000] - Timeout for element waiting
+ * @param {boolean} [options.log=true] - Whether to log healing process
+ * @param {string} [action='click'] - The intended action ('click' or 'fill') to optimize candidate search
+ * @returns {Locator} A working Playwright locator
+ * @throws {Error} If no suitable element can be found
+ */
+async function autoHealLocator(page, options, action = 'click') {
+  try {
+    // First, try the primary locator without any fallbacks
+    return await regularHeal(page, { ...options, fallbacks: [] });
+
+  } catch (err) {
+    // Primary locator failed, start auto-healing process
+    log('🤖 Auto-healing started...', options.log);
+
+    // Extract meaningful keywords from the failed selector
+    const keywords = extractKeywords(options.primary);
+    log(`Keywords: ${keywords.join(', ')}`, options.log);
+
+    // Find potential matching elements based on the keywords
+    const candidates = await findCandidates(page, keywords, action);
+
+    // Try the top candidates (limited to 4 attempts to avoid too many tries)
+    for (let i = 0; i < candidates.length; i++) {
+      if (i > 3) break; // Limit attempts to prevent excessive waiting
+
+      try {
+        const el = candidates[i];
+
+        // Wait for the candidate element to be visible
+        await el.waitFor({
+          state: 'visible',
+          timeout: 2000
+        });
+
+        // Success! Log and return the working element
+        log(`✅ Auto-healed using candidate ${i + 1}`, options.log);
+
+        return el;
+
+      } catch (e) {
+        // This candidate didn't work, try the next one
+        log(`❌ Candidate ${i + 1} failed`, options.log);
+      }
+    }
+
+    // All candidates failed, throw an error
+    throw new Error('Auto-healing failed: No suitable element found');
+  }
+}
+
+/**
+ * Performs a click action using auto-healing strategy.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} options - Configuration object with primary selector
+ */
+async function click(page, options) {
+  const locator = await autoHealLocator(page, options, 'click');
+  await locator.click();
+}
+
+/**
+ * Performs a fill action using auto-healing strategy.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} options - Configuration object with primary selector
+ * @param {string} options.primary - The selector to try (will auto-heal if it fails)
+ * @param {number} [options.timeout=2000] - Timeout for element waiting
+ * @param {boolean} [options.log=true] - Whether to log the healing process
+ * @param {string} value - The text value to fill into the input field
+ */
+async function fill(page, options, value) {
+  // Use the auto-healing locator function with 'fill' action for optimization
+  const locator = await autoHealLocator(page, options, 'fill');
+  // Fill the input field with the provided value
+  await locator.fill(value);
+}
+
+// Export the functions for use in other modules
+export { click, fill };

package/src/modes/regular.js

@@ -0,0 +1,44 @@
+/**
+ * Regular Healing Mode Module
+ * This module provides manual fallback-based healing for Playwright locators.
+ * When a primary selector fails, it tries a series of fallback selectors in order.
+ */
+
+// Import the core healing function that handles the logic of trying selectors
+import { regularHeal } from '../core/healer.js';
+
+/**
+ * Performs a click action using regular healing strategy.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} options - Configuration object containing primary selector and fallbacks
+ * @param {string} options.primary - The main CSS or XPath selector to try first
+ * @param {Array} options.fallbacks - Array of fallback selector objects with type and value
+ * @param {number} [options.timeout=2000] - Timeout in milliseconds for each selector attempt
+ * @param {boolean} [options.log=true] - Whether to log healing attempts to console
+ */
+async function click(page, options) {
+  // Call the core healing function to get a working locator
+  const locator = await regularHeal(page, options);
+  // Perform the click action on the found locator
+  await locator.click();
+}
+
+/**
+ * Performs a fill action using regular healing strategy.
+ * @param {Page} page - The Playwright page object
+ * @param {Object} options - Configuration object containing primary selector and fallbacks
+ * @param {string} options.primary - The main CSS or XPath selector to try first
+ * @param {Array} options.fallbacks - Array of fallback selector objects with type and value
+ * @param {number} [options.timeout=2000] - Timeout in milliseconds for each selector attempt
+ * @param {boolean} [options.log=true] - Whether to log healing attempts to console
+ * @param {string} value - The text value to fill into the input field
+ */
+async function fill(page, options, value) {
+  // Call the core healing function to get a working locator
+  const locator = await regularHeal(page, options);
+  // Fill the input field with the provided value
+  await locator.fill(value);
+}
+
+// Export the functions so they can be used by other modules
+export { click, fill };