Skip to content

What is self-healing test automation?

Mikhail Bodnarchuk

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.
  2. The framework collects context. The error, the failed step, earlier steps, the page URL and often the page HTML.
  3. A healer proposes a fix. A rule you wrote, or a model that reads the HTML and suggests a new locator or action.
  4. The fix runs. If it succeeds, the test continues from the next step.
  5. 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?

RetryRun-time healHealer agent
What happensThe same step or test runs againA different action runs in place of the failed oneAn agent edits the test file
Good forTiming and network flakesKnown UI changes, expired sessions, renamed elementsBroken tests after a larger UI change
Test code changesNoNo, but a fix is suggestedYes, as a diff
Main riskHides real intermittent bugsPasses a test against the wrong elementRewrites 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).

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). 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).
  • 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). 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.
  2. Keep healLimit low, so one test cannot drift far.
  3. Fail the main branch when anything was healed, and turn each heal into a test fix or a bug report.
  4. Start from stable locators. Playwright recommends user-facing attributes and explicit contracts such as getByRole() (Playwright 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 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 or the CodeceptJS page. If agents also write your tests, read about agentic coding.

Sources

  1. Heal, CodeceptJS docs, 2026-11
  2. Testing with AI, CodeceptJS docs, 2026-11
  3. heal, CodeceptJS docs, 2026-11
  4. codeceptjs 4.2.5, npm, 2026-11-18
  5. Playwright Test Agents, Playwright docs (Microsoft), 2026-11
  6. 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).

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.

Building with AI agents? Talk to an engineer.