In Cypress 16, what happens to a support file calling `Cypress.SelectorPlayground`?

## What Cypress 16 actually does with the old name `Cypress.SelectorPlayground` still exists on the `Cypress` object in Cypress 16, but it is a tripwire rather than an API. Both of its methods throw the moment they are called: - `Cypress.SelectorPlayground.defaults(...)` throws a message saying it **has been renamed** to `Cypress.ElementSelector.defaults()`, and asking you to update your code. - `Cypress.SelectorPlayground.getSelector($el)` throws a message saying it **has been removed**. Both errors carry a documentation link to the ElementSelector API page. Because the call almost always lives in the Cypress support file, the throw happens while the support file is being evaluated — before the first `it()` runs — so Cypress fails the spec rather than a test, and it does so for **every** spec, since every spec loads the same support file. ## Why the rename happened The rename landed in **Cypress 15.0.0**, not 16; a project jumping from 14 straight to 16 meets it on the way through. The old name had stopped describing the thing. The priority list was never only about the Selector Playground: the same generator feeds Cypress Studio when it records a click, and `cy.prompt()` when it turns a natural-language step into commands. `Cypress.ElementSelector` names the generator rather than one of its consumers. The Selector Playground itself was not removed. It is still there in `cypress open`, and since Cypress 15.8.0 it is available to every user in open mode rather than only alongside Studio. ## The loud half and the quiet half The migration has two parts, and only one of them announces itself: | Change | How you find out | What to do | | --- | --- | --- | | `Cypress.SelectorPlayground` renamed to `Cypress.ElementSelector` | Throws, naming the replacement | Rename the object | | `getSelector($el)` removed | Throws, saying it was removed | Delete the helper; there is no replacement | | `onElement` dropped as an option to `defaults()` | **Nothing** — silently ignored | Delete it and replace what it did | | An invalid `selectorPriority` entry | Throws, listing the accepted forms | Fix the entry's spelling | `onElement` is the one that hurts. `Cypress.ElementSelector.defaults()` reads only the `selectorPriority` key and ignores everything else, so a support file that was mechanically ported — object renamed, options copied across — throws nothing, passes CI, and has quietly lost whatever `onElement` was doing. Nothing in the run output says so. ## Diagnosing it during an upgrade 1. **Read the failure location, not the test name.** Cypress reports the spec that was running, but the stack points into the support file. A failure that appears identically on every spec in the suite is almost always support-file setup, not a test. 2. **Take the error at its word.** The rename message names the exact replacement, so this half is a find-and-replace: `Cypress.SelectorPlayground.defaults` becomes `Cypress.ElementSelector.defaults`. 3. **Then diff the options object against what `defaults()` accepts.** `selectorPriority` is the only key it reads. Anything else in that object is dead, and the run will not tell you. 4. **Re-check the entries themselves.** Values that were fine before still have to satisfy the current validation: `data-*`, `attribute:*`, `id`, `class`, `tag`, `name`, `attributes`, `nth-child`. 5. **Confirm by using the tooling.** Open the Selector Playground on a room card and check that the selector it offers is the one your priority list should produce. ## What you can still do, and what is gone - **Still there:** the Selector Playground in `cypress open`, the generated-selector behaviour itself, and the `selectorPriority` option — with the same accepted values and the same default order it had before the rename. - **Renamed:** the object. `Cypress.ElementSelector` is the only spelling that works, in the support file and anywhere else you reach for it. - **Gone, loudly:** `getSelector($el)`, so nothing in a spec can ask Cypress which selector it would derive for a given element. - **Gone, quietly:** `onElement`, the hook that let a project post-process the derived selector per element. There is no equivalent, so a project that relied on it has to accept the generator's output as it comes. ## What the migrated support file looks like ```javascript // cypress/support/e2e.js Cypress.ElementSelector.defaults({ selectorPriority: ['data-cy', 'attribute:aria-label', 'name', 'id'], }) ``` That is the whole surface now. There is no `onElement` hook to customise the derived selector per element, and no `getSelector()` to ask Cypress what it would generate — the generated selector reaches you through Cypress Studio, the Selector Playground and `cy.prompt()`, not through a scriptable call. A project that had built a helper on `getSelector()` has to drop the helper rather than port it.