Skip to content

Updates for open mode + selector playground #6316

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 1 commit into from
Nov 4, 2025
Merged

Updates for open mode + selector playground #6316

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
8 changes: 4 additions & 4 deletions docs/api/cypress-api/element-selector-api.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: 'Cypress.ElementSelector | Cypress Documentation'
description: 'Customize how Cypress chooses selectors in Studio and Selector Playground by setting your preferred selector strategy.'
description: 'Customize how Cypress chooses selectors in Studio and cy.prompt() by setting your preferred selector strategy.'
sidebar_label: ElementSelector
sidebar_position: 105
---
Expand All @@ -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) (which will be replaced by Cypress Studio once it is no longer experimental).
The ElementSelector API lets you define how Cypress selects elements in tools like [Cypress Studio](/app/guides/cypress-studio) and [cy.prompt()](/api/commands/prompt).

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 Down Expand Up @@ -72,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) (which will be replaced by Cypress Studio once it is no longer experimental).
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 [cy.prompt()](/api/commands/prompt)

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

Expand Down Expand Up @@ -158,4 +158,4 @@ Cypress.ElementSelector.defaults({
## See also

- [Cypress Studio](/app/guides/cypress-studio)
- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
- [cy.prompt()](/api/commands/prompt)
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 @@ -191,29 +191,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.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. |
| 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 [cy.prompt()](/api/commands/prompt). |
| [`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
15 changes: 0 additions & 15 deletions docs/app/core-concepts/best-practices.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,21 +144,6 @@ meaning it's not coupled to the **behavior** or **styling** of an element.
Additionally, it makes it clear to everyone that this element is used directly
by test code.

:::info

<strong>Did you know?</strong>

The [Selector Playground](/app/core-concepts/open-mode#Selector-Playground)
automatically follows these best practices.

When determining a unique selector, it will automatically prefer elements with:

- `data-cy`
- `data-test`
- `data-testid`

:::

#### <Icon name="graduation-cap" /> Real World Example

The <Icon name="github" inline="true" contentType="rwa" /> uses two useful
Expand Down
Loading