For AI agents and LLMs: a machine-readable index is available at llms.txt. A plain-Markdown version of any documentation page is available by appending .md to its URL.
Skip to main content

How to Use Auto-Healing for Playwright on TestMu AI


When Playwright tests break because a locator changed after a UI update, Auto Healing on TestMu AI recovers the session instead of failing the run. It detects broken locators at runtime and generates new ones, which reduces flakiness and keeps your test suites reliable. You turn it on by passing a single autoHeal: true capability in your Playwright configuration.

Enable Auto Healing With the autoHeal Capability​


To turn on Auto Healing, pass autoHeal: true as a capability in your Playwright configuration. The example below shows it inside the LT:Options block alongside the other test options.

Verified
const capabilities = {
browserName: "Chrome",
browserVersion: "latest",
"LT:Options": {
platform: "Windows 10",
build: "Playwright Auto Heal Build",
name: "Playwright Auto Heal Test",
user: process.env.LT_USERNAME,
accessKey: process.env.LT_ACCESS_KEY,
network: true,
video: true,
console: true,
autoHeal: true,
},
};
note

Auto Healing has no prerequisites. Enable it directly through the autoHeal capability.

Enable Auto Healing in Your Language​


The autoHeal capability works the same way across languages. Select your language below to see how to pass it when connecting to the TestMu AI Playwright endpoint.

Verified

For JavaScript/NodeJS, you can use the following code:

// playwright.config.js
module.exports = {
use: {
connectOptions: {
wsEndpoint: `wss://cdp.lambdatest.com/playwright?capabilities=${encodeURIComponent(JSON.stringify({
'browserName': 'Chrome',
'browserVersion': 'latest',
'LT:Options': {
'platform': 'Windows 10',
'build': 'Playwright Auto Heal Build',
'name': 'Playwright Auto Heal Test',
'autoHeal': true,
'user': process.env.LT_USERNAME,
'accessKey': process.env.LT_ACCESS_KEY,
}
}))}`
}
}
};

How Auto Healing Works​


Auto Healing watches the page during execution and restores the correct locator when one no longer matches. The diagram below shows how it detects a broken locator and recovers the correct element.

TestMu AI Automation dashboard showing an auto-healed locator during a Playwright test run, with the Healed Selector and Original Selector in the command log

Auto-healing adjusts broken locators by merging attributes and context. During runtime, it monitors the web page to identify DOM (Document Object Model) changes.

When an element is successfully located using Playwright's locator methods (page.locator('#username').click(), etc.), its DOM path is recorded. If that same element is later referenced on the same page and is missing, the system evaluates the current page and generates new locators for altered elements based on previous benchmarks.

Auto Detection of a Changed Locator​


Web elements often change their locators after an update to the web application. In these cases, Auto Healing detects the new locator and continues the test execution without a failure.

Here is an example test case demonstrating this:

Verified
const { test } = require('../lambdatest-setup');
const { expect } = require('@playwright/test');

test.describe('Browse LambdaTest in different search engines', () => {
test('Test Auto Heal', async ({ page }) => {
await page.goto('https://www.lambdatest.com/selenium-playground/auto-healing');
await page.waitForTimeout(1000); // sleep 1s

// Locate element before DOM change
let buttonBeforeDOMChange = await page.locator('#username'); // equivalent to FindElement ByID
await buttonBeforeDOMChange.click();

// Trigger DOM change
await page.click('p.selenium_btn');
await page.waitForTimeout(1000); // sleep 1s

// Try to locate the same element after DOM change
// Auto healing will automatically detect the new locator
let buttonAfterDOMChange = await page.locator('#username'); // again check for element
await buttonAfterDOMChange.click();

await page.waitForTimeout(1000); // sleep 1s
});
});

The test case interacts with an element before and after a DOM change occurs on the TestMu AI auto-healing playground. Auto Healing detects that the element's locator has changed and adapts to it, so the test continues to execute successfully.

To run the test, execute the below command:

Verified
npx playwright test auto-heal.spec.js

Benefits of Auto Healing​


Auto Healing pays off most in suites that break often on small UI changes. The benefits below explain what you gain by enabling it.

  • Increased Test Stability: Playwright tests remain consistent even when the web application's UI undergoes minor changes, reducing flakiness.
  • Reduced Test Maintenance: The system automatically adapts to evolving interfaces, reducing the manual effort required to update test scripts.
  • Reliable CI/CD Pipeline: Stable tests feeding into CI/CD pipelines reduce unexpected failures and ensure smoother deployments.

Limitations of Auto Healing​


Auto Healing handles a wide range of issues, but it does not cover every failure. Be aware of the limitations below before you rely on it.

  • Non-recoverable errors: Auto Healing cannot recover from certain types of errors, such as Playwright browser initialization errors, network connectivity issues, or system-level failures.

  • Test accuracy: While Auto Healing can reduce test flakiness, it may also mask real issues in your web application or test scripts. It's important to review the logs and understand why a test needed healing.

  • Performance impact: Auto Healing has minimal impact on test execution time. The additional locator checks and recovery mechanisms add only slight overhead.

  • Best for locator changes: Auto Healing works best with locator changes such as ID, class, or attribute modifications. Complete page redesigns or fundamental workflow changes may still require manual updates.

Auto Healing enhances test suite robustness but does not replace good test design. Review healed tests regularly for issues that may be masked by the feature.


Continue with the guides below to run and configure your Playwright tests on TestMu AI.

Terminal First Testing With Kane CLI

Natural language browser & mobile app tests right from terminal.

×
Schedule Your Personal Demo
Kane CLI terminal

Help and Support

Related Articles