Introduction

e2e-healer automatically repairs broken Playwright E2E tests. When a UI change renames or restructures an element and a test's selector stops matching, the engine diagnoses the failure, patches the broken selector, verifies it against the live DOM, and re-runs the test until it's green — as a local CLI or a GitHub Action that opens a patch PR.

The problem

You ship a component change. A className gets renamed, a button id changes, a wrapper <div> moves. Nothing is wrong — but a Playwright selector somewhere no longer matches, and the pipeline goes red:

locator.click: Timeout 5000ms exceeded.
Call log:
  - waiting for locator('#submit-btn')

The test isn't testing anything broken. It's just pointing at an element that moved. Someone now has to read the trace, find the new selector, and push a one-line fix — for every brittle locator, on every PR. e2e-healer does that step for you.

What it does

Before

await page.click('#submit-btn')  // ⛔ times out — id renamed

After

await page.click('#submit')       // ✅ healed, assertion untouched

id changed: #submit-btn → #submit

One renamed selector, patched automatically — and nothing else in the test is touched.

:::warning Scope guardrail The engine only fixes failing locators and wait conditions. It never edits your assertions (expect(...)), test flow, or business logic — enforced at both the prompt and JSON-schema level. Every patch stays small and human-reviewable, so it's safe to run in an enterprise pipeline. :::

Two modes: heal and review

Same diagnosis engine, two outputs — pick per project or per PR:

Mode	What it does	Best when
heal (default)	Patches the broken selector/wait and re-runs until green.	The UI change is intentional and the test just needs to catch up.
review	Posts source-level suggestions as inline PR comments (e.g. "add a data-testid" or "use getByRole"). Never edits the test.	You want to fix the root cause and push the team toward resilient selectors.

See Heal vs Review for how to choose.

Where to go next

• Quickstart — GitHub Action — add self-healing to your PRs in ~5 minutes. No local setup. (Recommended starting point for FE/QA teams.)
• Quickstart — CLI — run the engine locally against a single test or your whole suite.
• Heal vs Review — patch the test, or advise the fix at the source.