Troubleshooting flaky selectors and self-healing replay

Websites change. Buttons move, class names get regenerated, layouts shift. Tyrbo's replay engine is built to absorb most of that without breaking — and to hand you exactly what you need when a step truly can't run.

How replay finds an element

Every recorded step stores more than one way to find its element:

• A ranked list of candidate selectors, best first: test IDs, stable IDs, ARIA role and name, visible text, scoped CSS, and XPath as a last resort.
• A fingerprint of the element: its tag, text, key attributes, nearby text, and position on the page.

During a run, each browser step goes through the same sequence:

1. Auto-wait for the page to settle and the element to be ready.
2. Try the candidates in order until one matches.
3. Retry with backoff if the page is momentarily mid-update.
4. Fuzzy re-query by fingerprint — if no selector matches, Tyrbo looks for the element that best matches the stored fingerprint. When this succeeds, the step is logged as "healed."
5. Fail with evidence — only after all of that does the step fail, and it captures a screenshot and a DOM snapshot at the moment of failure.

What "healed" means

A healed step means the page changed enough that every stored selector missed, but the fingerprint still identified the element confidently. The run succeeded — treat the healed log line as an early warning. If the same step heals run after run, re-record or edit that step so it gets fresh selectors; healing is the safety net, not the plan.

Reading a failed run

Open the failed run and go to the failing step:

• The screenshot shows what the page looked like at failure — often the answer is immediately visible (a cookie banner, a login page, an error state).
• The DOM snapshot shows what was actually in the page, which tells you whether the element was missing, renamed, or just not loaded yet.

Common causes and fixes

| Symptom | Likely cause | Fix | | --- | --- | --- | | Step fails intermittently, screenshot looks half-loaded | Slow page, element appears late | Raise the step's timeout, or add a wait after the previous step | | Step fails right after a click that opens new content | Next step raced the page update | Add a wait-after on the click step, or a retry on the failing step | | Screenshot shows a pop-up, cookie banner, or survey | Occasional overlay blocks the element | Record dismissing it once, then mark that dismiss step optional | | Step fails only in the cloud, works locally | Site blocks datacenter traffic or needs your login | Route the browser steps to your device — see Cloud runs vs local runs | | Screenshot shows the login page | Saved session expired | Re-export the session from the recorder, or run those steps locally on a device with a persistent profile | | Step keeps getting logged as healed | Page redesign outdated the selectors | Re-record the step so it stores fresh selectors | | Wrong item clicked in a list | List order changed between runs | Re-record targeting something unique to the item (its text), not its position |

Make fragile steps resilient

Per-step options are your main tools:

• Timeout — how long to wait for the element before giving up.
• Retries — how many times to re-attempt the step.
• Optional — the run continues even if this step's element never appears; right for dismissing intermittent overlays.
• Wait after — a settle delay after the step, for pages that keep rendering after an action.

Still stuck?

If a step fails with evidence you can't explain, contact info@tyrbo.ai with the run link — the screenshot and DOM snapshot attached to the failing step are usually enough for us to spot the problem quickly.