healenium-js/README.md

Healenium-style self-healing decorator for Playwright in TypeScript

# Healenium-JS 🧪

A self-healing decorator for Playwright UI tests — inspired by Healenium. Automatically heals broken selectors using fuzzy matching and maintains fallback history.

## ✨ Features

- ✅ Self-heals selectors using fuzzy text-matching
- 📖 Tracks fallback usage and selector history
- 🧩 Decorator-based usage via `@Healenium`
- 🔁 Automatically updates fallback selectors
- 🧰 Written in TypeScript, ready for npm publishing

## 📦 Installation

```bash
npm install healenium-js
```

## 🚀 Usage

### 1. Decorate Failing Selector Method

```ts
import { Healenium } from 'healenium-js';

class MyTests {
  page: Page;

  constructor(page: Page) {
    this.page = page;
  }

  @Healenium('#non-existent-button')
  async clickMissingButton() {
    await this.page.click('#non-existent-button');
  }
}
```

### 2. Run Your Playwright Test

```bash
npx playwright test
```

### 3. View Fallback Data

- ✅ `fallback-selectors.json` — latest healed selectors
- 📚 `selector-history.json` — all past fallback selectors

## 🧠 How It Works

- When a selector fails, the plugin:
  1. Extracts its text
  2. Uses Levenshtein distance to find a similar element
  3. Generates a new selector and stores it
  4. Re-runs the test using the new selector

## 🧪 Example Test

```ts
import { test as base } from '@playwright/test';
import { Healenium } from 'healenium-js';

class Demo {
  page: Page;
  constructor(page: Page) {
    this.page = page;
  }

  @Healenium('#broken-selector')
  async triggerHealer() {
    await this.page.click('#broken-selector');
  }
}

base('Healenium demo', async ({ page }) => {
  const t = new Demo(page);
  await page.goto('https://example.com');
  await t.triggerHealer();
});
```

## 📜 License

MIT © [Your Name]