Self-healing: suggested fixes you review

When the application under test changes (a button gets a new id, a label is reworded, a field moves into an iframe), a step can no longer find its element. Self-healing finds the element the step most likely meant and proposes a fix. A person approves every fix. AutoTestX never edits a test on its own unless a project Admin or Test Manager has enabled a rule that allows it.

Status: available. Tiers 0 and 1 run today, and a project can turn on the optional AI tier 2: steps heal during a run, the run report shows every heal with its evidence, and suggestions are reviewed on the Self-healing page. Rules can apply safe fixes without a review, every decision is kept in an audit trail, and any applied fix can be reverted. Cases that are not built yet are listed under Roadmap at the end of this page.

The core rule: suggest, never silently change

A heal produces a suggestion that contains:

the step’s current target and the proposed target,
the evidence: every signal that was compared (name, label, test id, position, nearby text…) with its value then and now, and how well it matched,
a confidence score,
the run that found it.

You approve, edit and approve, or reject it. Only an approval changes the test, and the new target is stamped approved heal so you can always see where it came from.

A project can also set self-healing rules that approve or reject some suggestions without a person: for example, “apply low-risk click fixes seen in two runs or more”. A fix a rule applies goes through exactly the same checks as yours, is stamped auto-heal, names the rule in the test’s history, and can be reverted. A project with no rules works as described on this page: every fix waits for a person.

How a heal is found

Healing runs only when a step’s element cannot be found, and only for healable step types. It tries up to three tiers in order:

Tier	What it does	Cost
0: Promote a fallback	A fallback strategy already found the element (the step was warned). Suggest making that strategy the primary one.	Free, deterministic
1: Fingerprint match	Compare the elements on the page against the step’s last known good fingerprint. Each element is scored on its accessible name, label, test id, stable attributes, own text, ancestors and landmark, nearest heading, position and sibling index.	Free, deterministic
2: AI pick (optional, off by default)	Tier 1 found elements that resemble the old one but could not prove one. An AI chooses among them, or says none. See below.	One AI generation per new question

A Tier 1 match must pass three checks before a run acts on it:

its confidence must reach the bar for the step’s risk: 70% for low-risk steps, 78% for medium-risk steps and for all checks (an assertion on the wrong element can hide a defect),
it must lead the second-best candidate by at least 12 points, so two near-identical “Save” buttons are never guessed between,
it must match on something the element is known by (its name, text, label, id or test id), not only on where it sits. A removed button’s neighbour sits in the same place.

Only elements the step can act on are compared: a Type step is only ever healed onto a field, never onto a button that now sits where the field was.

The proposed locators lead with what has proven stable. Anything that changed between the last known good element and the match (a rotated id, renamed classes, a new wrapper in the path) is kept only as a fallback.

Last known good

Every passing run refreshes each step’s fingerprint, the snapshot of the element as it looked when the step last succeeded. Healing compares against that recent snapshot, not against the day the test was recorded. The snapshot is stored next to the test, not in it, so refreshing it does not create a new test version.

What happens during a run

The decision depends on the confidence of the match and the risk of the step:

Outcome	When	What you see
Healed	Confident match on a step where a wrong element cannot do harm	The run continues with the healed target. The step is reported as healed (like warned) and a suggestion is created. One run finds every broken step, not just the first.
Suggestion only	The match is likely but not certain, or the step is high-risk	The step fails as usual, with the suggestion attached to the failure.
No confident match	Nothing on the page resembles the element	The step fails with no confident match. This usually means a real change or a defect, not drift.

The test itself never changes during a run. A healed run tells you the test would pass with the suggested fix.

Risk

Steps whose element looks destructive or financial (Delete, Remove, Pay, Submit, Approve, Send and similar, before or after the change) are treated as high-risk, and so is typing into a password field. A run never acts on a healed element in a high-risk step: the step fails and the suggestion is attached. A wrong click on “Delete” is worse than a failed run.

Healed steps do not update the last known good

A healed step does not refresh its fingerprint. Otherwise the healed element would become the reference for a target that still describes the old one, and later runs would use the fix without anyone approving it.

AI healing (Tier 2, optional)

Some changes leave Tier 1 with the right element in its list but no proof: a rename with nothing else in common (“Purchase Requisition” → “PR Request”), two near-identical buttons, a menu item that moved to another menu. The step then fails as Suggestion only and a person picks. With AI healing on, an AI is asked first.

