How AI Self-Healing Makes Cypress Tests More Reliable

Cypress AI self-healing helps a test step recover when its target element changes and a selector that worked before no longer fits. In Cypress, cy.prompt() first checks cached selector mappings from successful steps; if none match, it uses AI to locate an element from the original natural-language instruction. That can prevent some UI locator changes from interrupting a run, but it cannot prove that the new element is the one your business behavior requires. Review the resolved element and keep meaningful assertions.

1. What AI self-healing means in Cypress

Cypress describes cy.prompt() as natural-language test authoring in the Cypress App. It can generate standard Cypress commands, and it can remain active at runtime so steps adapt as the UI changes. For a step that needs a changed element, Cypress says it tries previously successful selector mappings first and uses AI when no cached mapping fits. See Cypress AI and Cypress’s technical description of self-healing.

For example, a test may ask Cypress to click “Sign in.” If a redesign changes the button’s class or moves the control, a brittle CSS selector might fail. A prompt-based step can try a known working mapping and, if that does not fit, ask AI to locate the element described by the instruction. The same issue can arise when a form field moves, a button is renamed, or a product-card layout changes.

This is selector recovery, not automatic repair of test intent. If a page now has two “Continue” buttons, or the application has changed what an action does, a resolved element may still be wrong for the scenario. Keep assertions that check the outcome the user cares about.

2. The self-healing flow

The test step needs an element. The prompt expresses the action in natural language, such as submitting a login form.
Cypress checks prior successful selector mappings. If a cached mapping still identifies a usable element, Cypress can heal through the cache without an AI call.
AI locates a replacement when needed. If no cached mapping fits, Cypress says it uses AI to find an element matching the original instruction.
The step proceeds and leaves review information. Cypress says the Command Log and detailed Console output show healing details, including the resolved element and whether cache or AI was involved.

These are Cypress’s descriptions of its own implementation. They should not be generalized to every AI testing product. Cypress author Jennifer Shehane describes the two paths as “Self-healed via cache” and “Self-healed via AI” in the linked technical post.

3. Set up a prompt and review the result

cy.prompt() is used in the Cypress App workflow, and Cypress’s current FAQ says it requires a free or paid Cypress Cloud account. Product requirements and limits can change, so consult the live Cypress App FAQ before adopting it.

Open your project in the Cypress App and use a natural-language prompt to describe the user action and desired outcome.
Run the generated step against the application state your test is meant to cover.
Inspect the Command Log and detailed Console output. Confirm the element Cypress resolved, whether it used a cached mapping or AI, and whether the action occurred in the intended part of the page.
Check the application outcome with assertions. For a login flow, for example, assert a stable authenticated state rather than treating a successful click as proof of login.
Review generated code and diffs before committing or relying on the adaptive step in CI.

Cypress’s FAQ cautions that a passing test only shows that its written assertions passed. It does not show that a healed selector still targeted the intended control, nor that the assertions cover the whole business requirement. The FAQ also notes that a spec with all tests skipped can report passed in the cypress tap workflow, so inspect run status and test selection as well.

4. Choose runtime adaptation or generated static code

Approach	What happens	Review and control
Keep `cy.prompt()` active	The step can adapt as the UI changes, using Cypress’s cached mappings and AI fallback.	Review the resolved element and run output whenever behavior changes; adaptation occurs as part of the workflow.
Generate once, then commit Cypress commands	Use the prompt to author a step, inspect and edit the generated code in Code view, then commit ordinary Cypress commands.	The committed test is static and reviewable. This suits teams that want selector control or approval before AI is used in CI.

The second option makes the authoring step AI-assisted while keeping later test runs based on committed commands. Neither approach replaces code review or assertions about user-visible behavior.

5. Review a healed selector safely

Read the resolved element in the Command Log or Console; confirm its label, role, surrounding form or card, and page location.
Check whether the intended action changed the application state. A click completing is not enough if the test is meant to submit, purchase, or authenticate.
Keep assertions tied to outcomes, not only to the locator or action. A locator that resolves successfully can still be semantically wrong.
Pay extra attention when multiple controls have similar names, responsive layouts show different controls, or a redesign changed the workflow.
Inspect generated code and diffs before committing. If you need a fixed, auditable selector, generate once and commit the reviewed Cypress commands.
When a healed run behaves unexpectedly, capture the relevant Command Log and Console details for debugging, while following your organization’s rules for handling test data.

