feat: Rename SelectorPlayground API to ElementSelector API #31889

jennifer-shehane · 2025-06-13T17:34:47Z

Closes Deprecate Cypress.SelectorPlayground API - replace with Cypress.ElementSelector API #31801
Closes Studio: Generate DOM selectors based on the ARIA role name & label #30309
Closes Default SelectorPlayground priority order partially contradicts best practices #6876

Additional details

Renames SelectorPlayground API to ElementSelector - an error is thrown when users use the SelectorPlayground API.
Removes 'onElement' property from 'defaults' - we don't intend to support this custom selector definition anymore (it has extremely low usage)
Bumps unique-selector package to latest - this should bring in smarter selectors and an expanded API.
Loosen the types of selectors that can be specified in priority - we now support name and attribute:* selectors as they are accepted in unique-selector. Types are now more specific also.
Converts files from JS to TS

Steps to test

Use the existing Selector Playground UI - ensuring it adds selectors properly - accepting selectorPriority.
Use the existing experimentalStudio UI - ensuring it adds selectors properly - accepting selectorPriority.
Ensure calling SelectorPlayground API properly errors and is shown as deprecated in TypeScript.

How has the user experience changed?

Cypress.SelectorPlayground errors when called

Can now use name attribute in selectorPriority!

Can now use attribute:* in selectorPriority!

Current studio selector generation still works!

PR Tasks

Have tests been added/updated?
Has a PR for user-facing changes been opened in cypress-documentation? Updates for renaming SelectorPlayground to ElementSelector API cypress-documentation#6212
Have API changes been updated in the type definitions?

BREAKING: Rename SelectorPriority API to ElementSelector API

…-selector

…/github.com/cypress-io/cypress into selector-playground-api-to-element-selector

cypress · 2025-06-13T18:59:44Z

cypress Run #63279

Run Properties: Failed #63279 • d1c4948a9d: Merge branch 'release/15.0.0' into selector-playground-api-to-element-selector

Project	`cypress`
Branch Review	`selector-playground-api-to-element-selector`
Run status	`Failed #63279`
Run duration	`16m 59s`
Commit	`d1c4948a9d: Merge branch 'release/15.0.0' into selector-playground-api-to-element-selector`
Committer	`Jennifer Shehane`
View all properties for this run ↗︎

Test results
Failures	`1`
Flaky	`3`
Pending	`143`
Skipped	`0`
Passing	`6163`
View all changes introduced in this branch ↗︎

UI Coverage `0%`
Untested elements	`4`
Tested elements	`0`

Accessibility `97.09%`
Failed rules	`0 critical` `1 serious` `0 moderate` `0 minor`
Failed elements	`4`

Tests for review

cypress/e2e/commands/files.cy.js • 1 failed test • 5x-driver-firefox

View Output

Test Artifacts

src/cy/commands/files > #readFile > retries to read when ENOENT

    </td>
  </tr></table>

issues/28527.cy.ts • 1 flaky test • 5x-driver-firefox

View Output

Test		Artifacts
issue 28527 > fails and then retries and verifies about:blank is not displayed		`Screenshots`

studio/studio.cy.ts • 2 flaky tests • app-e2e

View Output

Test		Artifacts
Cypress Studio > does not create a new test if the Save test modal is closed		`Test Replay` `Screenshots`
Cypress Studio > remains in studio mode when the test name is changed on the file system and file watching is disabled		`Test Replay` `Screenshots`

jennifer-shehane · 2025-06-16T13:54:41Z

packages/driver/cypress/e2e/cypress/element_selector.cy.ts

@@ -0,0 +1,86 @@
+/// <reference types="cypress" />


Converted to TypeScript - the tests are the same except for removing tests around onElement

jennifer-shehane · 2025-06-16T13:55:13Z

packages/driver/src/cypress/element_selector.ts

@@ -0,0 +1,81 @@
+/// <reference types="cypress" />


Also converted to TS. The content is the same except for removing onElement and renaming element_selector

…-selector

cacieprins

Just a couple nits regarding types - looks good!

cacieprins · 2025-06-23T15:30:29Z

packages/driver/src/cypress/element_selector.ts

+
+const VALID_SELECTOR_PRIORITY_REGEX = /^(data\-.+|id|class|tag|attributes|nth\-child|attribute:(.+)|name)$/
+
+export const DEFAULT_SELECTOR_PRIORITIES = [


Should the values here match the type we export in cypress.d.ts - Cypress.SelectorPriority[]?

I'll take another look at these comments. I added the cypress types after the fact so probably should have looked back at the code to make sure they make sense together.

No, this is actually the exact selectorPriority that Cypress will pass by default to the unique-selector, not just the TYPE of selector priorities accepted.

cacieprins · 2025-06-23T15:32:31Z

packages/driver/src/cypress/element_selector.ts

+  'nth-child',
+] as const
+
+export type SelectorType = string


