SmartGet -  Self-Healing Selectors for Cypress

SmartGet: Self-Healing Selectors for Cypress

SmartGet is a custom command for Cypress that keeps your tests running even when UI changes break traditional XPath or CSS selectors.

When a selector fails, SmartGet automatically scans the live DOM, evaluates possible matches based on tag type, ID, class, and visible text, and repairs the locator on the fly.

This Smart Element Detection technique works as both a self-healing selector and an auto-healing selector. Instead of causing test failures, it intelligently identifies the correct element using fallback logic, allowing tests to adapt automatically after minor front-end updates.

By using SmartGet, your automation becomes more resilient, reliable, and maintenance-friendly—especially valuable for applications with frequently changing UIs.

Tools and Libraries

Tools & Plugins

Cypress

Main testing framework used for writing and executing E2E tests.

Cypress-XPath

Plugin to enable XPath support in Cypress, allowing for more flexible element targeting.

Install plugin- npm install cypress-xpath --save-dev.

Add Required plugin in e2e.js-  require("cypress-xpath")

Custom Smart Selector Engine

A self-built mechanism that automatically detects alternative selectors when the original fails. It checks:

• DOM tag names

• Nearby text

• Class and ID similarity

JavaScript & Node.js

Used for writing reusable selector fallback functions and processing the DOM programmatically.

How SmartGet works?

Dynamic Selector Resolution

When the original selector fails, the engine automatically attempts alternative strategies by analyzing the DOM structure. It inspects nearby elements, siblings, and known layouts to locate the intended element.

ClueText

A tester-provided hint or context string— ClueText —that represents the nearby or inner text of the expected element. ClueText acts as an anchor for recovery by helping identify similar elements even when attributes change.This text is either:

• Predicted by testers based on UI design, or

• Extracted from the static mockups or figma screens.

Regex Tag Matching

• Regular expressions are used to extract the tag name (such as input, button, etc.) from the original selector. Therefore, it is recommended to place the tag name first, whether you are using an XPath or a CSS selector.

Examples:

For XPath: cy.smartGet("//input[@id='name']")

For CSS Selector: cy.smartGet("input#name")

• The script then scans the current DOM for all elements matching that tag.

• A filtered array of elements is created based on key attribute similarities (e.g., type, placeholder, textContent, etc.)

Heuristic Scoring & Matching

Each DOM element in the filtered array is scored using a custom heuristic function. This scoring considers:

• Tag similarity

• Text proximity to ClueText

• Attribute match (class, id)

• DOM hierarchy (sibling/parent matching)

The element with the highest score is chosen as the new selector.

Logging & Alerts

Logs selector mismatches and recovery attempts for easier debugging and future tuning.

Testing Utilities

• Chai (Assertions) – For validating results within Cypress.

• Mocha (Runner) – Cypress uses this internally for test orchestration.

cy.smartGet() Usage

Here is my custom command in Cypress to handle fallback selectors:

▶ Watch the SmartGet demo.

Key Benefits of SmartGet 

1. This is a one-time script setup that provides long-term benefits. 

2. No plugins or additional configurations are required.

3. It needs no manual intervention and dynamically adapts to the current DOM structure — so no matter how many times the DOM changes, SmartGet continues to work reliably.

4. It is customizable for any project and scalable for large applications. 

5. Its simplicity is its strength.

6. Most importantly, it's ideal for agile environments where the DOM structure evolves  sprint by sprint - saving time and effort through a self-correcting selector mechanism

Conclusion

Incorporating Self-Healing Selectors and Auto-Healing Selectors into your automation framework is no longer a luxury — it's a necessity for modern test automation. Techniques like Smart Element Detection ensure your tests stay resilient even when UI changes break traditional selectors. By adapting dynamically using tag types, clue texts, and fallback logic, you reduce test flakiness and maintenance efforts.

If you're tired of flaky tests due to UI changes, it's time to embrace self-healing strategies that future-proof your automation scripts.