Cypress.SelectorPlayground

The Selector Playground exposes APIs that enable you to:

• Change the default selector strategy
• Override the selectors that are returned per element

Syntax

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.

Default Selector Priority:

1. data-cy
2. data-test
3. data-testid
4. id
5. class
6. tag
7. attributes
8. nth-child

$el (Object)

The jQuery element that you want to get the selector value for.

Examples

Selector Priority

Set the selector priority to favor IDs, then classes, then attributes.

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.

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.

<button id="bingo" class="number3">Cup of tea</button>

With the default selector strategy, the selector value will be '#bingo' because IDs have priority over classes.

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'.

Cypress.SelectorPlayground.defaults({
  selectorPriority: ['class', 'id'],
})

const $el = Cypress.$('button')
const selector = Cypress.SelectorPlayground.getSelector($el) // '.number3'