Cypress.SelectorPlayground

Improve this doc

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:

  • data-cy
  • data-test
  • data-testid
  • id
  • class
  • tag
  • attributes
  • 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'