Skip to main content
Auto-heal keeps your no-code tests passing when product copy, layout, or minor flows evolve. Each step carries intent (its description, run history, and optionally knowledge-base articles) so Stably can repair broken locators, adapt to new UI, or regenerate a sequence automatically. You stay in control—auto-heal never lands changes without your approval.

What auto-heal can fix

  • Locator tweaks: Adjust attributes, inner text, or roles when labels change.
  • Minor UI shifts: Handle new containers or re-ordered elements without rewriting the flow.
  • Exploratory retries: Add or skip intermediate clicks if a dialog or confirmation page appears.
  • Full regenerations: Propose rewritten steps when the intent is still valid but the journey changed. See Maintenance agents for the full automation loop.
Auto-heal suggestion preview

Choose the right step mode

Every step can run under one of three modes:
  • Strict: Replays the exact recorded actions—ideal for deterministic API calls or admin screens that must never change.
  • Auto-heal (default): Attempts minimal fixes to locators and UI position while preserving the original flow.
  • AI: Regenerates the step from its description each run, great for highly dynamic content such as “Select the last day of the current month”.
Switch modes from the step sidebar before saving a test or at any time afterwards.
Selecting auto-heal modes for a step

Configure healing sensitivity

Open Step settings → Auto-heal to pick how aggressively Stably should adapt:
  • Locator only: Update selectors, attributes, or nearby hierarchy—no extra actions.
  • Minor UI changes: Allow layout adjustments, new frames, or renamed buttons.
  • User flow changes: Explore alternate routes, including adding new actions discovered during the run.
Set optional exploration limits to cap how many AI-generated actions can be added when recovering a flow.
Configuring auto-heal sensitivity on a step

Review and apply changes

When auto-heal intervenes, you’ll receive a diff that highlights the proposed edits:
  1. Open the Auto-heal tab in the test run results or within the editor’s Review panel.
  2. Inspect each suggestion—updated selectors, inserted steps, or regenerated descriptions.
  3. Approve to merge the change into the saved test, or reject to keep the prior version.
Changes that you approve become the new baseline and automatically update future runs.

Project-level defaults

  • Set organization-wide defaults in Settings → AI Agents to pick auto-heal behavior, default exploration limits, and fallback models.
  • Connect Knowledge Base articles so the AI references your product terminology when healing flows.
  • Use run tags or environments to scope aggressive healing to staging while keeping production suites conservative.

Best practices

  • Keep step descriptions concise but descriptive—mention business intent, not just the UI element.
  • Mark critical gateway steps as Strict so you are alerted when the contract truly breaks.
  • Combine auto-heal with AI Assertions so validations remain resilient even as UI text changes.
  • Regularly review pending suggestions; early acceptance keeps your test suite aligned with the current experience.
If a test regularly needs deep rewrites, consider promoting the scenario to code with the Stably Playwright SDK where you can version-control bespoke recovery logic.
I