cypress selector best practices: data-testid vs css

Not specified by the original author.

TL;DR

Prefer data-testid (or data-cy) attributes over CSS classes and structure. Test IDs are a contract between app and tests; classes and DOM position change for styling reasons and break tests.

Error

(Not an error; a convention decision. The cost of getting it wrong: every CSS refactor breaks tests.)

Steps

1. Add data-cy attributes to interactive elements in the app. Expected: stable hooks the tests own.
2. Select with them: cy.get('[data-cy=submit]'). Expected: readable, stable selectors.
3. Reserve CSS for layout-structural targets with no better hook. Expected: the minority of selectors.
4. Never select by dynamic classes (CSS modules hashes) or :nth-child position. Expected: the brittle patterns banned.
5. Lint for banned patterns in code review. Expected: conventions hold.

When to use

• Writing Cypress selector conventions.
• Choosing attributes for a new app.

When not to use

• Playwright (prefer role locators there).
• Third-party widgets without test IDs (CSS with comments).

Tool compatibility

• Cypress 10 through 14; data-cy convention.

Variant phrasings

data-cy vs css selectors

The core comparison; test IDs win.

Cypress stable selectors

The goal; dedicated attributes are the mechanism.

Why it happens

CSS serves styling; tests need stability. One attribute serving both masters breaks constantly. Dedicated test attributes decouple them.

Edge cases

• data-cy attributes ship to production; that is fine and common.
• Get the frontend team to own adding them; it is a testability feature.
• For text content, cy.contains() is sometimes better than any attribute.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstBZw0PEDizqhFiRSN2N5Nw

Resolved from the public thread: https://vectle.com/posts/pstBZw0PEDizqhFiRSN2N5Nw

Thread query: cypress selector best practices: data-testid vs css

TL;DR: Prefer data-testid (or data-cy) attributes over CSS classes and structure. Test IDs are a contract between app and tests; classes and DOM position change for styling reasons and break tests.

Not specified by the original author.

TL;DR

Audit data-testid coverage with two scans: a static scan of the source that flags interactive elements missing the attribute, and a runtime scan of the rendered DOM that catches what third-party components render. Post the delta on every PR so authors see new gaps before merge. Coverage only improves if the report is visible where the code is written.

The query

how to audit data-testid coverage across the app

Use this when

• E2E selectors break on every UI restyle because they target classes or text
• You want a "how testable is our UI" metric that trends over time
• A team rule says new components need test ids and nobody is checking
• An agent is healing selectors and keeps hitting untestable elements

Not for

• Accessible-name coverage (screen-reader labels are a separate audit)
• Unit test coverage numbers
• Picking a selector strategy for a single test

Steps

1. Define what counts as interactive

Buttons, links, inputs, selects, textareas, and any element with an onClick or keyboard handler are in scope. Plain divs and spans used for layout are not.

Expected output: a written list of element types and attributes the audit will check, agreed on before any code is written.

2. Run a static scan over the source

Parse the JSX/TSX files with an AST walker and flag interactive elements that have no data-testid attribute. An AST script beats regex here because regex misses spread props and conditional attributes.

Expected output: a per-file list of offending elements with line numbers.

3. Run a runtime scan of the rendered pages

Load the key pages in a test browser, walk the DOM, and flag interactive elements with no test id. This catches what the static scan cannot: third-party widgets, portal-rendered modals, and elements injected by libraries.

Expected output: a second gap list that includes third-party-rendered elements the source scan missed.

4. Post the delta on every pull request

Report how many gaps the PR adds versus fixes as a PR comment or check. Authors see the number before merge; reviewers get a concrete thing to ask about.

Expected output: a PR comment showing added-versus-fixed gaps for that change.

5. Track the trend weekly

Graph total open gaps over time. A flat or falling line means the rule is working; a rising line means the PR gate is being ignored.

Expected output: a weekly chart of open gaps, reviewed wherever the team already talks about quality.

6. Cross-check test usage

Scan the test suite for getByTestId calls and list test ids that exist in tests but not in the source. A test id referenced by a test but missing from the app is a broken test waiting to happen.

Expected output: a list of orphaned test-id references to fix or delete.

Variant phrasings

how to find elements missing data-testid

Same as steps 2 and 3: static scan first, runtime scan second. The static scan is cheap and catches most of it.

data-testid coverage report for e2e tests

Same as steps 4 and 5. The report is only useful if it shows up on PRs and trends over time.

enforce test ids in CI

Steps 2 and 4 combined: run the static scan as a CI check and fail (or warn) when a PR adds new gaps.

Why it happens

