🧠 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

npm install pw-autoheal

Or with Bun:

bun add pw-autoheal

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

🛠 Setup

Add .env to your project root:

OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

🚀 Basic Usage

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' }, '[email protected]')

  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