🩹 Self-Healing Locator Agent

Free, offline-first, AI-powered self-healing element locator for Playwright & Selenium.

No paid APIs required. No internet required. Zero cost.

🎯 The Problem

Test locators break when UI changes. Traditional self-healing tools like autoheal-locator depend on paid AI APIs ($750+/month), require internet, and add 2–15 seconds per heal.

💡 Our Solution: 3-Layer Healing

| Layer | What | Cost | Speed | Internet? | |-------|------|------|-------|-----------| | Layer 1 | Weighted attribute scoring | $0 | <50ms | ❌ No | | Layer 2 | Local LLM (Ollama) | $0 | 1–3s | ❌ No | | Layer 3 | Cloud AI (Gemini free tier) | $0 | 2–5s | ✅ Optional |

Layer 1 handles ~90% of healing cases in under 50ms with zero cost.

🚀 Quick Start

Playwright

import { test } from '@playwright/test';
import { SelfHealingLocator } from 'self-healing-locator-agent';

test('login test', async ({ page }) => {
  const healer = new SelfHealingLocator(page);

  await page.goto('https://www.saucedemo.com/');

  // These selectors are WRONG — they'll be healed automatically!
  await healer.type('input[data-test="username-wrong"]', 'standard_user', 'Username field');
  await healer.type('input[data-test="password-broken"]', 'secret_sauce', 'Password field');
  await healer.click('input[data-test="login-btn"]', 'Login button');

  // Generate healing report
  await healer.shutdown();
});

Selenium

import { Builder, Browser } from 'selenium-webdriver';
import { SelfHealingLocator } from 'self-healing-locator-agent';

const driver = await new Builder().forBrowser(Browser.CHROME).build();
const healer = new SelfHealingLocator(driver, { framework: 'selenium' });

await driver.get('https://www.saucedemo.com/');
await healer.type('input[data-test="username-wrong"]', 'standard_user', 'Username field');
await healer.click('input[data-test="login-btn"]', 'Login button');

await healer.shutdown();
await driver.quit();

📦 Installation

npm install self-healing-locator-agent

That's it! No build step needed.

Optional: Install Ollama for Layer 2 (Free Local AI)

# Windows
winget install Ollama.Ollama

# Mac
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model (one-time, ~4GB)
ollama pull qwen2.5-coder:7b

⚙️ Configuration

Zero configuration needed — defaults work out of the box. Customize if you want:

const healer = new SelfHealingLocator(page, {
  heuristic: {
    enabled: true,
    confidenceThreshold: 70,    // Minimum score to accept (0-100)
    maxCandidates: 200,         // Max DOM elements to scan
  },
  localLLM: {
    enabled: true,              // Auto-disabled if Ollama not installed
    baseUrl: 'http://localhost:11434',
    model: 'qwen2.5-coder:7b',
  },
  cloudAI: {
    enabled: false,             // Opt-in only
    provider: 'gemini',
    apiKey: process.env.GEMINI_API_KEY,
  },
  cache: {
    persistToFile: true,        // Cache survives restarts
    ttlMs: 7 * 24 * 60 * 60 * 1000, // 7 days
  },
  reporting: {
    generateHtml: true,         // Beautiful HTML reports
    consoleLogging: true,       // Console output
  },
});

📊 Reports

After each test run, a report is generated at self-heal-reports/:

• HTML Report — Beautiful dark-themed dashboard with healing statistics
• JSON Report — Machine-readable for CI/CD integration

Reports include:

• ✅ Successfully healed selectors (with action-needed warnings)
• ❌ Failed healing attempts
• 📈 Statistics: confidence, speed, layer breakdown
• ⏱️ Estimated time saved

🏗️ Architecture

Test Code
  │
  ├── healer.find('#broken-selector', 'Login button')
  │
  ▼
┌─────────────────────────────────────────────────┐
│         Self-Healing Locator Agent               │
│                                                  │
│  1. Try original selector ──── Found? → Return   │
│  2. Check cache ───────────── Hit? → Return      │
│  3. Layer 1: Heuristic ────── Score>70%? → Cache  │
│  4. Layer 2: Ollama LLM ──── Works? → Cache      │
│  5. Layer 3: Cloud AI ─────── Works? → Cache      │
│  6. All failed ────────────── Throw Error         │
└─────────────────────────────────────────────────┘

📁 Project Structure

src/
├── core/
│   ├── types.ts               # All shared types & interfaces
│   ├── SelfHealingLocator.ts  # Main public API
│   └── HealingOrchestrator.ts # 3-layer coordination
├── fingerprint/
│   └── FingerprintCollector.ts # DOM element fingerprinting
├── layers/
│   ├── HeuristicMatcher.ts    # Layer 1: Free, offline, <50ms
│   ├── LocalLLMHealer.ts      # Layer 2: Free, offline (Ollama)
│   └── CloudAIHealer.ts       # Layer 3: Optional cloud AI
├── adapters/
│   ├── PlaywrightAdapter.ts   # Playwright integration
│   └── SeleniumAdapter.ts     # Selenium WebDriverJS integration
├── cache/
│   └── HealingCache.ts        # In-memory + persistent JSON cache
├── reporting/
│   └── HealingReporter.ts     # HTML/JSON/Console reports
├── config/
│   └── defaults.ts            # Default configuration
└── index.ts                   # Barrel exports

🆚 Comparison with autoheal-locator

| Feature | autoheal-locator | Self-Healing Locator Agent | |---------|-----------------|---------------------------| | Cost | $750–2250/month | $0 | | Offline | ❌ No | ✅ Yes | | Speed (per heal) | 2–15s | <50ms (Layer 1) | | Security | Full DOM sent to cloud | Data stays local | | Deterministic | ❌ Non-deterministic | ✅ Layer 1 is deterministic | | Language | Java only | TypeScript | | Frameworks | Selenium + Playwright (Java) | Playwright + Selenium (JS/TS) | | Wrong-element prevention | ❌ None | ✅ Confidence thresholds | | Root cause masking | ❌ Silent healing | ✅ Warning + action needed |

📄 License

MIT