Query Hierarchy Signals Accessibility Gaps

React Testing Library's query priority isn't documentation preference - it's enforcing how real users interact with your UI. When "getByRole" fails and you reach for "getByTestId", you're discovering an accessibility problem, not a testing limitation. Assistive technologies navigate by role and label, not data attributes. If a button lacks a proper role or a form input has no associated label, screen readers struggle with the same queries your test does. The recommended order (role > label > placeholder > text > testId) mirrors decreasing accessibility robustness.

Query Selection Decision Tree

// Prefer: Queries by role and accessible name
const submitButton = screen.getByRole('button', { name: /submit/i });
const emailInput = screen.getByLabelText(/email address/i);

// Acceptable: When semantic HTML isn't sufficient
const errorMessage = screen.getByText(/invalid credentials/i);

// Last resort: When accessibility is genuinely impossible
const loadingSpinner = screen.getByTestId('loading-spinner');

Role queries work with implicit Accessible Rich Internet Applications (ARIA) roles from semantic HyperText Markup Language (HTML) ("button", "textbox") or explicit "role" attributes. Label queries require proper "htmlFor" connections or "aria-label". Reaching for "getByTestId" early creates tests that pass while accessibility breaks - users with screen readers face different barriers than your test suite reveals.

Async Rendering Requires Query Strategy

The difference between "findBy" and "waitFor" determines test reliability. "findBy" queries return promises that resolve when elements appear, combining "getBy" with automatic retry logic - ideal for components that fetch data then render. "waitFor" wraps assertions that need multiple checks, like text content updating after user interaction. Using synchronous "getBy" queries on async elements causes immediate "not found" errors. Conversely, wrapping everything in "waitFor" with extended timeouts masks real timing issues - you want tests to fail fast when rendering actually breaks.

Applied Insight: Test User Behavior, Not Implementation

Tests should survive component refactoring without modification. Avoid asserting on "wrapper.state()", class names, or internal methods - these pass when rendered output breaks. If converting a class component to hooks fails tests despite unchanged UI behavior, you tested implementation details. Query by role and label first, fall back to text content, and reserve "testId" for genuinely non-semantic elements like loading indicators or decorative icons where accessibility attributes don't apply.