Skip to main content

​
Overview

Auto-Healing is Supatest’s AI-powered feature that automatically repairs tests when locators break due to UI changes. Instead of failing immediately when an element can’t be found, Auto-Healing uses AI to locate the correct element and continue execution.

​
How Auto-Healing Works

​
The Problem

UI changes frequently break tests:
  • Developers update CSS classes
  • Elements get new IDs
  • Page structure changes
  • Text content updates
Without Auto-Healing, these changes cause test failures that require manual fixes.

​
The Solution

When a step fails to find its element: 
1. Step attempts to find element with original locator
   ↓
2. Element not found - step would normally fail
   ↓
3. Auto-Healing activates
   ↓
4. AI analyzes the page using:
   - Step description
   - Original locator
   - Fallback locators
   - Page context
   ↓
5. AI finds the correct element
   ↓
6. Step executes successfully
   ↓
7. Healing suggestion saved for review

​
Enabling Auto-Healing

​
Per-Test Setting

  1. Open test in Editor
  2. Click Settings (gear icon)
  3. Find Auto-Healing toggle
  4. Enable or disable

​
Organization Default

  1. Go to Settings → Organization
  2. Find Default Test Settings
  3. Set Auto-Healing default
  4. Applies to new tests

​
Per-Step Override

Individual steps can override the test setting:
  1. Open step configuration
  2. Find Auto-Healing option
  3. Enable, disable, or use test default

​
What Auto-Healing Uses

When healing a step, AI considers:

​
Step Information

DataHow It Helps
Step typeKnows what kind of element to find (button, input, etc.)
Step descriptionNatural language context
Original locatorStarting point for finding similar elements
Fallback locatorsAlternative selectors to try

​
Page Context

DataHow It Helps
Current URLUnderstands page context
DOM structureFinds elements by structure
Visible textMatches by content
Element attributesIdentifies by properties

​
Historical Data

DataHow It Helps
Previous successful runsKnows what worked before
Healing historyLearns from past repairs
Element patternsRecognizes common UI patterns

​
Runtime Behavior

​
When Auto-Healing Activates

Auto-Healing triggers when:
  1. Primary locator fails to find element
  2. All fallback locators fail
  3. Auto-Healing is enabled for the test/step

​
Execution Flow

Normal Execution:
Step → Find Element → Execute Action → Next Step

With Auto-Healing:
Step → Find Element (fails) → Fallbacks (fail) →
AI Analysis → Find Element → Execute Action → Next Step

​
Performance Impact

ScenarioTime Impact
Element found normallyNo impact
Fallback locator worksMinimal (<1s)
AI healing required2-5 seconds additional

​
Reviewing Healing Suggestions

After a run with Auto-Healing:

​
View Suggestions

  1. Open run results
  2. Look for “Healed” indicator on steps
  3. Click to see healing details

​
Healing Details Show

  • Original locator
  • New locator found by AI
  • Confidence score
  • Element screenshot

​
Accept or Reject

Accept:
  • Updates the step’s primary locator
  • New locator used in future runs
  • Improves test stability
Reject:
  • Keeps original locator
  • AI tries again next run
  • Use when healing was incorrect

​
Bulk Review

For runs with multiple healed steps:
  1. Open run summary
  2. Click Review All Healings
  3. Accept/reject each suggestion
  4. Apply changes

​
Best Practices

​
When to Enable Auto-Healing

Enable for:
  • Tests in active development
  • Pages with frequent UI changes
  • Non-critical test paths
  • Regression suites
Consider disabling for:
  • Tests validating specific elements
  • Critical path tests where any change matters
  • Tests that should fail on UI changes

​
Improve Healing Success

  1. Write good step descriptions 
    ❌ "Click button"
✅ "Click the Submit Order button"
  2. Add fallback locators
    • More alternatives = better healing
    • Use different strategies (CSS, text, role)
  3. Use stable primary locators
    • data-testid attributes
    • Semantic selectors
    • Role-based selectors
  4. Keep tests focused
    • Smaller tests heal more accurately
    • Clear, single-purpose steps

​
Review Healings Regularly

  1. Check healing suggestions weekly
  2. Accept correct healings promptly
  3. Investigate rejected healings
  4. Update source locators when patterns emerge

​
AI Credits

Auto-Healing consumes AI credits:
ActionCredits
Healing attempt1 credit
Successful healing1 credit total
Failed healing1 credit (still consumed)
Monitor credit usage in Settings → AI Credits.

​
Limitations

​
Auto-Healing Cannot

  • Fix logic errors in tests
  • Handle missing pages/features
  • Repair invalid test data
  • Solve authentication issues

​
Healing May Fail When

  • Element was intentionally removed
  • Multiple similar elements exist
  • Page structure completely changed
  • Element requires specific state

​
Troubleshooting

​
Healing Not Activating

  1. Verify Auto-Healing is enabled
  2. Check AI credit balance
  3. Ensure step has locator (not AI Action)

​
Incorrect Healing

  1. Reject the suggestion
  2. Update step description for clarity
  3. Add more specific fallback locators
  4. Consider manual locator update

​
Too Many Healing Attempts

If tests constantly need healing:
  1. Review UI change patterns
  2. Update locators to be more stable
  3. Add data-testid to application
  4. Consider if tests need redesign