breaking: Move getSelector and reset to private methods on ElementSelector API

cli/CHANGELOG.md

@@ -12,7 +12,7 @@ _Released 07/29/2025 (PENDING)_
 - `@cypress/webpack-dev-server` no longer supports `webpack-dev-server` version 4. Addresses [#31605](https://github.com/cypress-io/cypress/issues/31605). If you still need to use `webpack-dev-server` version 4, please see our [migration guide](https://docs.cypress.io/app/references/migration-guide#Migrating-to-Cypress-150).
 - In order to better align with best practices, `@cypress/webpack-batteries-included-preprocessor` no longer includes certain browser built-ins that were automatically provided by Webpack 4. The removed built-ins are `assert`, `constants`, `crypto`, `domain`, `events`, `http`, `https`, `punycode`, `querystring`, `string_decoder`, `sys`, `timers`, `tty`, `url`, `util`, `vm`, and `zlib`. However, we know that certain built-ins are popular, given that many users have files that are shared between their Cypress tests and node context. Because of this, `@cypress/webpack-batteries-included-preprocessor` will ship with built-in support for `buffer`, `path`, `process`, `os`, and `stream`. If there is a built-in that isn't supported by default and you need to add support, please refer to the Webpack [resolve.fallback](https://webpack.js.org/configuration/resolve/#resolvefallback) documentation and the [`@cypress/webpack-batteries-included-preprocessor` README](../npm/webpack-batteries-included-preprocessor/README.md). Addresses [#31039](https://github.com/cypress-io/cypress/issues/31039).
 - The application under test's `pagehide` event in Chromium browsers will no longer trigger Cypress's `window:unload` event. Addressed in [#31853](https://github.com/cypress-io/cypress/pull/31853).
-- The `Cypress.SelectorPlayground` API has been renamed to `Cypress.ElementSelector`. This API was renamed to accommodate its use for defining `selectorPriority` in Cypress Studio and our future [`cy.prompt` release](https://on.cypress.io/cy-prompt-early-access?utm_source=docs&utm_medium=app-changelog&utm_content=cy-prompt-release). Addresses [#31801](https://github.com/cypress-io/cypress/issues/31801). Addressed in [#31889](https://github.com/cypress-io/cypress/pull/31889).
+- The `Cypress.SelectorPlayground` API has been renamed to `Cypress.ElementSelector`. This API was renamed to accommodate its use for defining `selectorPriority` in Cypress Studio and our future [`cy.prompt` release](https://on.cypress.io/cy-prompt-early-access?utm_source=docs&utm_medium=app-changelog&utm_content=cy-prompt-release). Additionally, the `getSelector` method and the `onElement` option of `defaults` were removed from this API. Addresses [#31801](https://github.com/cypress-io/cypress/issues/31801). Addressed in [#31889](https://github.com/cypress-io/cypress/pull/31889) and [#32098](https://github.com/cypress-io/cypress/pull/32098).
 - **Component Testing breaking changes:**
   - Removed support for Angular 17. The minimum supported version is now `18.0.0`. Addresses [#31303](https://github.com/cypress-io/cypress/issues/31303).
   - `@cypress/angular` now requires a minimum of `zone.js` `0.14.0`. Addresses [#31582](https://github.com/cypress-io/cypress/issues/31582).

cli/types/cypress.d.ts

@@ -702,7 +702,6 @@ declare namespace Cypress {
      */
     ElementSelector: {
       defaults(options: Partial<ElementSelectorDefaultsOptions>): void
-      getSelector($el: JQuery): JQuery.Selector
     }
 
     /**

packages/app/src/runner/aut-iframe.ts

@@ -385,7 +385,7 @@ export class AutIframe {
 
     const Cypress = this.eventManager.getCypress()
 
-    const selector = Cypress.ElementSelector.getSelector($el)
+    const selector = Cypress.ElementSelector._getSelector($el)
     const selectorPlaygroundStore = useSelectorPlaygroundStore()
 
     this._addOrUpdateSelectorPlaygroundHighlight({

packages/app/src/store/studio-store.ts

@@ -520,7 +520,7 @@ export const useStudioStore = defineStore('studioRecorder', {
       if (!this._matchPreviousMouseEvent(target)) {
         this._previousMouseEvent = {
           element: target,
-          selector: getCypress().ElementSelector.getSelector(window.UnifiedRunner.CypressJQuery(target)),
+          selector: getCypress().ElementSelector._getSelector(window.UnifiedRunner.CypressJQuery(target)),
         }
       }
     },

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

@@ -2,13 +2,17 @@
 import type { ElementSelectorAPI } from '../../../src/cypress/element_selector'
 import { DEFAULT_SELECTOR_PRIORITIES } from '../../../src/cypress/element_selector'
 const { $: $cypress } = Cypress.$Cypress
-const ElementSelector = Cypress.ElementSelector as ElementSelectorAPI
+const ElementSelector = Cypress.ElementSelector as ElementSelectorAPI & {
+  _reset(): void
+  getSelectorPriority(): Cypress.SelectorPriority[]
+  _getSelector($el: any): string
+}
 
 const SELECTOR_DEFAULTS: Cypress.SelectorPriority[] = [...DEFAULT_SELECTOR_PRIORITIES]
 
 describe('src/cypress/element_selector', () => {
   beforeEach(() => {
-    ElementSelector.reset()
+    ElementSelector._reset()
   })
 
   it('has defaults', () => {
@@ -108,13 +112,13 @@ describe('src/cypress/element_selector', () => {
 
       Cypress.$('body').append($div)
 
-      expect(ElementSelector.getSelector($div)).to.eq('[data-cy="main button 123"]')
+      expect(ElementSelector._getSelector($div)).to.eq('[data-cy="main button 123"]')
 
       ElementSelector.defaults({
         selectorPriority: ['data-foo'],
       })
 
-      expect(ElementSelector.getSelector($div)).to.eq('[data-foo="bar"]')
+      expect(ElementSelector._getSelector($div)).to.eq('[data-foo="bar"]')
     })
   })
 
@@ -140,11 +144,7 @@ describe('src/cypress/element_selector', () => {
 
       expect(fn).to.throw()
       .with.property('message')
-      .and.include('`Cypress.SelectorPlayground.getSelector()` has been renamed to `Cypress.ElementSelector.getSelector()`')
-
-      expect(fn).to.throw()
-      .with.property('message')
-      .and.include('Please update your code to use `Cypress.ElementSelector` instead')
+      .and.include('`Cypress.SelectorPlayground.getSelector()` has been removed')
     })
   })
 })

packages/driver/src/cypress.ts

@@ -159,7 +159,7 @@ class $Cypress {
       })
     },
     getSelector ($el: any) {
-      $errUtils.throwErrByPath('selector_playground.renamed', {
+      $errUtils.throwErrByPath('selector_playground.removed', {
         args: { method: 'getSelector' },
       })
     },

packages/driver/src/cypress/element_selector.ts

@@ -29,10 +29,13 @@ export type ElementSelectorDefaultsOptions = {
 }
 
 export interface ElementSelectorAPI {
-  reset(): void
-  getSelectorPriority(): Cypress.SelectorPriority[]
-  getSelector($el: any): string
   defaults(options: ElementSelectorDefaultsOptions): void
+  getSelectorPriority(): Cypress.SelectorPriority[]
+}
+
+interface ElementSelectorPrivate {
+  _reset(): void
+  _getSelector($el: any): string
 }
 
 const reset = (): Defaults => {
@@ -43,21 +46,21 @@ const reset = (): Defaults => {
 
 let defaults = reset()
 
-const ElementSelector: ElementSelectorAPI = {
-  reset () {
+const ElementSelector: ElementSelectorAPI & ElementSelectorPrivate = {
+  _reset () {
     defaults = reset()
   },
 
-  getSelectorPriority () {
-    return defaults.selectorPriority
-  },
-
-  getSelector ($el: any) {
+  _getSelector ($el: any) {
     return uniqueSelector($el.get(0), {
       selectorTypes: defaults.selectorPriority,
     })
   },
 
+  getSelectorPriority () {
+    return defaults.selectorPriority
+  },
+
   defaults (props: ElementSelectorDefaultsOptions) {
     if (!_.isPlainObject(props)) {
       $errUtils.throwErrByPath('element_selector.defaults_invalid_arg', {

packages/driver/src/cypress/error_messages.ts

@@ -1740,6 +1740,12 @@ export default {
         docsUrl: 'https://on.cypress.io/element-selector-api',
       }
     },
+    removed: ({ method }: { method: string }) => {
+      return {
+        message: `\`Cypress.SelectorPlayground.${method}()\` has been removed.`,
+        docsUrl: 'https://on.cypress.io/element-selector-api',
+      }
+    },
   },
 
   server: {