chiragx7/selector-healer

<div align="center"

<img src="docs/assets/hero.svg" alt="Selector Healer - catch broken test selectors before CI does" width="900" /

&nbsp;

Catch broken test selectors before CI does - for Playwright, Cypress, WebdriverIO & TestCafe. Selector Healer verifies each selector against your live DOM, shows why it broke, and applies AST-based fixes - from the CLI or a local-first VS Code dashboard. Nothing leaves your machine.

</div

---

• 🩹 Heals broken selectors - scores live-DOM candidates against a stored fingerprint and proposes ranked, explainable replacements.
• 🧠 Learns from your choices - remembers which kinds of fix you Apply vs Skip and gently nudges future suggestions toward your preference (bounded, fully local, and never enough to change an auto-apply).
• 📊 Analytics dashboard - a VS Code Overview with selector health, a robustness gauge, health-over-time, composition, and per-page breakdowns.
• ⚡ Shift-left - catches breakage at commit time (pre-commit or in your editor), not at 09:00 the next morning in CI.
• 🧭 Near-zero config - init auto-detects your framework, base URL, test directory, and even the login flow and pages.
• 🔒 Local-first - AST-only edits via recast + Babel (never regex on your source); no network beyond your own app, no telemetry.

Quick start

# Install (pnpm via Corepack)
corepack pnpm install

# Initialize in your project - auto-detects framework, base URL, test dir, login + pages
npx selector-healer init

# Then:
npx selector-healer capture       # Baseline: fingerprint every selector against the live DOM
npx selector-healer verify        # Check for broken selectors + see healing suggestions
npx selector-healer verify --fix  # Auto-apply high-confidence fixes
npx selector-healer report        # Generate a self-contained HTML report

How it works

• Parse - walks the Babel AST of your test files (Playwright, Cypress, WebdriverIO, TestCafe) and extracts every selector call: getByTestId(), getByRole(), page.locator(), cy.get(), …
• Capture - resolves each selector against the live DOM and stores a structural fingerprint (tag, attributes, text, parent chain, sibling index, page URL) in .selector-healer/fingerprints.json - committed to git, so the baseline travels with your code.
• Verify - re-runs each selector against the current DOM: zero matches = broken, many = ambiguous.
• Heal - for broken selectors, scores DOM candidates against the stored fingerprint with a 10-rule weighted engine (data-testid, id, role, tag, text, class overlap, aria, parent structure, sibling position, attribute coverage) and returns up to three ranked suggestions - each with an inspectable per-rule confidence breakdown.

No LLM, no cloud - the scoring is a deterministic, inspectable engine that runs entirely on your machine.

The VS Code experience

An Overview analytics home ties everything together: overall selector health, a live baseline (with one-click prune of stale fingerprints), a robustness gauge, health-over-time, selector composition, and a per-page breakdown - with persistent tabs to Results, Baseline, and Heal History.

<div align="center"<img src="docs/assets/overview.png" alt="Selector Healer Overview dashboard" width="820" /</div --

• Explainable, previewable heals - why it broke, all ranked candidates side by side, a "Why NN%?" per-rule breakdown, and a diff preview before you Apply.
• Learns from accept/reject - the more you Apply or Skip, the better your suggestions get ranked, each with a "✨ you usually accept X fixes" note. Feedback stays local (or, opt-in, shared with your team) - no network, ever.
• Watch mode - auto re-verify a test file the moment you save it.
• Skip a broken selector to silence it everywhere (list, health, "Heal all", and the editor squiggles/gutter/CodeLens) - restorable, and it returns when you edit the selector.
• Heal History + one-click Undo - every applied fix is reversible.
• Editor integration - Quick Fixes (Ctrl+.), per-selector CodeLens, hover cards, gutter dots + Problems diagnostics, and proactive fragility lint for brittle locators.

• Onboarding - a built-in Get Started walkthrough and a Settings UI.

See the extension README for the full tour.