In Cypress, what does setting `selectorPriority` via `Cypress.ElementSelector` control?

## What the API configures, and what it does not `Cypress.ElementSelector.defaults({ selectorPriority: [...] })` configures the **selector generator**, not the query engine. Several parts of Cypress have to look at an element you pointed at and write down a selector that identifies it: Cypress Studio when it records a click on a room card, the Selector Playground in `cypress open` when you hover an element, and `cy.prompt()` when it turns a natural-language step into commands. `selectorPriority` is the ranked list of attribute kinds those tools walk. It has **no effect on `cy.get()`**. A selector you typed is passed through unchanged; nothing rewrites it, reorders it or prefers a different attribute on your behalf. This is the most common misreading of the API and it is worth saying out loud in an interview before anything else. ## The default order in Cypress 16 As of Cypress 16 the built-in priority list is, in order: 1. `data-cy` 2. `data-test` 3. `data-testid` 4. `data-qa` 5. `name` 6. `id` 7. `class` 8. `tag` 9. `attributes` 10. `nth-child` The four dedicated test-attribute conventions come first, then the semantic `name` attribute, then the identifiers an application also styles and scripts against, and finally the structural fallbacks. Point the Selector Playground at a `<button data-cy="book-room" id="book-btn" class="primary">` and you get `[data-cy="book-room"]`, not `#book-btn`. ## What the array accepts Every entry is validated, and an unrecognised one throws immediately: | Entry form | Meaning | Example | | --- | --- | --- | | `data-<name>` | one specific data attribute | `data-cy`, `data-qa` | | `attribute:<name>` | one specific non-data attribute | `attribute:aria-label`, `attribute:role` | | `attributes` | any remaining attribute, as a fallback | `attributes` | | `id` / `class` / `tag` / `name` | that kind of selector | `id` | | `nth-child` | positional fallback | `nth-child` | The trap is the `attribute:` prefix. `data-` is the only prefix that stands alone, so `data-cy` is valid but a bare `aria-label` is not — it has to be written `attribute:aria-label`. Passing anything else throws with a message listing the accepted forms, and passing a non-array throws a separate error. Both throws happen at the call site, so a bad support file fails every spec before its first test. ## Why your first choice can still lose Cypress guarantees the generated selector is **unique in the document**; it only *attempts* to follow your priority. Two things follow from that: - If the highest-priority attribute is present but not unique — every room card in the list carries `data-cy="room-card"` — Cypress may skip it or combine it with something else to disambiguate. - If nothing on your list is present on the element, Cypress works with whatever the rest of the list leaves it, which is why stripping the list down to a single entry usually makes generated selectors worse rather than cleaner. The documentation is also explicit that `selectorPriority` is under active development and may change, so a list a team pins today is upgrade surface tomorrow. ## Where the call belongs, and how it behaves - **Put it in the Cypress support file** (`cypress/support/e2e.js` by default). The support file is loaded before every spec, so one call covers the suite; a call inside a single spec lasts only for that spec's run. - **The array replaces, it does not merge.** `defaults({ selectorPriority: ['data-cy'] })` leaves exactly one entry, not eleven. Every fallback you want has to be listed explicitly. - **`defaults({})` is a no-op.** The function reads only the `selectorPriority` key, so an empty object leaves the current list in place, and there is no public reset. It also means an unrecognised key is ignored in silence rather than rejected. - **It is configuration, not a command.** It runs synchronously outside the Cypress command queue and is never chained onto `cy`. ## A worked example A hotel booking project that has standardised on `data-cy`, and wants ARIA labels as the next-best thing, would write: ```javascript // cypress/support/e2e.js Cypress.ElementSelector.defaults({ selectorPriority: [ 'data-cy', 'attribute:aria-label', 'name', 'id', 'attributes', ], }) ``` Recording a click on the check-in field in Cypress Studio then produces `[data-cy="check-in-date"]`, which the default order would also have produced. The difference shows up on a control that has no test attribute yet: it now falls to its `aria-label` rather than to a hashed CSS class, because `class` was deliberately left off the list.