Skip to content

Commit 54fca6d

Browse files
jennifer-shehanejennifer-shehane
authored
Updates for renaming SelectorPlayground to ElementSelector API (#6212)
* Updates for SelectorPlayground to ElementSelector * add migration section for SelectorPlayground renaming * remove links to selector-playgroun-api * lint
1 parent b4b05f6 commit 54fca6d

File tree

8 files changed

+173
-143
lines changed

8 files changed

+173
-143
lines changed

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

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
---
2+
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.'
4+
sidebar_label: ElementSelector
5+
sidebar_position: 105
6+
---
7+
8+
<ProductHeading product="app" />
9+
10+
# Cypress.ElementSelector
11+
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).
13+
14+
## Syntax
15+
16+
```javascript
17+
Cypress.ElementSelector.defaults(options)
18+
Cypress.ElementSelector.getSelector($el)
19+
```
20+
21+
### Arguments
22+
23+
<Icon name="angle-right" /> **options _(Object)_**
24+
25+
An object containing any or all of the following options:
26+
27+
| Option | Accepts | Description |
28+
| ------------------ | ------------------ | -------------------------------------------------------------------------------- |
29+
| `selectorPriority` | `Array of strings` | Determines the order of preference for which selector is chosen for the element. |
30+
31+
`selectorPriority` accepts the following strings:
32+
33+
- `attribute:${string}`
34+
- `attributes`
35+
- `class`
36+
- `data-${string}`
37+
- `id`
38+
- `name`
39+
- `nth-child`
40+
- `tag`
41+
42+
<DefaultSelectorPriority />
43+
44+
<Icon name="angle-right" /> **$el _(Object)_**
45+
46+
The [jQuery element](http://api.jquery.com/Types/#jQuery) that you want to get
47+
the selector value for.
48+
49+
## Examples
50+
51+
### Selector Priority
52+
53+
Set the selector priority to favor role, then aria-label, then name, then classes, then attributes.
54+
55+
```javascript
56+
Cypress.ElementSelector.defaults({
57+
selectorPriority: [
58+
'attribute:role',
59+
'attribute:aria-label',
60+
'name',
61+
'class',
62+
'attributes',
63+
],
64+
})
65+
```
66+
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.
71+
72+
For example, consider this HTML fragment:
73+
74+
```html
75+
<button id="bingo" class="number3">Cup of tea</button>
76+
```
77+
78+
With the default selector strategy, the selector value will be `'#bingo'`
79+
because IDs have priority over classes.
80+
81+
```js
82+
const $el = Cypress.$('button')
83+
const selector = Cypress.ElementSelector.getSelector($el) // '#bingo'
84+
```
85+
86+
With a custom selector strategy that favours classes, the selector value will be
87+
`'.number3'`.
88+
89+
```js
90+
Cypress.ElementSelector.defaults({
91+
selectorPriority: ['class', 'id'],
92+
})
93+
94+
const $el = Cypress.$('button')
95+
const selector = Cypress.ElementSelector.getSelector($el) // '.number3'
96+
```
97+
98+
## See also
99+
100+
- [Cypress Studio](/app/guides/cypress-studio)
101+
- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)

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

Lines changed: 0 additions & 100 deletions
This file was deleted.

‎docs/api/table-of-contents.mdx

Lines changed: 23 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -190,29 +190,29 @@ The _key_ difference between Cypress APIs and Cypress commands is that Cypress
190190
APIs execute the moment they are invoked and are **not** enqueued to run at a
191191
later time.
192192

