React Testing Library: getBy vs queryBy vs findBy

Tests fail with cryptic errors because the wrong query type was used — getBy throws immediately, queryBy returns null, findBy is async. Choosing the wrong one causes misleading test failures.

Use the right query type based on expected element presence and timing.

import { render, screen } from '@testing-library/react';

// getBy* — expects element to exist NOW, throws if not found
const button = screen.getByRole('button', { name: 'Submit' });
// Use when: element should be in the DOM synchronously

// queryBy* — returns null if not found (no throw)
const error = screen.queryByText('Error message');
if (error) { /* handle */ }
// Use when: asserting an element is NOT present
expect(screen.queryByText('Loading...')).not.toBeInTheDocument();

// findBy* — async, waits for element to appear (returns Promise)
const user = await screen.findByText('Alice');
// Use when: element appears after async operation (fetch, setTimeout)

// Priority order (accessibility-first):
// 1. getByRole
// 2. getByLabelText
// 3. getByPlaceholderText
// 4. getByText
// 5. getByDisplayValue
// Avoid: getByTestId (last resort)

getBy throws synchronously — good for asserting presence. queryBy returns null — good for asserting absence. findBy polls with waitFor internally — good for async rendering.