Get Started | Healwright

01 Installation

$ npm install healwright

02 Configuration

Set your API key and choose your provider — OpenAI, Anthropic, Google, or use a local LLM via Ollama.

                  
                  
                  
                  .env
                

                  # OpenAI (default, or AI_PROVIDER="gpt")
export AI_API_KEY="your-openai-key"
export AI_MODEL="gpt-5-nano"
export SELF_HEAL=1

# Anthropic (AI_PROVIDER="anthropic" or "claude")
export AI_PROVIDER="anthropic"
export AI_API_KEY="your-anthropic-key"
export AI_MODEL="claude-sonnet-4-20250514"
export SELF_HEAL=1

# Google (AI_PROVIDER="google" or "gemini")
export AI_PROVIDER="google"
export AI_API_KEY="your-google-key"
export AI_MODEL="gemini-2.5-flash"
export SELF_HEAL=1

# Local LLM via Ollama (AI_PROVIDER="local" or "ollama") — no API key needed!
export AI_PROVIDER="local"
export AI_MODEL="gemma3:4b"
export SELF_HEAL=1
# Recommended: gemma3:4b or mistral (best accuracy for local models)
# export AI_MODEL="mistral"       # fast and reliable
# export AI_MODEL="llama3.2:1b"   # ultra-light for CI
                

03 Setup Fixture

Create a fixture to wrap your Playwright page with self-healing powers.

                  
                  fixtures.ts
                
                  import { test as base } from '@playwright/test';
import { createHealingFixture, HealPage } from 'healwright';

export const test = base.extend<{ page: HealPage }>(createHealingFixture());
export { expect } from '@playwright/test';

04 Write Your First Test

Use the wrapped page in your tests. If a selector breaks, AI fixes it automatically.

                  
                  login.spec.ts
                
                  import { test, expect } from './fixtures';

test('login flow', async ({ page }) => {
  await page.goto('https://example.com');

  // If this selector breaks, AI will find the right element
  await page.heal.click(
    page.locator('[data-testid="submit-btn"]'),
    'Submit button on form'
  );

  // Or skip the selector entirely — AI-only mode
  await page.heal.fill('', 'Email input field', 'user@example.com');
});

05 Available Methods

All healing methods accept a locator (or empty string for AI-only) and a description.

Method	What it does
`heal.locator(selector, desc)`	Chainable self-healing locator
`heal.click(loc, desc, {force?})`	Click (force: true for hidden elements)
`heal.fill(locator, desc, value)`	Fill an input field
`heal.selectOption(locator, desc, value)`	Select from a dropdown
`heal.check(locator, desc)`	Check a checkbox
`heal.uncheck(locator, desc)`	Uncheck a checkbox
`heal.dblclick(locator, desc)`	Double-click an element
`heal.hover(locator, desc)`	Hover over an element
`heal.focus(locator, desc)`	Focus an element

06 AI-Only Mode

Pass an empty string as the locator and let AI find the element from your description alone.

                  
                  example.spec.ts
                
                  await page.heal.click('', 'Login button');
await page.heal.fill('', 'Search input', 'my query');

07 Cache Configuration

Healed selectors are cached in .self-heal/. Add it to your .gitignore:

                  
                  .gitignore
                
                  # Healed selector cache
.self-heal/