What the AI is shown: the step’s type and label, the three steps before it, the element as it last worked, and up to six of Tier 1’s candidates, numbered, with Tier 1’s score for each: their roles, names, labels, ids, test ids and headings. Never the page itself, a screenshot, a typed value or a secret.

What it answers: the number of the candidate that is the same element, or none, with one sentence of reason and the values it compared. It never writes a locator. The fix’s locators are built by Tier 1 and checked against the page, exactly as for a Tier 1 match.

What a run does with it: nothing. An AI pick is never acted on during a run, whatever the step and however confident the AI is. The step fails, and the pick is filed as a suggestion with Tier 2 · AI pick on it. Rules never apply one either. A person approves, re-picks or rejects it like any other suggestion.

On the card	Means
Tier 2 · AI pick, medium confidence	The AI’s own word for how sure it is
Tier 1: 58%, lead 4 points. The AI chose tier 1’s first candidate.	Tier 1’s measured numbers, shown beside the AI’s answer, never replaced by it
An amber note: The AI chose candidate 3 of 5, which tier 1 scored at 41%. They disagree: look closely.	The AI picked an element Tier 1 did not rank first
The AI compared: “name="PR Request"” · “name="Purchase Requisition"”	The values its reason rests on, each quoted from what it was sent
The AI looked at tier 1’s candidates and did not choose one.	It answered none: the step keeps Tier 1’s result

The evidence table is Tier 1’s, for the element the AI chose.

When it is not asked: Tier 0 or a confident Tier 1 match healed the step; nothing on the page scored at least 25% (the element is most likely gone); AI healing is off; or the project’s daily limit or the organization’s AI allowance is used up. The step then keeps Tier 1’s result, and the report says why when the AI was skipped: AI healing skipped: the project’s daily limit on AI healing is reached.

When its answer is not used: a number that is not one of the candidates, a pick it cannot back with evidence from what it was sent, a pick whose locators do not find exactly that element, or no answer within 8 seconds. Each falls back to Tier 1, with the reason.

Turning it on

Where	Setting	Who
Self-healing → Rules, the AI healing card	On or off for the project, and the new AI calls a day (default 50, at most 500)	Admin, Test Manager
Organization → Settings, AI healing (tier 2)	Allowed or off for every project	Organization admin

It is off until a project turns it on. Turning it off for the organization keeps each project’s own setting for when it is allowed again.

Cost and reuse

Each new question uses one AI generation from the monthly allowance (none on your organization’s own key), charged to the project (it shows as AI healing (project) in the usage table), never to the person who started the run. The same question (the same step type, the same old element and the same candidates, in any order) is answered once a week: twenty tests that hit the same renamed button make one call. Rejecting or reverting an AI pick forgets its answer, so the next run asks again instead of filing the same pick.

How often the AI is right

On the Self-healing page, the AI picks filter narrows any tab to the AI’s picks and shows how they fared over the last 7, 30 or 90 days:

Number	Counts a pick a person
Approved as picked	Approved as the AI proposed it
Re-picked, rejected or reverted	Approved with another element (Pick the element instead…), rejected, or approved and then reverted

Each model that made picks gets its own line, and By step risk and AI confidence splits the same numbers into groups, since an overall rate can hide a group that is right far more, or far less, often than the rest. One group is shown on its own: low-risk, high-confidence picks that agreed with tier 1, on steps that are not checks. They are the only picks a run might one day be allowed to act on. Only what a person decided counts: a rule’s rejection says what the rule allows, not whether the AI chose the right element, and a pick still pending, replaced or no longer applying says nothing yet. These are the numbers that will decide whether an AI pick may ever do more than wait for a person.

Cases self-healing handles

A. Locator drift

These are healed by Tier 0 or Tier 1.

#	Case	Example	Tier
1	Primary locator broke, fallback still works	The id is gone, but role + name still matched (the step is warned)	0
2	Generated or rotating ids	`#btn_8f3a` → `#btn_c21e`	1
3	CSS or XPath broken by a DOM restructure	A wrapper `div` was added; classes were renamed	1
4	`data-testid` renamed	`save-btn` → `order-save`	1
5	Visible text or label wording changed	“Submit” → “Save changes”	1
6	Placeholder, aria-label or title changed	“Search…” → “Find orders”	1
7	Element moved on the page	A toolbar button moved to the header	1
8	Moved into or out of an iframe	A dialog now renders in its own frame. Every frame is searched, and the report names the frame it was found in	1
9	Moved into shadow DOM	A design-system migration to web components	1
10	Tag changed, role kept	`<button>` → `<a role=button>`; a native select → a custom combobox	1
11	Row container changed	Grid rows moved from `<tr>` to `div[role=row]`	1

