Designing an AI-Assisted Locator Self-Healing Workflow for Playwright

Designing an AI-Assisted Locator Self-Healing Workflow for Playwright

How to identify, propose, validate, and safely apply locator repairs in UI automation.

UI automation failures are not always product failures. A button’s accessible name may change, a form field may be reorganized, or the DOM may move while the feature still works. When a large regression suite runs repeatedly, engineers can spend considerable time locating and fixing those broken selectors.

This article describes a generalized reference workflow for AI-assisted locator healing in Playwright with TypeScript. It reflects engineering problems I have explored in regression automation, but it is not a disclosure of any client implementation, repository, private prompt, or measured production result.

Define what “healing” means

Consider a test that previously located a button by its accessible name:

await page.getByRole('button', { name: 'Submit request' }).click();

If the interface now calls it Send request, the test may fail with a locator timeout even though the user journey is still valid. A healer can suggest a new locator, but it must not treat every timeout as a locator problem. Network failures, missing permissions, bad test data, changed business rules, and genuine defects require different responses.

Scope: locator-related UI automation failures only. A successful repair should preserve the original test intent and assertions rather than just make the test green.

A reference workflow

Each stage should produce explainable evidence. Separating diagnosis, candidate discovery, code modification, and validation reduces the risk of an automatic change hiding an application defect.

1. Classify the failure first

A typical Playwright error may point to a selector or a timed-out assertion. That error is a clue, not a diagnosis. The classifier should inspect the failing action, relevant trace, and the application’s state at failure time.

A useful output might be:

{
"failureType": "possible_locator_change",
"confidence": "review_required",
"failedAction": "click submit button",
"evidence": ["original accessible name not found"],
"nextStep": "inspect candidate controls"
}

The example is invented and contains no internal test IDs or application data. A production process also needs a policy for how much failure evidence can be shared with an AI service.

1. Discover alternatives without guessing

Playwright encourages resilient, user-facing locators such as getByRole, getByLabel, and getByText when appropriate. A healer should inspect the current page and prefer semantic selectors over fragile CSS paths. For example:

// Old locator
page.getByRole('button', { name: 'Submit request' });
// Candidate after a reviewed UI label change
page.getByRole('button', { name: 'Send request' });

A candidate must be checked for uniqueness and correct context. A locator that matches some button is not enough. The target may live within a specific dialog, form, or section, and the healer needs to preserve that scope.

1. Validate before editing code

For each candidate, verify:

• The target exists and is uniquely identifiable in the intended UI state.
• Its role, name, label, or nearby context matches the original test intent.
• The original action can be performed without introducing a different flow.
• Downstream assertions still validate the intended user behavior.

A selector that resolves successfully but clicks the wrong button is an incorrect repair. If confidence is low or the UI behavior changed materially, stop and request human review.

1. Make a source-aware patch

With a TypeScript Page Object Model, locators may be shared across many tests. Broad string replacement risks changing unrelated code. An abstract syntax tree (AST) library such as ts-morph can help identify the intended declaration or call expression and produce a narrowly scoped patch.

A safe patching workflow should retain a diff, update only the approved target, type-check the project, and allow easy rollback. It should never silently modify tests to remove failing assertions or loosen expectations.

1. Rerun and produce a reviewable report

After patching, rerun the previously failing test with the same controlled data and environment, then run appropriate neighboring tests when the locator is shared. A review report might show:

Field Example
Failure classification Possible locator change
Previous locator Role: button, name: Submit request
Proposed locator Role: button, name: Send request
Validation Target unique; action verified
Targeted rerun Passed in example environment
Final status Pending engineer review

This is an illustrative report, not a real benchmark. A single passed rerun is evidence for review, not proof that the change is permanently correct or non-flaky.

Guardrails that matter

An AI-assisted healer should use approved data, least-privilege integrations, sanitized traces, controlled execution environments, and explicit review gates. Page text and error logs must be treated as untrusted input; they can include secrets or prompt-injection attempts. The OWASP Top 10 for LLM Applications provides a starting point for thinking through those risks.

Track metrics carefully: confirmed locator fixes, false-positive suggestions, review time, rerun outcomes, and reverted patches. Avoid claiming an overall reduction in regression failures when the measured scope is only locator repair.

What I learned

Self-healing works best as an engineering assistant, not as a way to force failing tests to pass. The difficult parts are failure classification, preserving the intended behavior, keeping source edits minimal, and generating evidence a reviewer can trust.

A robust design aims for this chain:

Failure evidence → locator diagnosis → candidate → validation → code diff → targeted rerun → human approval.

Further reading

• Playwright locator guidance
• Playwright best practices
• ts-morph
• OWASP LLM security guidance