Quickstart — Local CLI

The same engine CI runs, on your machine. Point e2e-healer at a failing spec and it diagnoses, patches the selector, and re-runs until green. Great for trying it out or fixing a break locally before you push.

:::tip Prefer zero local setup? Most FE/QA teams run e2e-healer entirely in CI. If you just want healed PRs, start with the GitHub Action quickstart — no install required. :::

Install

Requires Python 3.13+ and a Playwright (Node) project in your repo. Install the CLI once, globally:

pipx install ai-driven-e2e
# or, before the PyPI release:
uv tool install git+https://github.com/Lee-Dongwook/E2E-Self-Heal.git

Configure a key

The engine calls an LLM to reason about the diff. Set a provider key via .env:

cp .env.example .env
# set E2E_HEALER_LLM_API_KEY (or your provider's key)

The default provider is NVIDIA NIM (free key, openai/gpt-oss-120b). To use OpenAI, Anthropic, or a local Ollama model instead, see Configuration.

Heal a test

The CLI (Python) reads and rewrites your JS/TS Playwright spec — here's the command alongside the file it operates on:

Engine (CLI)

# Heal one failing test. With no --log, the engine runs the test to capture the failure:
e2e-healer tests/login.spec.ts

# Preview only — run the loop but write nothing to disk:
e2e-healer tests/login.spec.ts --dry-run

Your test (tests/login.spec.ts)

tests/login.spec.ts

import { test, expect } from '@playwright/test';

test('user logs in from the header', async ({ page }) => {
  await page.goto('/');
  await page.click('#login-btn');        // ⛔ id renamed → healer patches this line
  await expect(page).toHaveURL(/\/app/); // ✅ assertion — never touched
});

The engine only ever rewrites the selector/wait line; the expect(...) assertion is out of scope by design.

Heal the whole suite

Run every test, then repair each failing file and print an aggregate summary:

e2e-healer            # no path = whole suite

The CI-style invocation

When scripting (or debugging what CI does), feed a pre-captured log and a PR-scoped diff, and ask for machine-readable output:

e2e-healer tests/login.spec.ts \
  --log playwright.log \
  --diff-base origin/main \
  --json

• Exit code — 0 when the test is healed, non-zero otherwise. CI branches on this.
• --json — prints a machine-readable RepairSummary to stdout (human-readable output goes to stderr), so a wrapper can build a PR body without parsing prose.

See Exit codes & JSON output for the full contract, and the CLI reference for every flag.

Next steps

• Heal vs Review — patch the test, or advise the fix at the source.
• Suite vs single file — whole-suite runs and the CI diff path.
• Live selector verification — catch hallucinated selectors against a running app with --app-url.