Finding CSS Selectors

Element selectors tell CADENCE which part of your page to modify in a test. This guide covers how to find and use them.

What is a CSS selector?

A CSS selector identifies HTML elements on your page:

  • #hero-cta — element with id="hero-cta"
  • .button-primary — elements with class="button-primary"
  • [data-test="signup"] — elements with a data-test="signup" attribute

Finding selectors with browser DevTools

Chrome / Edge / Brave

  1. Right-click the element you want to test
  2. Click Inspect to open DevTools
  3. Right-click the highlighted HTML in the Elements panel
  4. Choose Copy > Copy selector
  5. Paste into the CADENCE selector field

Firefox

  1. Right-click element > Inspect Element
  2. Right-click highlighted HTML
  3. Copy > CSS Selector

Safari

  1. Enable the Develop menu: Preferences > Advanced > Show Develop menu
  2. Right-click element > Inspect Element
  3. Right-click highlighted HTML > Copy > Selector Path

Selector best practices

Good selectors (stable)

css
/* ID selectors — most stable */
#signup-button

/* Data attributes — best practice for testing */
[data-testid="hero-cta"]
[data-test="pricing-card"]

/* Specific classes */
.checkout-submit-button

/* Scoped combinations */
.hero-section [data-test="cta"]

Bad selectors (fragile)

css
/* Auto-generated classes — change with every build */
.css-1x2y3z4

/* Positional selectors — break when layout changes */
body > div:nth-child(3) > section > button

/* Too generic — matches many elements */
button
.button

/* Overly specific — unnecessarily long */
html > body > div > section > div > div > button

Selector types

By ID

css
#hero-cta

Most specific. Use when the element has a unique id attribute.

By class

css
.pricing-button
.btn-primary

Use for styled elements. May match multiple elements.

By data attribute

css
[data-testid="signup"]
[data-test="cta"]

Recommended. Add these attributes specifically for testing. They won't change when styles change.

By descendant

css
.hero-section .cta-button
#pricing-page [data-test="submit"]

Target elements within containers for more precision.

Testing your selector

In the browser console

Open DevTools (F12) and run:

javascript
// Check if selector matches an element
document.querySelector('#hero-cta')
// Returns the element, or null if not found

// Check how many elements match
document.querySelectorAll('.cta-button').length
// Returns the count — ideally 1 for test selectors

In your test code

After deploying test code to staging, check the browser console for CADENCE logs. If the selector doesn't match, you'll see:

[CADENCE] Element not found: #wrong-selector

Common scenarios

Testing a button

css
/* Best: data attribute */
[data-test="signup-button"]

/* Good: specific class */
.hero-cta-button

/* OK: ID */
#signup-cta

Testing a headline

css
/* Best: data attribute */
[data-test="hero-headline"]

/* OK: scoped selector */
.hero-section h1

/* Avoid: too generic */
h1

Testing a form

css
/* Best: form by data attribute */
[data-test="signup-form"]

/* Good: form by ID */
#email-signup-form

/* For inputs within a form */
[data-test="signup-form"] input[name="email"]

Adding data attributes for testing

Data attributes are the most stable selector strategy. They don't change when you update styles or refactor CSS classes.

Add them to your HTML:

html
<!-- Before -->
<button class="btn btn-primary">Sign Up</button>

<!-- After -->
<button class="btn btn-primary" data-test="signup-cta">Sign Up</button>

Then use the selector: [data-test="signup-cta"]

Troubleshooting

Selector returns nothing

  • Verify the element exists on the page
  • Check spelling and case sensitivity
  • Test the selector in DevTools console
  • Make sure the page is fully loaded before the test runs

Selector matches multiple elements

  • Be more specific (add a parent container)
  • Use a unique ID or data attribute
  • Test with document.querySelectorAll() to see all matches

Variant changes don't apply

  • Check that the selector is correct
  • Verify the element is visible (not hidden by CSS)
  • Check the browser console for JavaScript errors
  • Ensure the test is running on the correct URL pattern

Next steps