6. Account, data, and privacy considerations

Cypress says cy.prompt() requires a free or paid Cypress Cloud account. Its documentation distinguishes AI feature data flows: cy.prompt(), Studio AI, and Cloud MCP use run data already stored in Cypress App and Cypress Cloud, such as command history, console logs, network requests, and Test Replay recordings. Cypress’s security page says its AI models are not trained on customer data, inputs and outputs are session-bound and are not shared with model providers, and Cloud test content is stored in the USA. These are vendor statements and can change; check current security terms and your organization’s data policy before using sensitive test data.

7. Limits, performance, and cost

Self-healing addresses locator fragility when the intended action remains the same. It does not repair an application bug, guarantee a correct target, validate business rules, or make incomplete assertions comprehensive. Cypress’s published materials describe cache and AI recovery paths but provide no independent quantified measure of reliability improvement. Treat a healed step as a reason to inspect the run, not as evidence that the test is correct.

A cache-based heal does not make an AI call according to Cypress’s description; an AI-based heal is used when a changed selector has no matching cache entry. The available sources do not establish a fixed latency or performance cost for either path, so measure run behavior in your own suite rather than relying on an assumed benchmark.

Prompt execution allowances and plan terms are volatile. Cypress’s pricing page, accessed October 3, 2026, listed 100 prompt executions per month on Starter, 9,000 per year on Team, 24,000 per year on Business, and 60,000 per year on Enterprise; it listed Smart Recommendations as free while in beta. Check the current Cypress pricing page and usage limits before budgeting.

8. Troubleshooting

Symptom	Likely cause	What to do
The prompt feature is unavailable	The Cypress App workflow may not be connected to a required free or paid Cypress Cloud account, or product requirements may have changed.	Check the current FAQ, account state, and live product documentation.
The original selector fails and no replacement is found	The changed element may not match the instruction, may not be present yet, or the UI change may alter the step’s intent.	Inspect the page and run output, make the instruction more specific, and verify the target in the relevant UI state. If needed, edit generated code or use a stable locator.
A healed step acts on the wrong control	Several elements may satisfy a broad instruction, or a redesign may have changed the meaning of the control.	Inspect the resolved element and surrounding DOM context; narrow the action and add assertions for the intended outcome. Do not accept the pass without this review.
The test passes but the workflow is still broken	The existing assertions may be too weak, or skipped tests may make the run appear successful in a workflow that reports that status.	Assert the user-visible business outcome, confirm tests actually ran, and review the FAQ’s guidance on what a pass means.
Run output does not make the repair clear	The healing details may be in the Command Log or detailed Console output rather than the assertion summary.	Open those views and look for the resolved element, cached elements checked, healing status, and cache-versus-AI path.
Security review blocks use with sensitive test data	Stored run artifacts can include logs, requests, and recordings, and organizational policy may be stricter than vendor defaults.	Review current Cypress security documentation and internal data policy; avoid sending sensitive test content until the permitted data flow is clear.

9. Where ScreenshotNeo fits

For a related browser workflow—capturing pages for visual checks, bug reports, or test documentation—ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It does not replace Cypress selector healing; it can provide screenshots when a test or AI agent needs a page image. Its API and configuration are documented at ScreenshotNeo documentation.

Or skip the browser setup

One GET request returns a screenshot. This cURL example saves a WebP image of the Stripe homepage:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

The same request in Python:

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

And in Node.js:

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up for free and get 1,000 screenshots a month with no card.

10. FAQ

Does self-healing fix a broken Cypress test automatically?

It can recover a step whose target changed by resolving an element through a cached selector mapping or AI. It does not establish that the test’s business intent or assertions remain correct.

Can a team use AI during authoring but not during every run?

Yes. Cypress describes generating steps with a prompt, reviewing and editing the ordinary Cypress commands in Code view, then committing those commands as static tests.

How can I tell whether Cypress used cache or AI?

Review the healing details in the Command Log and detailed Console output; Cypress says they expose the resolved element and healing path.

Does a passing healed test prove the right element was clicked?

No. A pass means the assertions passed. Inspect the resolved target and assert the intended user outcome.

Do prompt limits and data terms stay the same?

No guarantee of that: plan allowances and product policies can change. Check Cypress’s current pricing, FAQ, and security pages when adopting the feature.