B. Never healed

These fail clearly, with the reason:

The element is really gone. The feature was removed or there is a bug. The healer reports no confident match instead of guessing.
High-risk actions (delete, submit, pay, approve) when the match is not near-certain.
Steps that are not healable: Open, URL assertions, HTTP request, Poll API, Custom code and control flow.
Problems that are not about locators: a lookup record that does not exist, sign-in failures, server errors (5xx) and network errors.

Which steps can heal

Only steps that find an element through a target:

Category	Steps
Interaction	Click, Double click, Type, Clear, Select, Check, Upload file, Hover
Validation	Exists, Visible, Text, Value, Attribute
Control	Wait for element
Data	Extract

Reviewing suggestions

Suggestions are filed when a run finishes, and appear in four places (reviewers can also get an email digest of new ones):

the Self-healing page in the menu, with the number waiting for review beside it. Its Suggestions view lists every suggestion in the project, newest first, under Pending, Approved, Rejected, No longer applies, Replaced and Reverted. The Decided by a rule filter narrows any tab to what a rule decided, and each such card names the rule and its version. The AI picks filter narrows it to Tier 2 suggestions and shows how often they were right. The page’s other views are Rules and the Audit trail,
the run report: a Healed status on the step, or the suggestion on a failed or warned step, with the decision and its reason, the confidence, lead and risk, the old and proposed locators, the evidence table, and a Review suggestion link,
the test editor: a banner when the open test has suggestions waiting, with a Review button that opens the Self-healing page for that test. An amber chip in it counts the fixes for a step that has been changed since their run (see below), and the banner refreshes after you save, since your save can be that change,
the dashboard, which lists a test whose last run healed a step as needing attention: it passed, but only thanks to a fix nobody has approved yet.

For each pending suggestion:

Action	Effect
Approve	The proposed target replaces the step’s target
Pick the element instead…	Opens Pick. The element you pick replaces the step’s target, and the suggestion is recorded as approved with a re-picked element.
Reject	Closes the suggestion, with an optional reason. The same proposal is not offered again for that step.

What approving changes

The test is	Approving
Draft	Saves the fix into the same revision
Ready, and you can mark tests Ready	Saves the fix as the next revision, still Ready, so regression runs pick it up
Ready, and you cannot mark tests Ready	Saves the fix as a new Draft revision. A Test Manager marks it Ready.
Deprecated	Is refused

The new target is stamped approved heal, and the version history says which step was fixed and with which locator.

Repeats are grouped. If later runs find the same fix for the same step, the existing suggestion’s run count goes up. No duplicate is created. A data-driven run counts once, however many of its rows healed.
One answer per step. If a later run proposes a different fix for the same step, it replaces the pending one, which moves to Replaced.
No longer applies. If someone edits the step’s target after the suggestion was made (re-picks the element, or fixes it by hand), the suggestion moves to No longer applies and cannot be approved. Approving it would overwrite a newer decision with an older guess. Approving one suggestion also retires any other pending one for that step. Edits to the rest of the step or the test are covered in the next section.
Components. Component versions never change, so approving a heal inside a component publishes a new component version. Tests that call it stay pinned to their current version until you upgrade them. The component’s source test is fixed too when it is a Draft you can edit, so the next publish from it does not bring the broken locator back. If it cannot be fixed, the confirmation says why.

When the test changed since the run

A suggestion remembers the revision of the test (or component) its run executed, and the step as it was there. Approving checks the test as it is at that moment against both, so a fix never lands on a step it was not found for, and never writes over a save it did not see.

Since the run	The card	Approving
Nothing was saved	As usual	Applies the fix
The test was saved, but this step is as it was (another step changed, or this one was only renamed or moved among its neighbors)	A grey line: Found on v3 (…); the test is now v4, saved by Dana Lee (…). This step is unchanged, so the fix still applies.	Applies the fix to the current revision. Everyone else’s changes stay.
This step was edited around its locator: its action, value or options changed, or it moved into another block	An amber panel, This step was changed after the run that found this fix, listing each change as it was when found and as it is now	Only with Apply to the step as it is now, after you have checked the fix still fits. Or Pick the element instead…, Reject, or leave it: the next run checks the step as it is now and suggests again if it still needs a fix.
The step’s locator changed, or the step is gone	Moves to No longer applies	Not possible

