Get started Get started Get started

1Install

Add healwright to the project that holds your Playwright tests, with the SDK for your provider. OpenAI is the default.

Using another provider? Install its SDK instead: @anthropic-ai/sdk, @google/genai, @typesafe-ai/sdk or ollama. If it's missing, the first heal tells you the exact command to run.

2Pick a provider

Healing stays off until SELF_HEAL=1, so your suite runs exactly as before until you turn it on. healwright reads environment variables: set them in CI, or load a .env file with import 'dotenv/config' at the top of playwright.config.ts.

SELF_HEAL=1
AI_PROVIDER=openai
AI_API_KEY=sk-…
# AI_MODEL=…   optional, overrides the default model

SELF_HEAL=1
AI_PROVIDER=anthropic
AI_API_KEY=sk-ant-…
# AI_MODEL=…   optional, overrides the default model

SELF_HEAL=1
AI_PROVIDER=google
AI_API_KEY=…
# AI_MODEL=…   optional, overrides the default model

SELF_HEAL=1
AI_PROVIDER=typesafe
TYPESAFE_API_KEY=…
# Jev picks one of the collected elements; healwright builds the locator.

SELF_HEAL=1
AI_PROVIDER=local
# No API key. Page content never leaves your machine.
# OLLAMA_HOST=http://127.0.0.1:11434   the default
# AI_MODEL=gemma3:4b                   the default; mistral also works well

Behind a gateway? AI_BASE_URL points any built-in provider at Azure, OpenRouter, vLLM or LiteLLM. For a model healwright has no client for, pass your own with the aiProvider option.

3Add the fixture

Wrap the page fixture once. Every test that imports test from this file gets page.heal; everything else on page works as usual.

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';

4Write a test

Each page.heal action takes a selector and a description. The selector runs first; the description is what the model looks for when the selector stops matching. Leave the selector empty and the description is enough.

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

test('customer can check out', async ({ page }) => {
  await page.goto('https://shop.example/checkout');

  // No selector: the description is enough
  await page.heal.fill('', 'Email field', 'ada@example.com');

  // The selector runs first; the description takes over if it breaks
  await page.heal.click('#buy-now', 'Place order button');

  await expect(page.getByText('Order confirmed')).toBeVisible();
});

Describe elements the way you'd point them out to a colleague: "Place order button", not "button". The model has only your words and the page to go on.

5Run it

While your selectors match, nothing changes and tests run at full speed. When one breaks, the heal shows up in the output. The next run reads the fix from the cache and doesn't call the model.

$ SELF_HEAL=1 npx playwright test

  ✦ healwright
  │
  ├─ ⚡︎ CLICK Place order button
  │  ⬡ analyzing 14 elements... (filtered from 63)
  │  ↳ received 412 chars
  │
  ├─ ✓ Place order button
  │  → getByRole("button", { name: "Place order" })
  │  ↑ 1180 input · 96 output · 1276 total tokens
  └──────────────────────────────
  ✓ checkout.spec.ts › customer can check out (2.8s)

6Keep it honest

A heal that lands on the wrong element still passes. These three settings decide how far the model is trusted and keep every heal visible. You can try them on the home page.

minConfidence

Fail the action instead of guessing when the model's confidence is below this score (0 to 1).

mode: 'warn'

Report what would have healed and keep the original failure. Use it in CI to see how far your selectors have drifted.

getHealSummary()

Count every heal in the run, so global teardown can fail the build and list the selectors to fix.

export const test = base.extend<{ page: HealPage }>(
  createHealingFixture({
    minConfidence: 0.8,
    mode: process.env.CI ? 'warn' : 'heal',
  })
);

// playwright.config.ts: globalTeardown: './global-teardown.ts'
import { getHealSummary } from 'healwright';

export default function () {
  const { healed, entries } = getHealSummary();
  if (healed === 0) return;

  console.error(`${healed} locator(s) needed healing. Update these selectors:`);
  for (const e of entries.filter((e) => e.outcome === 'healed')) {
    console.error(`  ${e.action} "${e.contextName}"`);
  }
  process.exitCode = 1;
}

Running Playwright in UI or watch mode? Call resetHealSummary() from globalSetup so each run starts at zero.

7Cache and logs

healwright keeps three files in .self-heal/.

.self-heal/heal_events.jsonl
.self-heal/heal_summary.jsonl
.self-heal/*.lock
.self-heal/*.tmp
# Or keep heals local to each machine instead:
# .self-heal/