# What is self-healing test automation? How it works, and its risks

URL: https://sdclabs.com/glossary/self-healing-test-automation/

> Self-healing test automation fixes a failed step at run time, such as a changed locator, and continues. How it works, a tested CodeceptJS recipe.

# What is self-healing test automation?

[Mikhail Bodnarchuk](https://sdclabs.com/author/bodnarchuk/) 2026-11-20

Definition

Self-healing test automation is a technique where the test framework reacts to a failed step during the run, such as a changed locator, by trying a fix like a new locator, a page reload or a fresh login, and then continuing the test. A sound setup reports every heal so a person can review it.

## How does self-healing test automation work?

A self-healing framework steps in between "a step failed" and "the test failed". The flow is the same whether the fix comes from a rule or from a language model:

1. **A step fails.** Usually an action: a click, a form fill, a select.
1. **The framework collects context.** The error, the failed step, earlier steps, the page URL and often the page HTML.
1. **A healer proposes a fix.** A rule you wrote, or a model that reads the HTML and suggests a new locator or action.
1. **The fix runs.** If it succeeds, the test continues from the next step.
1. **The heal is reported.** At the end of the run you get a list of healed steps and the suggested code changes.

Step 5 separates a useful setup from a dangerous one. A heal without a report is a silent change to what your test checks.

## How is self-healing different from retries?

|   | Retry | Run-time heal | Healer agent |
|---|---|---|---|
| What happens | The same step or test runs again | A different action runs in place of the failed one | An agent edits the test file |
| Good for | Timing and network flakes | Known UI changes, expired sessions, renamed elements | Broken tests after a larger UI change |
| Test code changes | No | No, but a fix is suggested | Yes, as a diff |
| Main risk | Hides real intermittent bugs | Passes a test against the wrong element | Rewrites the test to match a bug |

The CodeceptJS docs explain the difference from retries: a retry can only re-run failed steps, while a heal recipe can perform any set of actions and react to any step of any test, without living in the test code ([CodeceptJS heal](https://codecept.io/heal/) ).

Playwright's version is a healer agent. It replays the failing steps, inspects the current UI for equivalent elements or flows, suggests a patch such as a locator update or a wait change, and reruns until the test passes or guardrails stop it ([Playwright Test Agents](https://playwright.dev/docs/test-agents) ). If it decides the feature itself is broken, its output is a skipped test. Treat a skip as a failure that needs a person.

## How does self-healing work in CodeceptJS?

CodeceptJS, the open-source framework created by SDCLabs founders, has a heal plugin and heal recipes: functions that run when a step fails. Facts from the current docs:

- npx codeceptjs generate:heal creates a starter file with an AI recipe and a clickAndType recipe. In version 4.2.5 the generated file is heal.js.
- AI healing "can solve exactly one problem": a changed locator. It sends the prompt, the error and the page HTML, with non-interactive elements removed, to the provider you configure, and it runs only with the --ai flag ([Testing with AI](https://codecept.io/ai/) ).
- AI healing applies only to actions such as click and fillField, not to assertions, waiters or grabbers. Custom recipes have no such limit: a recipe listed for see will heal a failed assertion, so keep assertions out of your recipes' steps.
- healLimit caps healed steps per test, with a default of 2 ([heal plugin](https://codecept.io/plugins/heal/) ). Healing is off in --debug mode.

Here is a recipe without AI. It heals only renames a person has approved, and it can make the run fail when anything was healed:

// heal.js import { heal, event } from 'codeceptjs' // Renames a person has reviewed. Anything else fails as usual. const renamed = { 'Sign in': 'Log in' } heal.addRecipe('knownRenames', { priority: 10, steps: ['click'], fn: async ({ step }) => { const replacement = renamed[step.args[0]] if (!replacement) return [] // no fix offered: the step fails return ({ I }) => { I.click(replacement) } }, }) // With HEAL_STRICT=1 (for example on the main branch), a healed run // still exits non-zero, so someone has to update the test. event.dispatcher.on(event.all.result, () => { if (process.env.HEAL_STRICT && heal.fixes.length) process.exitCode = 1 }) // codecept.conf.js (excerpt) import './heal.js' export const config = { // tests, helpers ... plugins: { heal: { enabled: true } }, }
Tested on 2026-11-19: CodeceptJS 4.2.5 (its package requires Node.js 22.12 or newer) with the Playwright helper and Chrome, run against a local page whose button reads "Log in" while the test clicks "Sign in":

I click "Sign in" I click "Log in" Code healed successfully by knownRenames (no errors thrown) I see "Welcome back" OK | 1 passed // 1s Self-Healing Report: 1 step was healed
The run exited with code 0 by default and code 1 with HEAL_STRICT=1. A click on a label that is not in the map failed with Clickable element "Sign up" was not found by text|CSS|XPath, as it should.

Test every recipe against a step it should not heal, too: a recipe that offers no fix must leave the step failing.

## Can self-healing tests hide real bugs?

Yes. A healed step means the test now checks something slightly different from what it was written to check. Three common cases:

- **The change was the bug.** A button label changed by mistake, and the heal clicks it under its new name. The test passes and the copy regression ships.
- **The heal picks the wrong element.** A model chooses a similar button in another part of the page. The test continues on a path no user takes.
- **The healer rewrites the expectation.** An agent that edits tests can make a test match broken behavior. Review its diff like any other code.

Ways to keep heals honest:

1. Heal actions, never assertions.
1. Keep healLimit low, so one test cannot drift far.
1. Fail the main branch when anything was healed, and turn each heal into a test fix or a bug report.
1. Start from stable locators. Playwright recommends user-facing attributes and explicit contracts such as getByRole() ([Playwright locators](https://playwright.dev/docs/locators) ). Good locators break less often, so there is less to heal.

## When should you use self-healing?

Use it on long end-to-end journeys where one flaky step wastes a whole run, during a planned UI migration, and for known failure classes such as an expired session. Skip it as a substitute for fixing locators, for tests where the exact UI text is the requirement, and on release gates where nobody reads the heal report.

Healing treats symptoms. Our guide to [test automation](https://sdclabs.com/blog/what-is-test-automation/) covers the causes of flaky end-to-end tests and how to keep a CI suite stable. For test framework setup in CodeceptJS or Playwright, see [QA and test automation](https://sdclabs.com/services/qa-and-test-automation/) or the [CodeceptJS](https://sdclabs.com/test-automation/codeceptjs/) page. If agents also write your tests, read about [agentic coding](https://sdclabs.com/glossary/agentic-coding/) .

## Sources

1. [Heal](https://codecept.io/heal/) , CodeceptJS docs, 2026-11
1. [Testing with AI](https://codecept.io/ai/) , CodeceptJS docs, 2026-11
1. [heal](https://codecept.io/plugins/heal/) , CodeceptJS docs, 2026-11
1. [codeceptjs 4.2.5](https://www.npmjs.com/package/codeceptjs) , npm, 2026-11-18
1. [Playwright Test Agents](https://playwright.dev/docs/test-agents) , Playwright docs (Microsoft), 2026-11
1. [Locators](https://playwright.dev/docs/locators) , Playwright docs (Microsoft), 2026-11

## Frequently asked questions

### Do self-healing tests need AI?

No. A heal recipe can be plain code that reloads a page, logs in again or maps a known rename. AI is one way to guess a new locator when the markup changed, and it adds a model call and a data-sharing decision to every failed step.

### Which tools support self-healing tests?

Open-source options include the CodeceptJS heal plugin and the Playwright healer agent. Commercial test platforms may offer it too; ask any vendor to show you the heal report and how to switch healing off for a release run.

### Does Playwright have self-healing tests?

Yes. The healer is one of three Playwright Test Agents, next to the planner and the generator. You add their definitions with `npx playwright init-agents` for VS Code, Claude Code, Codex or OpenCode, and regenerate them when you update Playwright ([Playwright docs](https://playwright.dev/docs/test-agents) ).

### Is self-healing worth it for a small test suite?

Usually not. With a few dozen tests it is faster to fix a broken locator than to maintain recipes and review heal reports. It starts to pay off on long end-to-end journeys and large suites where one UI change breaks many tests at once.

Services

- [QA and test automation](https://sdclabs.com/services/qa-and-test-automation/)
- [AI testing services](https://sdclabs.com/services/ai-testing/)

Read next

- [What is test automation? A guide from the founders of Codeception and CodeceptJS](https://sdclabs.com/blog/what-is-test-automation/)
- [Faster delivery needs stronger tests: QA and test automation in 2026](https://sdclabs.com/blog/qa-test-automation-challenges/)
- [What is AI testing? It means two things, and you probably need both](https://sdclabs.com/blog/what-is-ai-testing/)

Related terms

- [Agentic coding](https://sdclabs.com/glossary/agentic-coding/)
- [AI evals](https://sdclabs.com/glossary/ai-evals/)

[Mikhail Bodnarchuk](https://sdclabs.com/author/bodnarchuk/) Founder of Codeception and CodeceptJSBoth are open-source testing frameworks: Codeception for PHP, CodeceptJS for JavaScript.[LinkedIn](https://www.linkedin.com/in/davert/) [GitHub](https://github.com/DavertMik)

## Building with AI agents? Talk to an engineer.

[Start a project](https://sdclabs.com/contact/) [Book a call with the CEO](https://calendly.com/sdclabs/60min)
