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

Automatically recover your failed Cypress tests using AI on BrowserStack Automate.

Self-Heal 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:

Self-Heal is also available for Selenium.

When to use Self-Heal

• 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.

• Resilient locators as output: Healed locators you can reuse in future runs.

• Build-level healing report: Every healed locator and the reason it was applied, per build.

• Test script maintanence: Apply healed locators to your test script directly through MCP, or create a GitHub PR for SDK users.

Prerequisites

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

Supported Cypress versions

Self-Heal supports a specific Cypress version at a time.

Enable Self-Heal

How Self-Heal works

Each time your test interacts with an element, Self-Heal 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-Heal 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.

Fix your script with healed locators

A heal keeps a single run green. To stop the failure from recurring, push the healed locator back into your test using either of the following methods:

• MCP: Apply a build’s healed locators directly to your test files through the BrowserStack MCP server.

• GitHub PR: If you use BrowserStack SDK, you can raise a GitHub PR directly from the Self-Healing report.

Self-Heal 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. You can view healed resilient locators in the Text Logs tab, marked with the self-heal icon. BrowserStack recommends replacing locators in your script with the healed versions to improve stability.

All your Builds which have Healed-Selectors 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:

The build level self healed reports are available on the product dashboard. You can also use the REST API to fetch the build details.

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.

Reference

Refer to the API reference documentation for a complete list of REST APIs.