pw-autoheal/README.md

AI-powered auto-healing for Playwright tests using OpenAI

# 🧠 pw-autoheal

> AI-powered auto-healing for Playwright tests using OpenAI.

**`pw-autoheal`** helps make your end-to-end tests more stable by automatically recovering from broken selectors. When a selector fails (e.g., due to a UI change), this library uses OpenAI to suggest a new one — and retries the action automatically.

---

## ✨ Features

- 🔄 Auto-recovers from broken selectors
- 🧠 Powered by OpenAI (`gpt-3.5-turbo-instruct`)
- 🔧 Works with `click()` and `fill()` (more coming!)
- ⚡ Lightweight and fast (built with Bun + TypeScript)
- 📦 Easy to drop into existing Playwright test suites

---

## 🚀 Installation

```bash
npm install pw-autoheal
```

---

Or with Bun:

```bash
bun add pw-autoheal
```

---

⚠️ Requires you to set an OPENAI_API_KEY in a .env file.

## 🛠 Setup

Add .env to your project root:

```bash
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

---

## 🚀 Basic Usage

```js
import { test } from '@playwright/test'
import { safeClick, safeFill } from 'pw-autoheal'

test('AI auto-heals broken selectors', async ({ page }) => {
  await page.goto('https://example.com')

  await safeFill(page, { type: 'name', value: 'email' }, 'admin@example.com')

  await safeClick(page, {
    type: 'role',
    value: 'button',
    name: 'Submit'
  })
})
```

## 📘 API Reference

### `safeClick(page, locator: LocatorType): Promise<void>`

Attempts to click the element described by the given `locator`.


If it fails:
- Captures the current page's DOM (`page.content()`)
- Captures the ARIA accessibility snapshot (`page.accessibility.snapshot()`)
- Sends both + the failed selector to OpenAI
- Receives a suggested replacement selector
- Retries the `.click()` using the new selector

---

### `safeFill(page, locator: LocatorType, value: string): Promise<void>`

Fills the specified input field.

If the selector fails:
- Same recovery steps as `safeClick`
- After receiving a replacement selector from OpenAI, retries the `.fill()` with the new one

---

### safeFill(page: Page, selector: string, value: string): Promise

Same logic as safeClick, but for input fields.

---

## 🔢 Locator Types

You must pass a structured `LocatorType` object. Supported types:

| Type         | Example Usage                                              |
|--------------|------------------------------------------------------------|
| `testId`     | `{ type: 'testId', value: 'submit-button' }`              |
| `id`         | `{ type: 'id', value: 'email-input' }`                    |
| `name`       | `{ type: 'name', value: 'username' }`                     |
| `placeholder`| `{ type: 'placeholder', value: 'Enter email' }`           |
| `class`      | `{ type: 'class', value: 'primary-btn' }`                 |
| `role`       | `{ type: 'role', value: 'button', name: 'Submit' }`       |

✅ All types are compatible with Playwright’s smart locators under the hood.
✅ You can use any combination of `type` and `value` to create a unique selector.
✅ You can also use `role` with `name` to target ARIA roles.

## 🧠 How It Works

1.  You call `safeClick()` or `safeFill()`

2.  If the selector fails:

    *   Captures `page.content()` (DOM)

    *   Captures `page.accessibility.snapshot()` (ARIA roles)

3.  Sends both + failed selector to OpenAI

4.  Gets a suggested selector

5.  Retries the original action with the suggestion


## ⚠️ Known Limitations


*   Doesn't currently auto-heal inside `expect()` assertions

*   Only supports `click` and `fill` for now

*   Needs OpenAI access + internet

*   Adds ~0.3–1s latency on fallback due to API call


## 🔮 Coming Soon

*   `safeExpect()` with AI-powered fallback

*   Multi-step retries with multiple suggestions

*   Local AI model fallback (offline healing)

*   Selector memory/cache for reusability