Use Self-Healing Agent for your Appium tests running on BrowserStack App Automate

Automatically recovery your failed Appium tests using AI on BrowserStack App Automate.

Self-Healing automatically detects when a locator no longer works and intelligently finds the right element using historical context and AI signals. Instead of failing immediately, BrowserStack recovers the test and records what changed — reducing false failures and keeping builds green as the UI evolves.

What is BrowserStack self-heal?

The following video explains how BrowserStack’s Self-Heal feature works:

When to use Self-Healing

• Your tests frequently fail due to UI or locator changes.
• UI Refactoring and redesigns happen often across teams.
• Flaky tests due to NoSuchElement exceptions are common.

Use Self-Heal to reduce build instability and debugging time.

Key features

• findElement command healing: Heals broken locators used in findElement commands.

• Generate resilient locators as output: Provides healed locators that can be used in future test runs.

• Build level healed selector report: Provides insights into healed selectors at the build level. (Coming soon)

Prerequisites

• Your account must have BrowserStack AI enabled to use the AI Self-Healing feature. For more information, see our documentation on how to activate AI preferences.
• Self-Healing Agent is available only on App Automate Pro plan.

Enable Self-Heal

MutableCapabilities capabilities = new MutableCapabilities();
HashMap<String, Object> browserstackOptions = new HashMap<String, Object>();
browserstackOptions.put("userName", "YOUR_USERNAME");
browserstackOptions.put("accessKey", "YOUR_ACCESS_KEY");
browserstackOptions.put("selfHeal", "true");
capabilities.setCapability("bstack:options", browserstackOptions);

var capabilities = {
	'bstack:options' : {
		"userName" : "YOUR_USERNAME",
		"accessKey" : "YOUR_ACCESS_KEY",
		"selfHeal" : "true"
	}
}

Dictionary<string, object> browserstackOptions = new Dictionary<string, object>();
browserstackOptions.Add("userName", "YOUR_USERNAME");
browserstackOptions.Add("accessKey", "YOUR_ACCESS_KEY");
browserstackOptions.Add("selfHeal", "true");
capabilities.AddAdditionalOption("bstack:options", browserstackOptions);

$caps = array(
	'bstack:options' => array(
		"userName" => "YOUR_USERNAME",
		"accessKey" => "YOUR_ACCESS_KEY",
		"selfHeal" => "true"
	)
)

desired_cap = {
	'bstack:options' : {
		"userName" : "YOUR_USERNAME",
		"accessKey" : "YOUR_ACCESS_KEY",
		"selfHeal" : "true"
	},
}

capabilities = {
	'bstack:options' => {
		"userName" => "YOUR_USERNAME",
		"accessKey" => "YOUR_ACCESS_KEY",
		"selfHeal" => "true"
	}
}

DesiredCapabilities caps = new DesiredCapabilities();
caps.setCapability("userName", "YOUR_USERNAME");
caps.setCapability("accessKey", "YOUR_ACCESS_KEY");
caps.setCapability("browserstack.selfHeal", "true");

var capabilities = {
 "userName" : "YOUR_USERNAME",
 "accessKey" : "YOUR_ACCESS_KEY",
 "browserstack.selfHeal" : "true"
}

DesiredCapabilities capability = new DesiredCapabilities();
capability.AddAdditionalCapability("userName", "YOUR_USERNAME");
capability.AddAdditionalCapability("accessKey", "YOUR_ACCESS_KEY");
capability.AddAdditionalCapability("browserstack.selfHeal", "true");

$caps = array(
 "userName" => "YOUR_USERNAME",
 "accessKeyild" => "YOUR_ACCESS_KEY",
 "browserstack.selfHeal" => "true"
);

desired_cap = {
 "userName" : "YOUR_USERNAME",
 "accessKey" : "YOUR_ACCESS_KEY",
 "browserstack.selfHeal" : "true"
}

caps = Selenium::WebDriver::Remote::Capabilities.new
caps["userName"] = "YOUR_USERNAME"
caps["accessKey"] = "YOUR_ACCESS_KEY"
caps["browserstack.selfHeal"] = "true"

The self healing feature is supported on the following platforms:

• Android
• iOS

How Self-Healing works

Each time your test interacts with an element, Self-Healing Agent securely stores key information about that element — including its locator, nearby attributes and the structure of the DOM.

During future test runs, if the original locator no longer resolves, Self-Healing steps in and the following process takes place:

• Detects a broken locator.
• Evaluates the latest success context.
• Generates the alternate healed locator.
• Applies the resilient locator and continues the test run.

Self-Healing workflow

1. Build listing- list of all your builds.
2. Build insights- detailed insights of self-healed tests in a build.
3. Test listing- list of all tests in a build.
4. Text logs- detailed logs of a test including self-healed locators.

All your Builds which have Healed-Selectors will appear with the AI icon next to its name:

Builds Insights page have 2 elements:

• The Self-Healed Test CTA on Build Summary widget
• Self Healing Insights widget

All your tests that are recovered by self-heal appear on the dashboard marked by the self-heal icon as shown in the following image:

You can view these self-healed resilient locators in the Text Logs tab of your session masked by the self-heal icon

You can filter the Text Logs to only view the self-healed locators as shown in the following image:

Self-heal limitations

Although the self-heal feature is engineered to handle a broad spectrum of issues, it comes with its own set of limitations, such as:

• Some Performance overhead
  Healing adds extra analysis during execution. The impact is usually small, but it should complement — not replace — good test design and error handling.

• Not all failures can be healed
  System failures, WebDriver issues, and situations where the element truly no longer exists cannot be recovered. These tests will (correctly) fail.