diff --git a/docs/api/cypress-api/element-selector-api.mdx b/docs/api/cypress-api/element-selector-api.mdx new file mode 100644 index 0000000000..c07aa88076 --- /dev/null +++ b/docs/api/cypress-api/element-selector-api.mdx @@ -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 +--- + + + +# 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 + + **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` + + + + **$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 + +``` + +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) diff --git a/docs/api/cypress-api/selector-playground-api.mdx b/docs/api/cypress-api/selector-playground-api.mdx deleted file mode 100644 index b2b700a060..0000000000 --- a/docs/api/cypress-api/selector-playground-api.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -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 ---- - - - -# Cypress.SelectorPlayground - -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 - -## Syntax - -```javascript -Cypress.SelectorPlayground.defaults(options) -Cypress.SelectorPlayground.getSelector($el) -``` - -### Arguments - - **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. | -| `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. | - - - - **$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 IDs, 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}]` - } - }, -}) -``` - -### Get Selector - -Returns you the selector value for a given element as determined by the selector -strategy. - -For example, consider this HTML fragment. - -```html - -``` - -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.SelectorPlayground.getSelector($el) // '#bingo' -``` - -With a custom selector strategy that favours classes, the selector value will be -`'.number3'`. - -```js -Cypress.SelectorPlayground.defaults({ - selectorPriority: ['class', 'id'], -}) - -const $el = Cypress.$('button') -const selector = Cypress.SelectorPlayground.getSelector($el) // '.number3' -``` diff --git a/docs/api/table-of-contents.mdx b/docs/api/table-of-contents.mdx index 01c2a7f43f..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.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 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..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. @@ -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. + + +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/app/references/changelog.mdx b/docs/app/references/changelog.mdx index d3ba0851ec..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_ @@ -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). @@ -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) 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 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`