Stop manually fixing broken locators after every UI redesign. Heal your Playwright test suites locally with $0 cloud cost.
⚡ Quick Start • ⚖️ Why AutoHeal-QA • 🏗️ Architecture • 📖 Usage Guide • 📚 DevShelf Ecosystem
Flaky tests and UI redesigns waste hundreds of engineering hours every month. Existing self-healing tools either:
- Require expensive cloud subscriptions ($1,000s/mo per seat).
- Leak proprietary DOM snapshots and credentials to 3rd-party LLM APIs.
- Blindly patch source code without verifying if the fix actually passes.
AutoHeal-QA solves this once and for all:
- 100% Free & Local: Deterministic algorithms first ($0, <1ms), with local Ollama models (
qwen2.5-coder,llama3.2) for complex UI rewrites. Zero cloud API tokens required. - Surgical Auto-Patcher: Intelligently updates your actual
.spec.tsfiles while preserving indentation, chaining (.click(),.fill()), and formatting. - Verification Loop: Automatically re-runs the failed test before committing. If the patch fails, it auto-rolls back from backup and tries alternative candidates.
- Safe by Default: Automatically creates
.autoheal-backupsnapshots before modifying disk. Revert anytime withautoheal rollback.
| Feature | AutoHeal-QA | Commercial Cloud QA (Mabl, Testim) | Legacy Plugins (Healenium) |
|---|---|---|---|
| Pricing | 100% Free & Open Source ($0) | $1,200 – $5,000 / month | Free, but requires Docker/DB setup |
| Privacy / Data Security | 100% In-Process & Local | Code & DOM sent to cloud | Local backend required |
| AI Architecture | Multi-Tiered (Heuristics + Local Ollama) | Proprietary Cloud Models | Classical ML (Selenium only) |
| Playwright Native | ✅ Native | ❌ Selenium-centric | |
| Surgical Code Patching | ✅ Modifies source files | ❌ No (cloud dashboard only) | ❌ No (database locator store) |
| Verification Loop | ✅ Auto-verifies before commit | ❌ Manual review | ❌ No auto-verification |
| Instant Rollback | ✅ autoheal rollback |
❌ No | ❌ No |
flowchart TD
A[Playwright Test Fails] --> B[AutoHeal Interception Engine]
B --> C[Page State Harvester: Live AXTree + Pruned DOM]
C --> D{Tier 1: Deterministic Heuristic Engine}
D -->|Confidence >= 85%| G[Surgical Patcher & Diff Preview]
D -->|Ambiguous / Low Confidence| E{Local Ollama Available?}
E -->|Yes| F[Tier 2: Local AI Reasoning - Qwen2.5 / Llama3.2]
E -->|Offline| H[Tier 3: Graceful Heuristic Fallback]
F --> G
H --> G
G --> I[Verification Loop: Re-run Specific Test]
I -->|Passed| J[✅ Commit Patch & Clean Backup]
I -->|Failed| K[🔄 Auto-Rollback from Backup & Try Next Candidate]
pnpm add -D @ritualdev-lab/autoheal @ritualdev-lab/autoheal-interceptor
# or run from source:
git clone https://github.com/RitualDev-Lab/autoheal-qa.git && cd autoheal-qa && pnpm install && pnpm buildAdd @ritualdev-lab/autoheal-interceptor to your playwright.config.ts:
import { defineConfig } from "@playwright/test";
export default defineConfig({
reporter: [
["list"],
["@ritualdev-lab/autoheal-interceptor", { outputFile: "autoheal-failures.json" }],
],
});autoheal testIf any locators break, AutoHeal intercepts the failure and captures the live accessibility snapshot.
autoheal healYou will see an instant colorized diff preview:
[#1/1] Authentication Suite > user logs in successfully
Broken: page.getByRole('button', { name: 'Submit' })
File: tests/auth.spec.ts:14
🔍 Analyzing candidates and finding optimal replacement...
✨ Suggested: page.getByRole('button', { name: 'Sign In to Account' }) (95% confidence) [⚡ Local Heuristics ($0)]
Reason: Matching button with 92% text similarity to name "Sign In to Account"
📋 Proposed Diff Preview:
--- a/tests/auth.spec.ts:14
+++ b/tests/auth.spec.ts:14
@@ -14,1 +14,1 @@
- await page.getByRole('button', { name: 'Submit' }).click();
+ await page.getByRole('button', { name: 'Sign In to Account' }).click();
👉 Apply this patch? [Y]es / [n]o / [a]ll / [q]uit: y
⏳ Verifying patch with Playwright runner...
✅ Verification PASSED: Tests pass with new locator! Committed to auth.spec.ts.| Command | Description |
|---|---|
autoheal test [args...] |
Runs Playwright tests with AutoHeal failure interception active. |
autoheal test --heal |
Runs Playwright and automatically triggers interactive healing if any tests fail. |
autoheal heal |
Interactively reviews failed tests and applies verified patches. |
autoheal heal --yes |
Automatically verifies and applies all patches without interactive prompts (ideal for CI/CD). |
autoheal heal --no-verify |
Applies patches immediately without re-running test verification. |
autoheal report |
Generates a visual standalone HTML dashboard (autoheal-report.html). |
autoheal rollback |
Reverts all .autoheal-backup files across the workspace. |
Whenever tests fail, AutoHeal automatically compiles an interactive, dark-mode visual report:
autoheal reportOpen autoheal-report.html in your browser to view:
- Overview Metrics: Total failures, captured DOM snapshots, running cost ($0.00).
- Comparison Cards: Side-by-side broken locator vs suggested replacement.
- Confidence Meters: Transparent score breakdowns (role matching, string distance, action compatibility).
- Interactive AXTree Inspector: Expandable candidate elements captured at the exact moment of failure.
Clone this repository and run the included interactive demo:
git clone https://github.com/RitualDev-Lab/autoheal-qa.git
cd autoheal-qa
pnpm install
pnpm build
# Run the demo
cd examples/demo-app
pnpm run test:healAutoHeal-QA is a 100% free, local-first open-source test auto-healer. Your sponsorship directly finances multi-browser Playwright test matrix runner hours (Chromium, Firefox, WebKit), local Ollama LLM integration tests, and AST mutation engines.
⚡ 1-Click Dodo Payments Checkout • 🎁 Interactive Donation Form (USD & INR UPI) • ❤️ GitHub Sponsors
🔒 Zero physical shipping required. Powered by Dodo Payments (Merchant of Record) with instant tax invoice and global payment methods (Cards, UPI, Apple Pay).
Distributed under the MIT License. See LICENSE for details.