This error occurs when React Testing Library cannot find an element with the specified ARIA role during testing. It often happens when elements are not properly accessible, have incorrect roles, or are rendered asynchronously.
The "Unable to query by role" error indicates that React Testing Library's query methods (getByRole, findByRole, etc.) cannot locate an element with the specified role in the rendered DOM. This can happen due to several reasons including incorrect role assignment, elements not being accessible, asynchronous rendering not being handled properly, or the element being hidden from the accessibility tree.
Inspect the rendered DOM to ensure the element has the expected role. For example, a <button> element has an implicit role of "button". If using a custom element, you may need to add role="button" explicitly.
// Good: button element has implicit role
<button>Click me</button>
// Good: div with explicit role
<div role="button">Click me</div>
// Problematic: div without role
<div onClick={handleClick}>Click me</div> // No roleEnsure the element is not hidden from the accessibility tree. Elements with aria-hidden="true", display: none, or visibility: hidden are excluded by default. Also check if parent elements have aria-hidden="true".
// Problematic: hidden from accessibility
<div aria-hidden="true">
<button>This button won't be found</button>
</div>
// Solution: remove aria-hidden or use { hidden: true } option
const button = screen.getByRole('button', { hidden: true });If the element renders asynchronously, use findByRole instead of getByRole. findByRole returns a Promise and waits for the element to appear (default timeout is 1000ms).
// Using getByRole (fails if element not immediately present)
// const button = screen.getByRole('button');
// Using findByRole (waits for element)
const button = await screen.findByRole('button');
// You can also increase timeout if needed
const button = await screen.findByRole('button', {}, { timeout: 5000 });Some elements may have different implicit roles in newer versions of Testing Library. For example, certain Material-UI components changed from role="button" to role="combobox". Check the Testing Library documentation and your component library's release notes.
// Old query (may fail after upgrade)
screen.getByRole('button', { name: /Ernie Variable 1/i });
// New query for combobox
screen.getByRole('combobox', { name: /Ernie Variable 1/i });Some roles require additional options like name for elements with accessible names. Check that you're providing the correct options for your query.
// Button with accessible name via aria-label
<button aria-label="Submit form">Submit</button>
// Query with name option
const button = screen.getByRole('button', { name: /submit form/i });
// Button with text content (implicit name)
<button>Save changes</button>
// Query with name from text content
const saveButton = screen.getByRole('button', { name: /save changes/i });Use screen.debug() to see the entire rendered DOM and verify what roles are available. This can help identify if the element has the expected role or if there are other issues.
import { screen } from '@testing-library/react';
// Render your component
render(<MyComponent />);
// Print the DOM to console
screen.debug();
// Print only accessible elements
screen.logTestingPlaygroundURL();
// Check available roles
console.log(screen.getAllByRole('button'));React Testing Library uses the Accessibility Tree (computed by the browser) rather than just the DOM structure. This means elements must be accessible to be found by role queries. The hidden option can be used to include elements that are normally excluded from the accessibility tree. Also note that role="presentation" and role="none" completely remove elements from the accessibility tree, which differs from aria-hidden="true". When testing complex components like Material-UI or Chakra UI, check their documentation for correct role usage as these libraries may use non-standard ARIA patterns.
React Hook useCallback has a missing dependency: 'variable'. Either include it or remove the dependency array react-hooks/exhaustive-deps
React Hook useCallback has a missing dependency
Cannot use private fields in class components without TS support
Cannot use private fields in class components without TS support
Cannot destructure property 'xxx' of 'undefined'
Cannot destructure property of undefined when accessing props
useNavigate() may be used only in the context of a <Router> component.
useNavigate() may be used only in the context of a Router component
Cannot find module or its corresponding type declarations
How to fix "Cannot find module or type declarations" in Vite