Cypress times out looking for an element by data-testid
Timed 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.
Fix it fast
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 open2Match what you see, then jump to its fix
- 1
The log shows an expected element such as `data-testid` or `data-testid="login"` without square bracketsThe selector is not an attribute selectorFix - 2
The 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
The 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
The 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
The 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
- 1
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" cypress2Fix
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.jsConfirmed by docs.cypress.io
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" cypress2Fix
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.jsConfirmed by testing-library.com
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 | head2Fix
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.jsConfirmed by raw.githubusercontent.com
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 cypress2Fix
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.jsConfirmed by docs.cypress.io
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.ts2Fix
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.jsConfirmed by docs.cypress.io
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fixWeb apps
axios gets 429 Too Many Requests from a React app
429 (Too Many Requests)
A 429 comes from the server or an API gateway, not from axios: your client sent too many requests in a window.
4 causes, each with a fixWeb apps
Axios request is not cancelled when a React component unmounts
A cancelled request is logged as an error in the catch block
Axios cancels a request when you pass it an AbortSignal and later call abort() on its controller.
4 causes, each with a fix