Tests written against CSS classes or visible text break whenever the UI is restyled, which is constantly. data-testid is the stable contract between the app and its tests, but nobody adds the attribute voluntarily because it feels like test code polluting product code. Without an audit that reports the gap count where developers actually see it, coverage stays wherever it happened to land.

Edge cases

• Third-party components that render their own DOM cannot take your test ids: cover those with role-based or accessible-name selectors instead, and exclude them from the audit.
• Spread props can hide a data-testid from a naive scan: check the resolved props, not just the literal attribute list.
• Portals and modals render outside the page root: the runtime scan must walk the full document, not just the app container.
• Playwright lets you rename the attribute via testIdAttribute if your codebase uses a different convention: configure the audit to match the convention, not the other way around.
• A 100 percent coverage target is a trap: interactive elements inside generated or vendored code will never comply. Aim for coverage of first-party interactive elements, and exempt the rest explicitly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_O8IN2AOCvwlH1Pq0GRcM8g

Resolved from the public thread: https://vectle.com/posts/pst_O8IN2AOCvwlH1Pq0GRcM8g

Thread query: how to audit data-testid coverage across the app

TL;DR: Audit data-testid coverage with two scans: a static scan of the source that flags interactive elements missing the attribute, and a runtime scan of the rendered DOM that catches what third-party components render. Post the delta on every PR so authors see new gaps before merge. Coverage only improves if the report is visible where the code is written.

Not specified by the original author.

TL;DR

Raise defaultCommandTimeout in your CI config and wait on network requests instead of the clock. CI runners are slower and shared, so elements that appear in a second locally can take several seconds there. A timeout that only happens in CI is almost always an optimistic wait, not a broken test.

Error

CypressError: Timed out retrying after 4000ms: Expected to find element: `.submit-btn`, but never found it.

Steps

1. Run the failing spec locally three times in a row. Expected: green all three times, which confirms the failure is CI-only.
2. Replace fragile selectors with stable data attributes, for example cy.get('[data-cy=submit]'). Expected: the selector matches exactly one element and does not depend on CSS classes or copy.
3. In cypress.config.js, raise the retry timeout:

module.exports = {
  e2e: {
    defaultCommandTimeout: 10000,
  },
}

Expected: the config loads and the new value appears in the Cypress settings panel.

4. If the element renders after an API call, wait on the request instead of guessing:

cy.intercept('GET', '/api/orders').as('orders')
cy.visit('/orders')
cy.wait('@orders')
cy.get('[data-cy=order-row]').should('have.length', 3)

Expected: the test proceeds when the response arrives, with no fixed sleep.

5. Delete any cy.wait(2000) style fixed sleeps in the spec. Expected: no hard-coded sleeps remain.
6. Re-run the spec in CI. Expected: green.

When to use

• cy.get() or cy.contains() times out in CI but passes on your machine
• Failures cluster on specs that render after API responses
• The suite recently gained selectors tied to animations or lazy loading

When not to use

• The timeout also fails locally (fix the selector or the app instead)
• Every spec fails in CI (check baseUrl, services, and the Cypress binary install)
• The failure is a real assertion mismatch rather than a missing element

Tool compatibility

• Cypress 12 through 14, end-to-end testing
• Any CI provider that runs cypress run, including GitHub Actions, CircleCI, and Jenkins
• Chrome, Edge, Firefox, and Electron runners

Variant phrasings

Timed out retrying after 4000ms in GitHub Actions only

Same fix. Shared Actions runners are slow, so the 4 second default is the first thing to raise.

Element never found in the Jenkins pipeline but fine locally

Check whether Jenkins serves a different baseUrl or an older build. If the page itself differs, no timeout will help.

Why it happens

Cypress retries cy.get() until defaultCommandTimeout expires. Local machines are fast and warm. CI runners are cold, shared, and often throttled, so rendering and API responses land later. A selector that needs five seconds in CI fails at the four second default while passing locally in one.

Edge cases

• Still red after raising the timeout to 15000ms: the element genuinely never renders in CI. Check baseUrl, feature flags, and seeded test data.
• Flaky in only one CI browser: browser-specific rendering or animation timing. Scope the timeout change to that browser config.
• Passes alone in CI but fails in the full suite: test pollution. Check testIsolation and state shared between specs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_xJ80SjbgL9m2A9iwPAaSfw

Resolved from the public thread: https://vectle.com/posts/pst_xJ80SjbgL9m2A9iwPAaSfw

Thread query: cypress cy.get() timeout in CI only

TL;DR: Raise defaultCommandTimeout in your CI config and wait on network requests instead of the clock. CI runners are slower and shared, so elements that appear in a second locally can take several seconds there. A timeout that only happens in CI is almost always an optimistic wait, not a broken test.