“Apply to the step as it is now” applies only to the step you were shown. If someone changes it again before you click, nothing is saved and the panel shows the step afresh.
Someone else is editing the test. Approving asks first, in the card: Dana Lee is editing this test. Approving now means they must reload before they can save. Choose Approve anyway or Cancel. It is asked only for a fix that would be saved: one that no longer applies, or is for a step changed since you were shown it, says so first. The editor holds the test until its user leaves it or stops editing for 15 minutes, so the question can come shortly after they saved. Your own open editor never asks. A fix inside a component does not ask, since it changes the component, not the test.
A save and an approval at the same moment never overwrite each other. Whichever lands second is checked against the first: an approval on top of a save becomes the grey “still applies” case, and a save made before the approval gets the editor’s usual This test was saved by someone else dialog.
Rules apply a fix when the step is unchanged, like the grey case. When it was edited around its locator, the fix waits for a person (the step was changed since the run that found the fix, see Self-healing rules).
Older suggestions filed before revisions were recorded say Found before suggestions recorded their test revision, so only the locator is checked.
The audit trail records, for each applied fix, the revision it was found on next to the one it was applied to, and whether the test had moved on.

Reverting a fix

An approved fix, yours or a rule’s, has a Revert button on the Approved tab. Reverting puts the locator the fix replaced back into the step:

It saves a new revision. History is never rewritten, even when the fix amended a Draft, so the version history shows the fix and its undoing as separate steps. A fix inside a component publishes a new component version, and the source test is handled as for an approval.
The suggestion moves to Reverted and is not suggested again for that step, even when the next run finds exactly the same fix.
It is refused if anyone has changed the step’s locator since the fix (re-picked the element, or edited it by hand). Reverting would undo their change too. The card says so and nothing changes. Edits to the rest of the step do not stop a revert: it only puts the step’s own earlier locator back.
You can add a reason. It is kept in the audit trail.

Reverting a rule’s fix pauses that rule for that step. You have just said the rule chose wrong there, so it will not fix that step again by itself: its next fix for the step waits for review. The rule still works everywhere else, including on the test’s other steps. Untick Pause the rule for this step when the rule was right and only this match was wrong. An Admin or Test Manager lifts the pause on the Rules view.

Who can approve

	Admin	Test Manager	Test Developer	Tester	Viewer
See suggestions, rules and the audit trail	✓	✓	✓	✓	✓
Approve, edit, reject or revert fixes	✓	✓	✓	—	—
Create, change and delete rules; lift a paused rule	✓	✓	—	—	—
Turn AI healing on or off for the project	✓	✓	—	—	—

Approving or reverting also needs the right to edit that test, and a fix inside a component needs the right to publish components. A suggestion for someone’s private test is only shown to its owner, and the audit trail leaves its entries out for everyone else.

See People, roles and permissions.

Making tests easier to heal

Keep at least one fallback strategy on every target. Tier 0 is the cheapest and most reliable heal.
Run tests regularly. Each passing run refreshes the last known good fingerprint, so the healer compares against how the page looks now.
Fix drift while it is a warning. A warned step is a heal waiting to happen.
Scope grid rows by business key (within role row, key {{poNumber}}), never by index. A scoped target survives row and layout changes far better.

Roadmap

These are not built yet. They are listed so you can see where self-healing is going; ask us for their status if one matters to you.

More locator cases (Tiers 0 and 1)

Case	Example	Tier
New ambiguity	A second “Save” appeared and the locator now matches two elements: suggest a container scope or a narrower strategy	1
Brittle primary can be upgraded	The primary is an XPath or `nth`, but the element now has a stable test id (a proactive suggestion)	0
Lookup controls drifted	The opener, Next, OK and search-field targets of a Lookup step, which will make Lookup a healable step	1

Suggestion-only fixes

These will never be applied during a run, because applying them could hide a defect. The step will fail and the suggestion will be attached.

Case	Suggested fix
Timeout, but the element appeared shortly after	Raise the step’s timeout, or add a Wait for element step
An overlay blocks the click (cookie banner, “What’s new” dialog)	Insert a conditional step that dismisses it
A Select option’s text was renamed	Update the option value
Assert text: expected and actual differ only slightly	Update the expected value. Flagged may mask a regression.