Skip to content

Commit 83402f9

Browse files
jennifer-shehanejennifer-shehane
authored
Rewrite to make its use more understandable + remove getSelector (#6235)
* Rewrite to make its use more understandable + remove getSelector * Add more examples + simplify * lint * add note about uniqueness of selector * lint
1 parent 1d1c4a3 commit 83402f9

File tree

1 file changed

+85
-31
lines changed

1 file changed

+85
-31
lines changed

‎docs/api/cypress-api/element-selector-api.mdx

Lines changed: 85 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: 'Cypress.ElementSelector | Cypress Documentation'
3-
description: 'The Element Selector exposes APIs that enable you to change the default selector strategy and override the selectors that are returned per element.'
3+
description: 'Customize how Cypress chooses selectors in Studio and Selector Playground by setting your preferred selector strategy.'
44
sidebar_label: ElementSelector
55
sidebar_position: 105
66
---
@@ -9,13 +9,18 @@ sidebar_position: 105
99

1010
# Cypress.ElementSelector
1111

12-
The Element Selector API is used to get the selector priority for selecting elements in [Cypress Studio](/app/guides/cypress-studio) and [Selector Playground](/app/core-concepts/open-mode#Selector-Playground).
12+
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).
13+
14+
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.
15+
16+
Cypress uses a strategy to generate selectors that are not only based on your preferred selectors, but also guaranteed to be **unique** within the document.
17+
18+
This means Cypress will **attempt to follow your configured `selectorPriority`**, but may skip lower-priority options or combine multiple selectors if a single attribute isn't unique enough.
1319

1420
## Syntax
1521

1622
```javascript
1723
Cypress.ElementSelector.defaults(options)
18-
Cypress.ElementSelector.getSelector($el)
1924
```
2025

2126
### Arguments
@@ -24,33 +29,44 @@ Cypress.ElementSelector.getSelector($el)
2429

2530
An object containing any or all of the following options:
2631

27-
| Option | Accepts | Description |
28-
| ------------------ | ------------------ | -------------------------------------------------------------------------------- |
29-
| `selectorPriority` | `Array of strings` | Determines the order of preference for which selector is chosen for the element. |
32+
| Option | Accepts | Description |
33+
| ------------------ | ------------------ | ---------------------------------------------------------------------- |
34+
| `selectorPriority` | `Array of strings` | Determines the order of attributes Cypress uses to generate selectors. |
3035

31-
`selectorPriority` accepts the following strings:
36+
Accepted values for `selectorPriority` are:
3237

33-
- `attribute:${string}`
34-
- `attributes`
38+
- `attribute:${string}` - for specific attributes like `attribute:aria-label`, `attribute:lang`, etc.
39+
- `attributes` - general fallback for any other attributes
3540
- `class`
36-
- `data-${string}`
41+
- `data-${string}` - for specific data attributes like `data-cy`, `data-testid`, etc.
3742
- `id`
3843
- `name`
3944
- `nth-child`
4045
- `tag`
4146

4247
<DefaultSelectorPriority />
4348

49+
Consider the following HTML:
50+
51+
```html
52+
<button id="submit-btn" class="primary" role="button" aria-label="Submit">
53+
Submit
54+
</button>
55+
```
56+
57+
With the default selector priority, Cypress prioritizes `id`, so the selector would be `#submit-btn`.
58+
4459
<Icon name="angle-right" /> **$el _(Object)_**
4560

46-
The [jQuery element](http://api.jquery.com/Types/#jQuery) that you want to get
47-
the selector value for.
61+
The [jQuery element](http://api.jquery.com/Types/#jQuery) for which you want to retrieve a selector.
4862

4963
## Examples
5064

51-
### Selector Priority
65+
### Set custom selector priority
5266

53-
Set the selector priority to favor role, then aria-label, then name, then classes, then attributes.
67+
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).
68+
69+
For example, this config tells Cypress to prefer semantic and accessibility attributes before falling back to styling details like class names.
5470

5571
```javascript
5672
Cypress.ElementSelector.defaults({
@@ -64,37 +80,75 @@ Cypress.ElementSelector.defaults({
6480
})
6581
```
6682

67-
### Get Selector
68-
69-
Returns you the selector value for a given element as determined by the selector
70-
strategy. This is useful for debugging custom selector priorities you have set.
83+
### Prioritize accessible attributes
7184

72-
For example, consider this HTML fragment:
85+
Accessibility-first apps often use ARIA roles and labels. You can configure Cypress to prioritize these when generating selectors:
7386

74-
```html
75-
<button id="bingo" class="number3">Cup of tea</button>
87+
```js
88+
Cypress.ElementSelector.defaults({
89+
selectorPriority: ['attribute:aria-label', 'attribute:role', 'id', 'class'],
90+
})
7691
```
7792

78-
With the default selector strategy, the selector value will be `'#bingo'`
79-
because IDs have priority over classes.
93+
This helps produce more readable and resilient selectors, especially for accessibility-first applications.
94+
95+
### Prioritize language-agnostic selectors (for i18n)
96+
97+
In multilingual applications, selectors based on text or labels may change between locales. Prefer stable, language-agnostic attributes like `data-*`, `role`, and `aria-labelledby`.
8098

8199
```js
82-
const $el = Cypress.$('button')
83-
const selector = Cypress.ElementSelector.getSelector($el) // '#bingo'
100+
Cypress.ElementSelector.defaults({
101+
selectorPriority: [
102+
'data-cy',
103+
'attribute:role',
104+
'attribute:aria-labelledby',
105+
'name',
106+
'id',
107+
'class',
108+
'attributes',
109+
],
110+
})
84111
```
85112

86-
With a custom selector strategy that favors classes, the selector value will be
87-
`'.number3'`.
113+
This ensures selectors are resilient to translation changes in text or labels.
114+
115+
### Avoid dynamic or auto-generated selectors
116+
117+
Many frameworks produce dynamic ids or class names such as:
118+
119+
```html
120+
<button
121+
id="button-5a3f9d"
122+
class="Component_button__3XyZ2 css-1a2b3c SeriesIndexFooter-footer-3WmRg"
123+
data-cy="checkout-btn"
124+
role="button"
125+
aria-label="Checkout"
126+
>
127+
Checkout
128+
</button>
129+
```
130+
131+
You can configure Cypress to prioritize `data-cy` and `role` attributes, and skip `id` and `class` attributes that are dynamically generated.
88132

89133
```js
90134
Cypress.ElementSelector.defaults({
91-
selectorPriority: ['class', 'id'],
135+
selectorPriority: [
136+
'data-cy',
137+
'attribute:role',
138+
'attribute:aria-label',
139+
'name',
140+
'attributes', // fallback
141+
// deliberately omit 'id' and 'class'
142+
],
92143
})
93-
94-
const $el = Cypress.$('button')
95-
const selector = Cypress.ElementSelector.getSelector($el) // '.number3'
96144
```
97145

146+
## History
147+
148+
| Version | Changes |
149+
| ------------------------------------------ | ------------------------------------------------------------------ |
150+
| [15.0.0](/app/references/changelog#15-0-0) | Renamed `Cypress.SelectorPlayground` to `Cypress.ElementSelector`. |
151+
98152
## See also
99153

100154
- [Cypress Studio](/app/guides/cypress-studio)

0 commit comments

Comments
 (0)