Instead of this type, we should probably use Cypress.SelectorPriority, unless we accept strings that are not included in that union.

Updated the Cypress.SelectorPriority to be used everywhere.

jennifer-shehane · 2025-06-24T14:32:14Z

Pausing on merging this until the Studio side updates handling Cypress.ElementSelector to address the test failure.

…-selector

feat: Rename SelectorPriority API to ElementSelector API

3e440ec

BREAKING: Rename SelectorPriority API to ElementSelector API

jennifer-shehane changed the base branch from develop to release/15.0.0 June 13, 2025 17:34

jennifer-shehane changed the title ~~Selector playground api to element selector~~ feat: Rename SelectorPlayground API to ElementSelector API Jun 13, 2025

jennifer-shehane and others added 6 commits June 13, 2025 13:35

Merge branch 'release/15.0.0' into selector-playground-api-to-element…

139874d

…-selector

bump unique-selector + remove restriction on type of prop

e07db39

Merge branch 'selector-playground-api-to-element-selector' of https:/…

5b1eece

…/github.com/cypress-io/cypress into selector-playground-api-to-element-selector

rename file + remove test

54538a8

rename and add types to files

2ce3309

save file

080d9d6

fix types

770af77

jennifer-shehane commented Jun 16, 2025

View reviewed changes

jennifer-shehane added 2 commits June 16, 2025 11:27

Add error when Cypress.SelectorPlayground is called to suggest renaming

6866162

Add better description of ElementSelector API

e3c103e

jennifer-shehane self-assigned this Jun 16, 2025

jennifer-shehane and others added 7 commits June 17, 2025 13:52

Error on invalid selector priority types

c31f27d

changelog entry

f002750

Merge branch 'release/15.0.0' into selector-playground-api-to-element…

72e8260

…-selector

Update types to match exact type of selectorPriority

d792b66

remove semicolon

ea5816d

Add feature description for separate feature

3fa5bdb

remove the other semicolon

c909ecb

jennifer-shehane requested review from cacieprins and ryanthemanuel June 23, 2025 15:10

cacieprins approved these changes Jun 23, 2025

View reviewed changes

jennifer-shehane added 2 commits June 23, 2025 13:26

Update types to use official cypress types

8d16f65

Add other issue that this PR resolves.

8330fa3

jennifer-shehane marked this pull request as draft June 24, 2025 14:32

jennifer-shehane added 2 commits June 24, 2025 14:16

add name to selector priority

54b71a7

alphabetize strings in selectorPriority types

bd5a7f9

jennifer-shehane mentioned this pull request Jun 24, 2025

Updates for renaming SelectorPlayground to ElementSelector API cypress-io/cypress-documentation#6212

Open

jennifer-shehane marked this pull request as ready for review June 25, 2025 15:07

Merge branch 'release/15.0.0' into selector-playground-api-to-element…

d1c4948

…-selector

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat: Rename SelectorPlayground API to ElementSelector API #31889

feat: Rename SelectorPlayground API to ElementSelector API #31889

Uh oh!

jennifer-shehane commented Jun 13, 2025 •

edited

Loading

Uh oh!

cypress bot commented Jun 13, 2025 •

edited

Loading

Uh oh!

jennifer-shehane Jun 16, 2025

Uh oh!

jennifer-shehane Jun 16, 2025

Uh oh!

cacieprins left a comment

Uh oh!

cacieprins Jun 23, 2025

Uh oh!

jennifer-shehane Jun 23, 2025

Uh oh!

jennifer-shehane Jun 23, 2025

Uh oh!

cacieprins Jun 23, 2025

Uh oh!

jennifer-shehane Jun 23, 2025

Uh oh!

jennifer-shehane commented Jun 24, 2025

Uh oh!

Uh oh!


		const VALID_SELECTOR_PRIORITY_REGEX = /^(data\-.+\|id\|class\|tag\|attributes\|nth\-child\|attribute:(.+)\|name)$/

		export const DEFAULT_SELECTOR_PRIORITIES = [

feat: Rename SelectorPlayground API to ElementSelector API #31889

Are you sure you want to change the base?

feat: Rename SelectorPlayground API to ElementSelector API #31889

Uh oh!

Conversation

jennifer-shehane commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Additional details

Steps to test

How has the user experience changed?

PR Tasks

Uh oh!

cypress bot commented Jun 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Tests for review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cacieprins left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jennifer-shehane commented Jun 24, 2025

Uh oh!

Uh oh!

jennifer-shehane commented Jun 13, 2025 •

edited

Loading

cypress bot commented Jun 13, 2025 •

edited

Loading