chiragx7/selector-healer

Selector Healer

Catch broken Playwright selectors before CI does. Selector Healer statically scans your test files, verifies each selector against the live DOM, and — when a UI change breaks a selector — suggests (or auto-applies) an AST-based fix. Everything runs on your machine: no network calls beyond your own app, no telemetry.

• 🩹 Heals broken selectors — scores live DOM candidates against a stored fingerprint and proposes ranked replacements.
• ⚡ 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.
• 🖥️ Three surfaces — a core library, the selector-healer CLI (CI / pre-commit), and a VS Code extension.
• 🔒 Local-first — AST-only edits via recast + Babel (never regex on your source); nothing leaves your machine.

Quick Start

# Install
corepack pnpm install

# Initialize in your project
npx selector-healer init

# Edit selector-healer.config.ts with your testDir and baseUrl, then:
npx selector-healer capture    # Baseline fingerprints
npx selector-healer verify     # Check for broken selectors
npx selector-healer verify --fix  # Auto-apply high-confidence fixes
npx selector-healer report     # Generate HTML report

How It Works

• Parse — The parser walks Babel ASTs of your Playwright test files and extracts every page.locator(), getByTestId(), getByRole(), etc.

• Capture — Each selector is resolved against the live DOM using Playwright. A structural fingerprint (tag, attributes, text, parent chain, sibling index) is stored in .selector-healer/fingerprints.json.

• Verify — Re-runs each selector against the current DOM. If a selector no longer matches, it's flagged as broken.

• Heal — For broken selectors, the healer scans the DOM for candidates matching the stored fingerprint using a 7-rule weighted scoring engine (data-testid, id, role, tag, text, parent structure, sibling position). Returns up to 3 ranked replacement suggestions.

Packages

| Package | Description | |---|---| | @selector-healer/core | Framework-agnostic library: parser, fingerprint, verifier, healer. | | @selector-healer/cli | selector-healer CLI binary for terminal and CI. | | vscode-extension | VS Code extension with diagnostics, code actions, and status bar. |

CLI Commands

| Command | Description | |---|---| | selector-healer init | Detect framework, base URL, test dir, login + pages; write a ready-to-use config | | selector-healer capture | Parse test files and capture DOM fingerprints | | selector-healer verify | Verify selectors against live DOM, show healing suggestions | | selector-healer verify --fix | Auto-apply suggestions above the auto-apply threshold | | selector-healer report | Generate a self-contained HTML report |

Options

• -v, --verbose — Show detailed output including per-selector errors
• --fail-on-warning — Exit 1 on ambiguous (multiple-match) selectors
• -o, --output <path — Report output path (default: .selector-healer/report.html)

Configuration

Run selector-healer init to generate a config automatically — it detects your framework, base URL, test directory, and login flow. Or write selector-healer.config.ts by hand: