> ## Documentation Index
> Fetch the complete documentation index at: https://qodex.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Replay cache and self-healing
> Qodex replays stable UI steps without an LLM call and uses recovery only when the page changes.
# Replay cache and self-healing
The replay cache is how Qodex keeps UI test runs fast and affordable. Once Qodex has resolved a plain-English step against the browser, it saves the working action and reuses it on future runs.
The LLM is not in the normal replay path. It comes back only when a cached action stops working because the UI changed.
## What gets cached
Each UI step stores two kinds of information:
* **Intent**: the meaning of the step, such as "open the billing page" or "click Save changes."
* **Cached action**: the browser action and selector that worked when the step was authored.
The cached action lets Qodex replay the step directly in Chromium. The intent gives Qodex enough context to recover if the cached selector becomes stale.
## Cache hit
A cache hit is the normal path. The saved selector still matches the page, so Qodex executes the browser action, checks the expectations, captures the step screenshot, and moves to the next step.
No model call is needed. The cost is the cost of running the browser action.
Qodex's browser replay tolerates invalid or self-signed certificates on the test target. This keeps staging, preview, and internal environments testable even when their TLS setup is not production-grade.
## Cache miss
A cache miss happens when the saved action no longer works. Common reasons include:
* A button label changed.
* A component moved or was replaced.
* A selector no longer matches anything.
* A modal, redirect, or feature flag changed the page state.
When this happens, Qodex uses the step intent, the current page snapshot, the previous cached action, and the error message to choose a new bounded browser action. If the new action succeeds, the run continues.
## What self-healing means
Self-healing is not a separate mode you turn on. It is the recovery path Qodex uses whenever a cached UI action fails but the original intent still makes sense on the new page.
| Result | Meaning | What Qodex does |
| -------------------------------- | ------------------------------------------------- | ------------------------------------------------ |
| Recovery succeeds | The UI changed, but the user intent still applies | The step passes and the run continues |
| Recovery gives up | The intent no longer matches the page | The step fails as a stale test or action failure |
| Action works but assertion fails | The UI behaved differently than expected | The step fails as a product or expectation issue |
This distinction matters because not every failure means the test is broken. Some failures are real product regressions; others are stale automation. Qodex keeps enough context to classify the difference.
## Why this matters
Without a replay cache, every UI test replay would require the model to inspect the page again. That gets expensive as your suite grows.
With Qodex, stable flows run from cached browser actions. Recovery is reserved for the places where the UI actually drifted, which keeps scheduled runs and CI runs practical.
## Related
See how cached actions are created during authoring.
Review the evidence captured when a step fails.
Understand REAL\_BUG, STALE\_TEST, and ENVIRONMENT\_ISSUE.
Track failed runs and verification results.
## On the roadmap
The deterministic UI replay runner will reduce recovery-time LLM usage further by re-deriving actions from captured authoring-time trajectories.