Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

Cypress times out looking for an element by data-testid

ErrorTimed out retrying after 4000ms: Expected to find element: `[data-testid=login]`, but never found it.

Short answer

Cypress retries cy.get until its timeout, then reports that it never found the element. For data-testid the usual reasons are a selector written without square brackets, testing-library commands that were never registered, an app that uses a different attribute name, an element inside shadow DOM, or an element that renders after the timeout.

  • Applies to Cypress (current docs), @testing-library/cypress, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the failing run in the Cypress app and inspect the live DOM at that step. Check whether the element exists and how its attribute is spelled, then compare it with your selector.

    npx cypress open
  2. 2Match what you see, then jump to its fix

    1. 1The log shows an expected element such as `data-testid` or `data-testid="login"` without square bracketsThe selector is not an attribute selectorFix
    2. 2The test stops on a cy.findByTestId line with an error about the command itself, before any message about a missing elementcy.findByTestId was never registeredFix
    3. 3The element is visible in the live DOM, but carries data-cy, data-test or data-test-id instead of data-testidThe app writes a different attribute name than the one the query readsFix
    4. 4The element appears in DevTools under a #shadow-root, and a selector that works in the browser console finds nothing in CypressThe element sits inside a shadow rootFix
    5. 5The element does exist once you wait, but the log reports a time-out after 4000ms on a page that loads data firstThe element renders after the 4-second command timeoutFix

What does the error look like?

  • Timed out retrying after 4000ms: Expected to find element: `[data-testid=login]`, but never found it.

Cause 1 of 5

The selector is not an attribute selector

1Check

A name on its own in cy.get is matched like a tag name, the way cy.get('button') matches buttons. An attribute needs square brackets around it.

grep -rn "cy.get('data-testid\|cy.get(\"data-testid" cypress

2Fix

Wrap the attribute in square brackets and quote the value.

cy.get('[data-testid="login"]').click()

3Verify

The command now finds the element and the test moves on to the next step.

npx cypress run --spec cypress/e2e/login.cy.js

Confirmed by docs.cypress.io

Did this fix it?

Cause 2 of 5

cy.findByTestId was never registered

1Check

The testing-library queries are not part of Cypress. They are added to cy by an import in the support commands file.

npm ls @testing-library/cypress
grep -rn "add-commands" cypress

2Fix

Install the package as a dev dependency and import its add-commands entry in your commands file.

npm install --save-dev @testing-library/cypress

// cypress/support/commands.js
import '@testing-library/cypress/add-commands'

3Verify

Run the spec again; cy.findByTestId is now a known command.

npx cypress run --spec cypress/e2e/login.cy.js

Confirmed by testing-library.com

Did this fix it?

Cause 3 of 5

The app writes a different attribute name than the one the query reads

1Check

The testing-library test id queries read data-testid unless you configure another name. Cypress's own guidance uses data-cy or data-test in its examples.

grep -rno "data-[a-z-]*=" src | sort | uniq -c | sort -rn | head

2Fix

Either rename the attribute in the app, or tell testing-library which attribute to read. Put the configuration in your Cypress support file.

import { configure } from '@testing-library/cypress'
configure({ testIdAttribute: 'data-test-id' })

3Verify

cy.findByTestId('login') now resolves for an element that has data-test-id="login".

npx cypress run --spec cypress/e2e/login.cy.js

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 4 of 5

The element sits inside a shadow root

1Check

By default Cypress does not look through shadow DOM boundaries when cy.get runs. The includeShadowDom option is false unless you change it.

grep -rn "includeShadowDom" cypress.config.js cypress.config.ts cypress

2Fix

Turn on includeShadowDom for the one command, or for the whole project in the config.

cy.get('[data-testid="login"]', { includeShadowDom: true }).click()

// or, in cypress.config.js
const { defineConfig } = require('cypress')
module.exports = defineConfig({ includeShadowDom: true })

3Verify

The command finds the element inside the shadow root.

npx cypress run --spec cypress/e2e/login.cy.js

Confirmed by docs.cypress.io

Did this fix it?

Cause 5 of 5

The element renders after the 4-second command timeout

1Check

cy.get retries for defaultCommandTimeout, which is 4000 ms. If the element only appears after a slow request, the command gives up before it exists.

grep -rn "defaultCommandTimeout" cypress.config.js cypress.config.ts

2Fix

Wait for the request the page depends on instead of guessing a delay: alias the route and wait for its response before looking for the element.

cy.intercept('/api/session').as('getSession')
cy.visit('/login')
cy.wait('@getSession')
cy.get('[data-testid="login"]').should('be.visible')

3Verify

The spec passes on repeated runs, not only on a fast machine.

npx cypress run --spec cypress/e2e/login.cy.js

Confirmed by docs.cypress.io

Did this fix it?

How do I stop it coming back?

  • Pick one test attribute name for the project, document it, and use it in every component that tests will touch.
  • Write attribute selectors with brackets and quoted values from the start, so no one learns the bare-name mistake from a failing run.
  • Wait on aliased requests, not on fixed delays, so the test follows the app's real loading order.
  • Keep the testing-library import and configuration in one support file so every spec gets the same behaviour.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.