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 autoheal
# or
npm install --save-dev autohealAdd @autoheal/interceptor to your playwright.config.ts:
import { defineConfig } from "@playwright/test";
export default defineConfig({
reporter: [
["list"],
["@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 built as a 100% free, community-first open-source alternative to closed-source enterprise test automation tools. We believe world-class QA engineering should be accessible to every solo developer and startup without massive monthly bills.
If AutoHeal-QA saves your team hours of flaky test debugging, please consider supporting ongoing development:
- ⭐ Star this repository on GitHub.
- 💬 Share AutoHeal-QA on Twitter/X, LinkedIn, and Reddit.
- ☕ Sponsor on GitHub Sponsors: Help us keep AutoHeal-QA 100% free and independent.
Distributed under the MIT License. See LICENSE for details.