Skip to content

Updates for renaming SelectorPlayground to ElementSelector API #6212

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.

Sign up for GitHub

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 4 commits into from
Jun 27, 2025
Merged

Updates for renaming SelectorPlayground to ElementSelector API #6212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
e33207f
Updates for SelectorPlayground to ElementSelector
jennifer-shehane Jun 24, 2025
643bf6c
add migration section for SelectorPlayground renaming
jennifer-shehane Jun 24, 2025
d00fd23
remove links to selector-playgroun-api
jennifer-shehane Jun 24, 2025
cc3771f
lint
jennifer-shehane Jun 24, 2025
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
101 changes: 101 additions & 0 deletions docs/api/cypress-api/element-selector-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
---
title: 'Cypress.ElementSelector | Cypress Documentation'
description: 'The Element Selector exposes APIs that enable you to change the default selector strategy and override the selectors that are returned per element.'
sidebar_label: ElementSelector
sidebar_position: 105
---

<ProductHeading product="app" />

# Cypress.ElementSelector

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).

## Syntax

```javascript
Cypress.ElementSelector.defaults(options)
Cypress.ElementSelector.getSelector($el)
```

### Arguments

<Icon name="angle-right" /> **options _(Object)_**

An object containing any or all of the following options:

| Option | Accepts | Description |
| ------------------ | ------------------ | -------------------------------------------------------------------------------- |
| `selectorPriority` | `Array of strings` | Determines the order of preference for which selector is chosen for the element. |

`selectorPriority` accepts the following strings:

- `attribute:${string}`
- `attributes`
- `class`
- `data-${string}`
- `id`
- `name`
- `nth-child`
- `tag`

<DefaultSelectorPriority />

<Icon name="angle-right" /> **$el _(Object)_**

