Skip to content

Add notes about the variability of the ElementSelector API and the de… #6238

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 10 additions & 2 deletions docs/api/cypress-api/element-selector-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ sidebar_position: 105

# Cypress.ElementSelector

The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).
The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) (which will be replaced by Cypress Studio once it is no longer experimental).

By setting your own selector strategy, you can control which attributes Cypress prioritizes (like `data-*`, `id`, or `aria-label`) when generating selectors. This helps you enforce consistency, improve test readability, and make generated tests more resilient to changes in your HTML.

Expand All @@ -33,6 +33,14 @@ An object containing any or all of the following options:
| ------------------ | ------------------ | ---------------------------------------------------------------------- |
| `selectorPriority` | `Array of strings` | Determines the order of attributes Cypress uses to generate selectors. |

:::info

##### API Stability

The `selectorPriority` API is under active development and may change in future versions as we refine the best way to generate selectors within our products. Stay updated with our [changelog](/app/references/changelog) for any breaking changes.

:::

Accepted values for `selectorPriority` are:

- `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.
Expand Down Expand Up @@ -64,7 +72,7 @@ The [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to

### Set custom selector priority

You can customize how Cypress generates selectors by defining a priority order for which attributes to prefer. This affects the selectors you see in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).
You can customize how Cypress generates selectors by defining a priority order for which attributes to prefer. This affects the selectors you see in tools like [Cypress Studio](/app/guides/cypress-studio) and the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) (which will be replaced by Cypress Studio once it is no longer experimental).

For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.

Expand Down
7 changes: 7 additions & 0 deletions docs/app/core-concepts/open-mode.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -540,6 +540,13 @@ unexpected behaviors

## Selector Playground

:::caution

##### Deprecation Notice

The Selector Playground will be replaced by [Cypress Studio](/app/guides/cypress-studio) once it is no longer experimental. Cypress Studio provides the same functionality for constructing Cypress commands using unique selectors, along with additional recording capabilities.
:::

The Selector Playground is an interactive feature that helps you:

- Determine a unique selector for an element.
Expand Down