From e33207f968bfec3dc7b71f09f4d6bfbff104e723 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 24 Jun 2025 14:33:17 -0400 Subject: [PATCH 1/4] Updates for SelectorPlayground to ElementSelector --- ...round-api.mdx => element-selector-api.mdx} | 69 +++++++++---------- docs/api/table-of-contents.mdx | 2 +- docs/app/core-concepts/open-mode.mdx | 13 ++-- docs/app/guides/cypress-studio.mdx | 10 +++ docs/partials/_default-selector-priority.mdx | 11 +-- 5 files changed, 54 insertions(+), 51 deletions(-) rename docs/api/cypress-api/{selector-playground-api.mdx => element-selector-api.mdx} (50%) diff --git a/docs/api/cypress-api/selector-playground-api.mdx b/docs/api/cypress-api/element-selector-api.mdx similarity index 50% rename from docs/api/cypress-api/selector-playground-api.mdx rename to docs/api/cypress-api/element-selector-api.mdx index b2b700a060..efb411f8ea 100644 --- a/docs/api/cypress-api/selector-playground-api.mdx +++ b/docs/api/cypress-api/element-selector-api.mdx @@ -1,24 +1,21 @@ --- -title: 'Cypress.SelectorPlayground | Cypress Documentation' -description: 'The Selector Playground exposes APIs that enable you to change the default selector strategy and override the selectors that are returned per element.' -sidebar_label: SelectorPlayground +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 --- -# Cypress.SelectorPlayground +# Cypress.ElementSelector -The [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) -exposes APIs that enable you to: - -- Change the default selector strategy -- Override the selectors that are returned per element +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.SelectorPlayground.defaults(options) -Cypress.SelectorPlayground.getSelector($el) +Cypress.ElementSelector.defaults(options) +Cypress.ElementSelector.getSelector($el) ``` ### Arguments @@ -30,7 +27,17 @@ 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. | -| `onElement` | `function` | A function called with the element that should return a unique selector string for the element. If a falsey value is returned, the default selector function is used. | + +`selectorPriority` accepts the following strings: + +- `attribute:${string}` +- `attributes` +- `class` +- `data-${string}` +- `id` +- `name` +- `nth-child` +- `tag` @@ -43,37 +50,20 @@ the selector value for. ### Selector Priority -Set the selector priority to favor IDs, then classes, then attributes. +Set the selector priority to favor role, then aria-label, then name, then classes, then attributes. ```javascript -Cypress.SelectorPlayground.defaults({ - selectorPriority: ['id', 'class', 'attributes'], -}) -``` - -### onElement Callback - -Set a custom function for determining the selector for an element. Falls back to -default behavior if returning a falsey value. - -```javascript -Cypress.SelectorPlayground.defaults({ - onElement: ($el) => { - const customId = $el.attr('my-custom-attr') - - if (customId) { - return `[my-custom-attr=${customId}]` - } - }, +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. +strategy. This is useful for debugging custom selector priorities you have set. -For example, consider this HTML fragment. +For example, consider this HTML fragment: ```html @@ -84,17 +74,22 @@ because IDs have priority over classes. ```js const $el = Cypress.$('button') -const selector = Cypress.SelectorPlayground.getSelector($el) // '#bingo' +const selector = Cypress.ElementSelector.getSelector($el) // '#bingo' ``` With a custom selector strategy that favours classes, the selector value will be `'.number3'`. ```js -Cypress.SelectorPlayground.defaults({ +Cypress.ElementSelector.defaults({ selectorPriority: ['class', 'id'], }) const $el = Cypress.$('button') -const selector = Cypress.SelectorPlayground.getSelector($el) // '.number3' +const selector = Cypress.ElementSelector.getSelector($el) // '.number3' ``` + +## See also + +- [Cypress Studio](/app/guides/cypress-studio) +- [Selector Playground](/app/core-concepts/open-mode#Selector-Playground) diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx index 01c2a7f43f..3145a22592 100644 --- a/docs/api/table-of-contents.mdx +++ b/docs/api/table-of-contents.mdx @@ -201,6 +201,7 @@ later time. | [`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. | @@ -208,7 +209,6 @@ later time. | [`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". | diff --git a/docs/app/core-concepts/open-mode.mdx b/docs/app/core-concepts/open-mode.mdx index ea937ea614..b206e22705 100644 --- a/docs/app/core-concepts/open-mode.mdx +++ b/docs/app/core-concepts/open-mode.mdx @@ -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. -:::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 diff --git a/docs/app/guides/cypress-studio.mdx b/docs/app/guides/cypress-studio.mdx index 1795761aeb..e1096b79c7 100644 --- a/docs/app/guides/cypress-studio.mdx +++ b/docs/app/guides/cypress-studio.mdx @@ -87,6 +87,16 @@ You can also extend and update existing tests using Cypress Studio. 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. + + + +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 diff --git a/docs/partials/_default-selector-priority.mdx b/docs/partials/_default-selector-priority.mdx index 5940fe01ab..71e8eed843 100644 --- a/docs/partials/_default-selector-priority.mdx +++ b/docs/partials/_default-selector-priority.mdx @@ -4,8 +4,9 @@ 2. `data-test` 3. `data-testid` 4. `data-qa` -5. `id` -6. `class` -7. `tag` -8. `attributes` -9. `nth-child` +5. `name` +6. `id` +7. `class` +8. `tag` +9. `attributes` +10. `nth-child` From 643bf6c26e65f142870e97845e41fda8dc7860c7 Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 24 Jun 2025 14:40:31 -0400 Subject: [PATCH 2/4] add migration section for SelectorPlayground renaming --- docs/app/references/migration-guide.mdx | 26 +++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/docs/app/references/migration-guide.mdx b/docs/app/references/migration-guide.mdx index 121157b1b8..e721cc35a1 100644 --- a/docs/app/references/migration-guide.mdx +++ b/docs/app/references/migration-guide.mdx @@ -144,6 +144,32 @@ import { mount } from `cypress/angular` import { mount } from `@cypress/angular` ``` +### Selector Playground API changes + +The `Cypress.SelectorPlayground` API has been renamed to +[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api). Additionally, the `onElement` function has been removed as an option to the `defaults` method. + +This change was made in order to reflect its use in features beyond just the Selector Playground - like Cypress Studio. + +The following code shows how to migrate from the `Cypress.SelectorPlayground` API to the +[`Cypress.ElementSelector`](/api/cypress-api/element-selector-api) API. + +Before{' '} + +```ts +Cypress.SelectorPlayground.defaults({ + selectorPriority: ['class', 'id'], +}) +``` + +After + +```ts +Cypress.ElementSelector.defaults({ + selectorPriority: ['class', 'id'], +}) +``` + ## Migrating to Cypress 14.0 This guide details the code changes needed to migrate to Cypress From d00fd236bfdd4884da9604312b004d3db19e24fd Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 24 Jun 2025 14:53:48 -0400 Subject: [PATCH 3/4] remove links to selector-playgroun-api --- docs/app/guides/cypress-studio.mdx | 3 --- docs/app/references/changelog.mdx | 6 +++--- 2 files changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/app/guides/cypress-studio.mdx b/docs/app/guides/cypress-studio.mdx index e1096b79c7..50df3dd889 100644 --- a/docs/app/guides/cypress-studio.mdx +++ b/docs/app/guides/cypress-studio.mdx @@ -84,9 +84,6 @@ 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 diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index d3ba0851ec..e1bab63fbd 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -1831,7 +1831,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). @@ -10886,14 +10886,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) From cc3771fae7a77f6659fc7b0474111c253049179d Mon Sep 17 00:00:00 2001 From: Jennifer Shehane Date: Tue, 24 Jun 2025 15:09:25 -0400 Subject: [PATCH 4/4] lint --- docs/api/cypress-api/element-selector-api.mdx | 14 ++++-- docs/api/table-of-contents.mdx | 46 +++++++++---------- docs/app/guides/cypress-studio.mdx | 1 - docs/app/references/changelog.mdx | 1 - 4 files changed, 33 insertions(+), 29 deletions(-) diff --git a/docs/api/cypress-api/element-selector-api.mdx b/docs/api/cypress-api/element-selector-api.mdx index efb411f8ea..c07aa88076 100644 --- a/docs/api/cypress-api/element-selector-api.mdx +++ b/docs/api/cypress-api/element-selector-api.mdx @@ -24,9 +24,9 @@ Cypress.ElementSelector.getSelector($el) 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. | +| 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: @@ -54,7 +54,13 @@ Set the selector priority to favor role, then aria-label, then name, then classe ```javascript Cypress.ElementSelector.defaults({ - selectorPriority: ['attribute:role', 'attribute:aria-label', 'name', 'class', 'attributes'], + selectorPriority: [ + 'attribute:role', + 'attribute:aria-label', + 'name', + 'class', + 'attributes', + ], }) ``` diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx index 3145a22592..3eb8becefb 100644 --- a/docs/api/table-of-contents.mdx +++ b/docs/api/table-of-contents.mdx @@ -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.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 [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 diff --git a/docs/app/guides/cypress-studio.mdx b/docs/app/guides/cypress-studio.mdx index 50df3dd889..f3fd044b8b 100644 --- a/docs/app/guides/cypress-studio.mdx +++ b/docs/app/guides/cypress-studio.mdx @@ -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. diff --git a/docs/app/references/changelog.mdx b/docs/app/references/changelog.mdx index e1bab63fbd..dfdad48c99 100644 --- a/docs/app/references/changelog.mdx +++ b/docs/app/references/changelog.mdx @@ -12,7 +12,6 @@ sidebar_label: Changelog _Released 7/01/2025 (PENDING)_ - ## 14.5.0 _Released 6/17/2025_