The [jQuery element](http://api.jquery.com/Types/#jQuery) that you want to get
the selector value for.

## Examples

### Selector Priority

Set the selector priority to favor role, then aria-label, then name, then classes, then attributes.

```javascript
Cypress.ElementSelector.defaults({
selectorPriority: [
'attribute:role',
'attribute:aria-label',
'name',
'class',
'attributes',
],
})
```

### Get Selector

Returns you the selector value for a given element as determined by the selector
strategy. This is useful for debugging custom selector priorities you have set.

For example, consider this HTML fragment:

```html
<button id="bingo" class="number3">Cup of tea</button>
```

With the default selector strategy, the selector value will be `'#bingo'`
because IDs have priority over classes.

```js
const $el = Cypress.$('button')
const selector = Cypress.ElementSelector.getSelector($el) // '#bingo'
```

With a custom selector strategy that favours classes, the selector value will be
`'.number3'`.

```js
Cypress.ElementSelector.defaults({
selectorPriority: ['class', 'id'],
})

const $el = Cypress.$('button')
const selector = Cypress.ElementSelector.getSelector($el) // '.number3'
```

## See also

- [Cypress Studio](/app/guides/cypress-studio)
- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
100 changes: 0 additions & 100 deletions docs/api/cypress-api/selector-playground-api.mdx
View file
Open in desktop

This file was deleted.

46 changes: 23 additions & 23 deletions docs/api/table-of-contents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -190,29 +190,29 @@ The _key_ difference between Cypress APIs and Cypress commands is that Cypress
APIs execute the moment they are invoked and are **not** enqueued to run at a
later time.

| Property | Usage |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| [`Cypress.arch`](/api/cypress-api/arch) | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`. |
| [`Cypress.browser`](/api/cypress-api/browser) | Information about the current browser, such as browser family and version. |
| [`Cypress.Commands`](/api/cypress-api/custom-commands) | Create new custom commands and extend or override existing ones. |
| [`Cypress.config()`](/api/cypress-api/config) | Get and set Cypress configuration from inside your tests. |
| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies) | Generate console logs whenever a cookie is modified. |
| [`Cypress.currentRetry`](/api/cypress-api/currentretry) | A number representing the current test retry count. |
| [`Cypress.currentTest`](/api/cypress-api/currenttest) | An object with information about the currently executing test. |
| [`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. |
| [`Cypress.dom`](/api/cypress-api/dom) | A collection of DOM related helper methods. |
| [`Cypress.env`](/api/cypress-api/env) | Get environment variables from inside your tests. |
| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser) | Checks if the current browser matches the given name or filter. |
| [`Cypress.isCy()`](/api/cypress-api/iscy) | checks if a variable is a valid instance of cy or a cy chainable. |
| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api) | Set default values for how the `.type()` command is executed. |
| [`Cypress.platform`](/api/cypress-api/platform) | The underlaying OS name, as returned by Node's `os.platform()`. |
| [`Cypress.require`](/api/cypress-api/require) | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function. |
| [`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. |
| [`Cypress.SelectorPlayground`](/api/cypress-api/selector-playground-api) | Configure options used by the [Selector Playground](/app/core-concepts/open-mode#Selector-Playground). |
| [`Cypress.session`](/api/cypress-api/session) | A collection of helper methods related to the `.session()` command. |
| [`Cypress.spec`](/api/cypress-api/spec) | An object with information about the currently executing spec file. |
| [`Cypress.testingType`](/api/cypress-api/testing-type) | The current testing type, eg. `"e2e"` or `"component". |
| [`Cypress.version`](/api/cypress-api/version) | The current Cypress version. |
| Property | Usage |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`Cypress.arch`](/api/cypress-api/arch) | CPU architecture name of the underlying OS, as returned from Node's `os.arch()`. |
| [`Cypress.browser`](/api/cypress-api/browser) | Information about the current browser, such as browser family and version. |
| [`Cypress.Commands`](/api/cypress-api/custom-commands) | Create new custom commands and extend or override existing ones. |
| [`Cypress.config()`](/api/cypress-api/config) | Get and set Cypress configuration from inside your tests. |
| [`Cypress.Cookies.debug()`](/api/cypress-api/cookies) | Generate console logs whenever a cookie is modified. |
| [`Cypress.currentRetry`](/api/cypress-api/currentretry) | A number representing the current test retry count. |
| [`Cypress.currentTest`](/api/cypress-api/currenttest) | An object with information about the currently executing test. |
| [`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. |
| [`Cypress.dom`](/api/cypress-api/dom) | A collection of DOM related helper methods. |
| [`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). |
| [`Cypress.env`](/api/cypress-api/env) | Get environment variables from inside your tests. |
| [`Cypress.isBrowser()`](/api/cypress-api/isbrowser) | Checks if the current browser matches the given name or filter. |
| [`Cypress.isCy()`](/api/cypress-api/iscy) | checks if a variable is a valid instance of cy or a cy chainable. |
| [`Cypress.Keyboard.defaults()`](/api/cypress-api/keyboard-api) | Set default values for how the `.type()` command is executed. |
| [`Cypress.platform`](/api/cypress-api/platform) | The underlaying OS name, as returned by Node's `os.platform()`. |
| [`Cypress.require`](/api/cypress-api/require) | Enables utilizing dependencies within the [cy.origin()](/api/commands/origin) callback function. |
| [`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. |
| [`Cypress.session`](/api/cypress-api/session) | A collection of helper methods related to the `.session()` command. |
| [`Cypress.spec`](/api/cypress-api/spec) | An object with information about the currently executing spec file. |
| [`Cypress.testingType`](/api/cypress-api/testing-type) | The current testing type, eg. `"e2e"` or `"component". |
| [`Cypress.version`](/api/cypress-api/version) | The current Cypress version. |

## Utilities

Expand Down
13 changes: 5 additions & 8 deletions docs/app/core-concepts/open-mode.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -559,19 +559,16 @@ interactions.
title="Selector Playground demo"
/>

### Uniqueness
### How are selectors determined?

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

<DefaultSelectorPriority />

:::info

Cypress allows you to control how a selector is determined. Use the [Cypress.SelectorPlayground](/api/cypress-api/selector-playground-api)
API to control the selectors you want returned.

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

### Best practices

Expand Down
12 changes: 9 additions & 3 deletions docs/app/guides/cypress-studio.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ e2eSpecific: true

:::


## Overview

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.
Expand Down Expand Up @@ -84,9 +83,16 @@ You can also extend and update existing tests using Cypress Studio.
5. Right-click to add assertions
6. Click **Save** to save the changes to your spec file

The selectors are generated according to the
[`Cypress.ElementSelector` selector priority](/api/cypress-api/selector-playground-api#Default-Selector-Priority).
### How are selectors determined?

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

<DefaultSelectorPriority />

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

## Limitations

Expand Down
7 changes: 3 additions & 4 deletions docs/app/references/changelog.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ sidebar_label: Changelog

_Released 7/01/2025 (PENDING)_


## 14.5.0

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

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

**Documentation Changes:**

- [Added `Selector Playground Guide`](/app/core-concepts/open-mode#Selector-Playground)
- [Added `Selector Playground API`](/api/cypress-api/selector-playground-api)
- Added `Selector Playground API`
- [Updated `Best Practices`](/app/core-concepts/best-practices)
- [Updated `FAQ`](/app/faq)
- [Updated `Introduction to Cypress`](/app/core-concepts/introduction-to-cypress)
Expand Down
Loading