Locators That Heal Themselves

1What Self-Healing Does

Self-Healing is a first-class subsystem that keeps your Robot Framework suites green when the UI underneath drifts. It is not a regex pass on output.xml — it builds a unique fingerprint for every element your tests touch, then uses similarity scoring to re-find them after changes.

• Fingerprint = identity. Tag + attributes + text + depth + sibling index + parent / grandparent context + child tag bag + preceding/following siblings + SHA-256.
• 10 strategies. Attribute fuzzy match, parent/ancestor search, sibling-relative search, text content match, structural position, fingerprint similarity, CSS fallback, accessibility-id fallback, ML-predicted, visual template.
• Confidence-scored. Every candidate heal carries a 0–1 score; thresholds decide auto-apply vs review vs escalate.
• Persistent. JSON DB at .robogent/healing_locator_db.json — safe to commit.

2How Healing Works

1. You generate a script — every locator gets fingerprinted at generation time.
2. A test run fails on a locator (UI changed).
3. RoboClaw fetches the new page source and runs all enabled strategies in parallel.
4. Each strategy emits a candidate locator + confidence score.
5. The best score is compared against thresholds:
   • ≥ 0.80 → AUTO_HEAL — locator updated in-memory; status HEALED_AUTO
   • 0.50 – 0.80 → MANUAL_REVIEW — queued for human approval
   • < 0.50 → FAILED — marked failed; "Ask Copilot" action surfaced
6. Approved/auto-healed locators feed back into the RAG index for future generations.

3Start the Engine

1. Open the RoboClaw sidebar.
2. Scroll to Step 6: Self-Healing System.
3. Click the green Start button on the hero card.

When the engine is active:

• The card pulses green.
• The 4-stat tile grid (Records · Healthy · Failed · Avg Confidence) starts updating.
• The status bar shows Self-Heal: N records · 0 failed.

To stop:

4The Dashboard

For deep work, open the dedicated dashboard:

The dashboard renders beside your editor with:

• Records table — status pill, confidence bar, heal-count, last-validated, per-row Heal / Ask Copilot actions.
• Filters — status, screen, free-text.
• Settings card — sliders for thresholds + strategy on/off toggles.
• Healing event timeline — last 200 events with timestamp and confidence.
• Import / Export / Clear DB controls.

5output.xml Watcher

Turn on the watcher and RoboClaw reads every Robot Framework run automatically — no manual scan needed.

When enabled:

1. The watcher listens for filesystem changes on **/output.xml in your workspace.
2. On change, it parses failing keywords + their locators.
3. Each failed locator runs through the healing pipeline.
4. Auto-heals are applied; reviews are queued; failures surface in the dashboard.

6Thresholds

All thresholds are tunable from the dashboard Settings card (or via VS Code settings).

7The 10 Healing Strategies

Disable individual strategies from the dashboard Settings card. The engine still runs the rest — confidence scores re-weight automatically.

8Manual Review Queue

Heals in the [0.5, 0.8) band are not applied — they wait for you.

1. Open the Self-Healing Dashboard.
2. Filter by status = HEALED_REVIEW.
3. For each row:
   • Click the candidate locator to copy it.
   • Run Heal to promote to HEALED_AUTO.
   • Run Ask Copilot to open Copilot Chat with the failing context pre-loaded.
   • Run Reject to mark the candidate as wrong (lowers future similarity weight for this record).

9Export Reports

For sprint reviews or audit trails:

You get two files:

• healing_report_<timestamp>.json — machine-readable, full record + event dump.
• healing_report_<timestamp>.txt — human-readable summary: records healed, avg confidence, top 5 most-healed locators, strategies used.

10Troubleshooting

"Records count stays at 0"

Self-Healing only fingerprints elements that pass through RoboClaw's locator engine. If your script was hand-written outside the workflow, run RoboClaw: Self-Healing: Scan Page Source against a captured XML to seed fingerprints.

"Auto-heal updated a locator to the wrong element"

1. Open the dashboard.
2. Find the record, click Reject Last Heal.
3. Bump AUTO_HEAL_THRESHOLD to 0.85 if it keeps happening on this app.

"Watcher doesn't trigger"

• Confirm the toggle is on: RoboClaw: Self-Healing: Toggle output.xml Watcher.
• Make sure your robot ... command writes to a path inside your workspace (e.g. --outputdir Results).

Nuking the DB

Confirms before wiping .robogent/healing_locator_db.json. Export a report first if you want a backup.