--- source_url: "https://help.mabl.com/hc/en-us/articles/19078583792404-How-auto-heal-works" title: How auto-heal works – mabl help mirrored_at: 2026-08-05T03:38:50.806Z host: help.mabl.com cited_in_42a: true mirror_canonical: "https://index.42a.ai/help.mabl.com/hc/en-us/articles/19078583792404-How-auto-heal-works" --- > **Original source:** https://help.mabl.com/hc/en-us/articles/19078583792404-How-auto-heal-works You are probably testing software that changes on a regular basis. Some changes are major and require old tests to be rewritten. But many changes, such as relabeling a button or layout adjustments, are minor. A person might not even notice these changes, but they can easily break automated tests. Auto-heal helps mabl adapt to such changes so your browser tests keep on working through these inevitable changes. This article explains how it works. - [Building an element history](#01JHTX979JNV8A9AH7FVZ2GNHS) - [Looking for element candidates](#01JHTX979M7ZXG0755XCXW4A17) - [Finding a strong match](#01JHTX979NV3MBV1MGY6STRZ0M) - [Auto-healing](#01JHTX979SA98S3EQR3R8SBT5E) - [Auto-heal outcomes](#01JHTX979W9HEAHFDKJSXKA7V5) **Which steps auto-heal?** Auto-heal works for all recorded steps that interact with your application. The following steps do _not_ auto-heal: - Recorded steps that use [Configure Find](https://help.mabl.com/hc/en-us/articles/19078181126932) with auto-heal disabled - [Custom find steps](https://help.mabl.com/hc/en-us/articles/19078195962388) that find an element using a CSS selector or XPath query. ## Building an element history When you record a test step that interacts with an element on the page, mabl collects attributes and uses them to find the element and track changes over time. The element history may also include: - Ancestor elements - elements that contain the target element - Custom test ID attributes - attributes set manually at the application level to match your team's test ID conventions. See [finding the correct element in browser tests](https://help.mabl.com/hc/en-us/articles/19078165693588) for more details. This information forms the basis of the step’s [element history](https://help.mabl.com/hc/en-us/articles/19083854354324). mabl uses a step’s element history during auto-heals. ## Looking for element candidates During a test run, mabl uses intelligent find strategies to look for elements that match the tracked attributes and the element history for the step. - If an ancestor is recorded for the element, this process happens first for the ancestor. Then mabl identifies candidates for the target element within the ancestor and chooses the best match. - If the step uses Configure Find, mabl only considers elements that match the specified criteria. **Auto-heal is per environment** A test step’s element history is tracked and updated for each environment the test is run against. For example, if you have a test in two plans - one that runs the test against your QA environment and one against your production environment - mabl tracks element attributes separately for those two environments. Any changes in the QA environment that result in auto-heals do not affect the behavior of the same test running against the production environment. ## Finding a strong match mabl uses data from past runs to determine when the element should appear on the page and be in an actionable state. Then mabl looks for a strong match to the model of the element learned from past runs: - If there is a strong match, mabl executes the step action on the target element and moves on to the next step. - If a strong match is not found after the element is expected to have appeared and been actionable, mabl [attempts an auto-heal](#01JHTX979SA98S3EQR3R8SBT5E). ### Configure Find The process of finding a strong match for steps that use Configure Find works a bit differently. First, mabl looks for a strong match using the specific criteria until the chosen timeout. - If there is a strong match, mabl executes the step action on the target element and makes small updates to the element if needed. - If a strong match is not found before the chosen timeout, the next phase depends on which option was selected for the step: - “Auto-heal”: mabl attempts to [auto-heal](#01JHTX979SA98S3EQR3R8SBT5E). - “Disable auto-heal”: mabl fails the step and indicates that it was unable to find the correct element. **Determining wait times in cloud runs** If the step is newer and hasn’t run a few times successfully in plan runs, mabl uses [page interaction speed](https://help.mabl.com/hc/en-us/articles/19078567932308) to determine how long to wait for an exact or strong match for an element in your application. After a few successful plan runs, mabl uses [Intelligent Wait](https://help.mabl.com/hc/en-us/articles/19078583820948) to determine how long to wait for an exact or strong match. ## Adaptive auto-healing When an element has changed enough that mabl is not confident it has found the right one, mabl attempts to auto-heal: ### Standard auto-heal mabl looks for the best available match to the element model. This process includes comparing partial matches to the model across the available elements on the page. ### Advanced auto-heal In cloud runs, if standard auto-healing strategies do not find a good match, mabl attempts advanced auto-healing. Advanced auto-heal uses generative AI to identify semantic similarities with new text and meaningful attribute values to find a good match. **Note** mabl doesn’t attempt advanced auto-heal until the test has run successfully in a plan at least 5 times. ### Summarizing find confidence When mabl auto-heals a step, the step output logs include a **Find summary** tab. This tab summarizes mabl’s confidence in finding a suitable match. If the best match is low confidence, the test step fails instead of auto-healing to an element that is a poor match. ![find\_confidence.png](https://help.mabl.com/hc/article_attachments/34012806901652) Find summary for a step that used advanced auto-heal ## Auto-heal outcomes After mabl attempts an auto-heal, one of the following outcomes occurs: 1. **Updated element model**: if the test ultimately passes and is part of a plan run, mabl updates the [element model](https://help.mabl.com/hc/en-us/articles/19083854354324) and records an auto-heal [insight](https://help.mabl.com/hc/en-us/articles/19083857000468) for the step. 2. **No updates to element model**: If the test ultimately fails or is part of an ad-hoc run, mabl notes the auto-heal in the output logs but does not update the element model or record an insight for the step. The following table illustrates how auto-heal works in different types of test runs: **Type of test run** **Standard auto-heal** **Advanced auto-heal if needed** **Updated element model** Passing test in plan run yes yes yes Failing test in plan run yes yes no Ad hoc cloud run (passing or failing) yes yes no Ad hoc local run (passing or failing) yes no no ### Local runs and auto-heal For local runs, mabl uses models from the most recent cloud runs to find the correct element. If a strong match isn’t found during a local run, mabl uses standard auto-healing strategies. Advanced auto-heal is a cloud-only feature. Any attempted auto-heals in local runs are not saved as auto-heal insights and do not impact the element model, even if the test run passes. ### Ad hoc runs and auto-heal Ad-hoc runs, which use the same execution environment as tests run in plans or deployment events, are intended to provide a way to validate test edits without impacting overall stats, metrics, and insights. For this reason, while ad-hoc runs use the same find strategies as tests run in a plan or deployment event, any successful adaptation in an ad-hoc run does not update the [element model](https://help.mabl.com/hc/en-us/articles/19083854354324).