193-
| Property | Usage |
194-
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
195-
| [`Cypress.arch`](/api/cypress-api/arch) | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`. |
196-
| [`Cypress.browser`](/api/cypress-api/browser) | Information about the current browser, such as browser family and version. |
197-
| [`Cypress.Commands`](/api/cypress-api/custom-commands) | Create new custom commands and extend or override existing ones. |
198-
| [`Cypress.config()`](/api/cypress-api/config) | Get and set Cypress configuration from inside your tests. |
199-
| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies) | Generate console logs whenever a cookie is modified. |
200-
| [`Cypress.currentRetry`](/api/cypress-api/currentretry) | A number representing the current test retry count. |
201-
| [`Cypress.currentTest`](/api/cypress-api/currenttest) | An object with information about the currently executing test. |
202-
| [`Cypress.log`](/api/cypress-api/cypress-log) | This is the internal API for controlling what gets printed to the Command Log. Useful when writing your own custom commands. |
203-
| [`Cypress.dom`](/api/cypress-api/dom) | A collection of DOM related helper methods. |
204-
| [`Cypress.env`](/api/cypress-api/env) | Get environment variables from inside your tests. |
205-
| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser) | Checks if the current browser matches the given name or filter. |
206-
| [`Cypress.isCy()`](/api/cypress-api/iscy) | checks if a variable is a valid instance of cy or a cy chainable. |
207-
| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api) | Set default values for how the `.type()` command is executed. |
208-
| [`Cypress.platform`](/api/cypress-api/platform) | The underlaying OS name, as returned by Node's `os.platform()`. |
209-
| [`Cypress.require`](/api/cypress-api/require) | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function. |
210-
| [`Cypress.Screenshot.defaults()`](/api/cypress-api/screenshot-api) | Set defaults for screenshots captured by the `.screenshot()` command and the automatic screenshots taken during test failures. |
211-
| [`Cypress.SelectorPlayground`](/api/cypress-api/selector-playground-api) | Configure options used by the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground). |
212-
| [`Cypress.session`](/api/cypress-api/session) | A collection of helper methods related to the `.session()` command. |
213-
| [`Cypress.spec`](/api/cypress-api/spec) | An object with information about the currently executing spec file. |
214-
| [`Cypress.testingType`](/api/cypress-api/testing-type) | The current testing type, eg. `"e2e"` or `"component". |
215-
| [`Cypress.version`](/api/cypress-api/version) | The current Cypress version. |
193+
| Property | Usage |
194+
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
195+
| [`Cypress.arch`](/api/cypress-api/arch) | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`. |
196+
| [`Cypress.browser`](/api/cypress-api/browser) | Information about the current browser, such as browser family and version. |
197+
| [`Cypress.Commands`](/api/cypress-api/custom-commands) | Create new custom commands and extend or override existing ones. |
198+
| [`Cypress.config()`](/api/cypress-api/config) | Get and set Cypress configuration from inside your tests. |
199+
| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies) | Generate console logs whenever a cookie is modified. |
200+
| [`Cypress.currentRetry`](/api/cypress-api/currentretry) | A number representing the current test retry count. |
201+
| [`Cypress.currentTest`](/api/cypress-api/currenttest) | An object with information about the currently executing test. |
202+
| [`Cypress.log`](/api/cypress-api/cypress-log) | This is the internal API for controlling what gets printed to the Command Log. Useful when writing your own custom commands. |
203+
| [`Cypress.dom`](/api/cypress-api/dom) | A collection of DOM related helper methods. |
204+
| [`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) | Configure selector priority used by [Cypress Studio](/app/guides/cypress-studio) and [Selector Playground](/app/core-concepts/open-mode#Selector-Playground). |
205+
| [`Cypress.env`](/api/cypress-api/env) | Get environment variables from inside your tests. |
206+
| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser) | Checks if the current browser matches the given name or filter. |
207+
| [`Cypress.isCy()`](/api/cypress-api/iscy) | checks if a variable is a valid instance of cy or a cy chainable. |
208+
| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api) | Set default values for how the `.type()` command is executed. |
209+
| [`Cypress.platform`](/api/cypress-api/platform) | The underlaying OS name, as returned by Node's `os.platform()`. |
210+
| [`Cypress.require`](/api/cypress-api/require) | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function. |
211+
| [`Cypress.Screenshot.defaults()`](/api/cypress-api/screenshot-api) | Set defaults for screenshots captured by the `.screenshot()` command and the automatic screenshots taken during test failures. |
212+
| [`Cypress.session`](/api/cypress-api/session) | A collection of helper methods related to the `.session()` command. |
213+
| [`Cypress.spec`](/api/cypress-api/spec) | An object with information about the currently executing spec file. |
214+
| [`Cypress.testingType`](/api/cypress-api/testing-type) | The current testing type, eg. `"e2e"` or `"component". |
215+
| [`Cypress.version`](/api/cypress-api/version) | The current Cypress version. |
216216

217217
## Utilities
218218

‎docs/app/core-concepts/open-mode.mdx

Lines changed: 5 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -559,19 +559,16 @@ interactions.
559559
title="Selector Playground demo"
560560
/>
561561

562-
### Uniqueness
562+
### How are selectors determined?
563563

564-
Cypress will automatically calculate a **unique selector** to use targeted
564+
Cypress will automatically calculate a **unique selector** to use for a targeted
565565
element by running through a series of selector strategies.
566566

567567
<DefaultSelectorPriority />
568568

569-
:::info
570-
571-
Cypress allows you to control how a selector is determined. Use the [Cypress.SelectorPlayground](/api/cypress-api/selector-playground-api)
572-
API to control the selectors you want returned.
573-
574-
:::
569+
Cypress allows you to control how a selector is determined. Use the
570+
[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API to control
571+
the selectors you want prioritized.
575572

576573
### Best practices
577574

‎docs/app/guides/cypress-studio.mdx

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,6 @@ e2eSpecific: true
1919

2020
:::
2121

22-
2322
## Overview
2423

2524
Cypress Studio makes test creation faster and easier. With Studio, you can record user interactions in the browser and instantly generate Cypress test code. Add assertions with a rightclick and fine-tune your tests inline.
@@ -84,9 +83,16 @@ You can also extend and update existing tests using Cypress Studio.
8483
5. Right-click to add assertions
8584
6. Click **Save** to save the changes to your spec file
8685

87-
The selectors are generated according to the
88-
[`Cypress.ElementSelector` selector priority](/api/cypress-api/selector-playground-api#Default-Selector-Priority).
86+
### How are selectors determined?
87+
88+
Cypress will automatically calculate a **unique selector** to use for a targeted
89+
element by running through a series of selector strategies.
90+
91+
<DefaultSelectorPriority />
8992

93+
Cypress allows you to control how a selector is determined. Use the
94+
[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API to control
95+
the selectors you want prioritized.
9096

9197
## Limitations
9298

‎docs/app/references/changelog.mdx

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@ sidebar_label: Changelog
1212

1313
_Released 7/01/2025 (PENDING)_
1414

15-
1615
## 14.5.0
1716

1817
_Released 6/17/2025_
@@ -1831,7 +1830,7 @@ _Released 1/24/2023_
18311830
configured to exclude files with those extensions. Addresses
18321831
[#24495](https://github.com/cypress-io/cypress/issues/24495).
18331832
- Added support for the `data-qa` selector in the
1834-
[Selector Playground](/api/cypress-api/selector-playground-api) in addition to
1833+
Selector Playground in addition to
18351834
`data-cy`, `data-test` and `data-testid`. Addresses
18361835
[#25305](https://github.com/cypress-io/cypress/issues/25305).
18371836

@@ -10886,14 +10885,14 @@ _Released 3/1/2018_
1088610885
has been updated to automatically prefer `data-cy`, `data-test` or
1088710886
`data-testid` attributes when providing the unique selector for an element.
1088810887
Additionally it now exposes a
10889-
[public API](/api/cypress-api/selector-playground-api) that you can use to
10888+
public API that you can use to
1089010889
control how it determines which selector to use. Fixes
1089110890
[#1135](https://github.com/cypress-io/cypress/issues/1135).
1089210891

1089310892
**Documentation Changes:**
1089410893

1089510894
- [Added `Selector Playground Guide`](/app/core-concepts/open-mode#Selector-Playground)
10896-
- [Added `Selector Playground API`](/api/cypress-api/selector-playground-api)
10895+
- Added `Selector Playground API`
1089710896
- [Updated `Best Practices`](/app/core-concepts/best-practices)
1089810897
- [Updated `FAQ`](/app/faq)
1089910898
- [Updated `Introduction to Cypress`](/app/core-concepts/introduction-to-cypress)

0 commit comments

Comments
 (0)