React Testing Library Best Practices

React Testing Library encourages testing components the way users interact with them. Here's how to write effective tests.

Query Priority#

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

// Queries ordered by priority (most to least accessible)
function TestComponent() {
  return (
    <form>
      {/* 1. getByRole - Most preferred */}
      <button>Submit</button>
      <input type="text" />

      {/* 2. getByLabelText - For form elements */}
      <label htmlFor="email">Email</label>
      <input id="email" type="email" />

      {/* 3. getByPlaceholderText - When no label */}
      <input placeholder="Search..." />

      {/* 4. getByText - For non-interactive elements */}
      <p>Welcome message</p>

      {/* 5. getByDisplayValue - For filled inputs */}
      <input value="current value" readOnly />

      {/* 6. getByAltText - For images */}
      <img src="logo.png" alt="Company Logo" />

      {/* 7. getByTitle - Rarely used */}
      <span title="Close">×</span>

      {/* 8. getByTestId - Last resort */}
      <div data-testid="custom-element">Custom</div>
    </form>
  );
}

test('uses appropriate queries', () => {
  render(<TestComponent />);

  // Prefer role queries
  expect(screen.getByRole('button', { name: /submit/i })).toBeInTheDocument();
  expect(screen.getByRole('textbox', { name: /email/i })).toBeInTheDocument();

  // Use text for static content
  expect(screen.getByText(/welcome message/i)).toBeInTheDocument();

  // Use testId only when necessary
  expect(screen.getByTestId('custom-element')).toBeInTheDocument();
});

User Events#

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

// Setup userEvent with options
function setup(jsx: React.ReactElement) {
  return {
    user: userEvent.setup(),
    ...render(jsx),
  };
}

// Form interaction
test('submits form with user data', async () => {
  const handleSubmit = jest.fn();
  const { user } = setup(<LoginForm onSubmit={handleSubmit} />);

  // Type in inputs
  await user.type(screen.getByLabelText(/email/i), 'test@example.com');
  await user.type(screen.getByLabelText(/password/i), 'password123');

  // Click submit
  await user.click(screen.getByRole('button', { name: /login/i }));

  expect(handleSubmit).toHaveBeenCalledWith({
    email: 'test@example.com',
    password: 'password123',
  });
});

// Keyboard interactions
test('navigates with keyboard', async () => {
  const { user } = setup(<NavigableList items={['A', 'B', 'C']} />);

  // Tab through elements
  await user.tab();
  expect(screen.getByText('A')).toHaveFocus();

  await user.tab();
  expect(screen.getByText('B')).toHaveFocus();

  // Arrow keys
  await user.keyboard('{ArrowDown}');

  // Enter to select
  await user.keyboard('{Enter}');
});

// Complex interactions
test('drag and drop', async () => {
  const { user } = setup(<DragDropList />);

  const draggable = screen.getByText('Item 1');
  const dropzone = screen.getByTestId('dropzone');

  await user.pointer([
    { keys: '[MouseLeft>]', target: draggable },
    { coords: { x: 200, y: 200 } },
    { target: dropzone },
    { keys: '[/MouseLeft]' },
  ]);
});

Async Testing#

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

// Wait for element to appear
test('loads data asynchronously', async () => {
  render(<UserProfile userId="123" />);

  // Loading state
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  // Wait for data
  const userName = await screen.findByText('John Doe');
  expect(userName).toBeInTheDocument();
});

// Wait for element to disappear
test('removes loading indicator', async () => {
  render(<UserProfile userId="123" />);

  await waitForElementToBeRemoved(() => screen.queryByText(/loading/i));

  expect(screen.getByText('John Doe')).toBeInTheDocument();
});

// Custom waitFor conditions
test('waits for multiple conditions', async () => {
  render(<Dashboard />);

  await waitFor(() => {
    expect(screen.getByText('Users: 10')).toBeInTheDocument();
    expect(screen.getByText('Orders: 25')).toBeInTheDocument();
  });
});

// Avoid false positives with findBy
test('handles async errors', async () => {
  // Mock API error
  server.use(
    rest.get('/api/user', (req, res, ctx) => {
      return res(ctx.status(500));
    })
  );

  render(<UserProfile userId="123" />);

  // Use findBy for async elements
  const errorMessage = await screen.findByRole('alert');
  expect(errorMessage).toHaveTextContent(/failed to load/i);
});

Testing Hooks#

import { renderHook, act } from '@testing-library/react';

// Test custom hook
function useCounter(initialValue = 0) {
  const [count, setCount] = useState(initialValue);

  const increment = () => setCount((c) => c + 1);
  const decrement = () => setCount((c) => c - 1);
  const reset = () => setCount(initialValue);

  return { count, increment, decrement, reset };
}

test('useCounter increments', () => {
  const { result } = renderHook(() => useCounter(0));

  expect(result.current.count).toBe(0);

  act(() => {
    result.current.increment();
  });

  expect(result.current.count).toBe(1);
});

// Hook with dependencies
test('useCounter with initial value', () => {
  const { result, rerender } = renderHook(
    ({ initial }) => useCounter(initial),
    { initialProps: { initial: 10 } }
  );

  expect(result.current.count).toBe(10);

  // Update props
  rerender({ initial: 20 });

  act(() => {
    result.current.reset();
  });

  expect(result.current.count).toBe(20);
});

// Hook with context
test('hook with provider', () => {
  const wrapper = ({ children }: { children: React.ReactNode }) => (
    <ThemeProvider theme="dark">{children}</ThemeProvider>
  );

  const { result } = renderHook(() => useTheme(), { wrapper });

  expect(result.current.theme).toBe('dark');
});

Mocking#

// Mock modules
jest.mock('./api', () => ({
  fetchUser: jest.fn(),
}));

import { fetchUser } from './api';

test('handles API data', async () => {
  (fetchUser as jest.Mock).mockResolvedValue({ name: 'John' });

  render(<UserProfile />);

  await screen.findByText('John');
});

// Mock with MSW (Mock Service Worker)
import { rest } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  rest.get('/api/user/:id', (req, res, ctx) => {
    return res(ctx.json({ id: req.params.id, name: 'John Doe' }));
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test('fetches and displays user', async () => {
  render(<UserProfile userId="123" />);

  expect(await screen.findByText('John Doe')).toBeInTheDocument();
});

// Override handlers per test
test('handles errors', async () => {
  server.use(
    rest.get('/api/user/:id', (req, res, ctx) => {
      return res(ctx.status(500), ctx.json({ error: 'Server error' }));
    })
  );

  render(<UserProfile userId="123" />);

  expect(await screen.findByRole('alert')).toHaveTextContent(/error/i);
});

Testing Patterns#

// Page Object Pattern
class LoginPage {
  get emailInput() {
    return screen.getByLabelText(/email/i);
  }

  get passwordInput() {
    return screen.getByLabelText(/password/i);
  }

  get submitButton() {
    return screen.getByRole('button', { name: /login/i });
  }

  async login(user: ReturnType<typeof userEvent.setup>, email: string, password: string) {
    await user.type(this.emailInput, email);
    await user.type(this.passwordInput, password);
    await user.click(this.submitButton);
  }
}

test('login flow', async () => {
  const { user } = setup(<LoginForm />);
  const page = new LoginPage();

  await page.login(user, 'test@example.com', 'password');

  expect(await screen.findByText(/welcome/i)).toBeInTheDocument();
});

// Render with providers utility
function renderWithProviders(
  ui: React.ReactElement,
  {
    preloadedState = {},
    store = configureStore({ reducer, preloadedState }),
    ...renderOptions
  } = {}
) {
  function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <Provider store={store}>
        <ThemeProvider>
          <Router>{children}</Router>
        </ThemeProvider>
      </Provider>
    );
  }

  return {
    store,
    user: userEvent.setup(),
    ...render(ui, { wrapper: Wrapper, ...renderOptions }),
  };
}

// Accessibility testing
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('component is accessible', async () => {
  const { container } = render(<Navigation />);

  const results = await axe(container);
  expect(results).toHaveNoViolations();
});

Common Assertions#

import '@testing-library/jest-dom';

test('element states', () => {
  render(<Form />);

  // Visibility
  expect(screen.getByText('Visible')).toBeVisible();
  expect(screen.getByText('Hidden')).not.toBeVisible();

  // Enabled/Disabled
  expect(screen.getByRole('button')).toBeEnabled();
  expect(screen.getByRole('textbox')).toBeDisabled();

  // Checked
  expect(screen.getByRole('checkbox')).toBeChecked();

  // Values
  expect(screen.getByRole('textbox')).toHaveValue('initial');
  expect(screen.getByRole('textbox')).toHaveDisplayValue('initial');

  // Classes
  expect(screen.getByText('Error')).toHaveClass('error');

  // Attributes
  expect(screen.getByRole('link')).toHaveAttribute('href', '/home');

  // Focus
  expect(screen.getByRole('textbox')).toHaveFocus();

  // Form validity
  expect(screen.getByRole('textbox')).toBeInvalid();
  expect(screen.getByRole('textbox')).toHaveErrorMessage(/required/i);
});

Best Practices#

Queries:
✓ Prefer role queries
✓ Use accessible names
✓ Avoid testId when possible
✓ Use findBy for async elements

User Events:
✓ Use userEvent over fireEvent
✓ Always await user actions
✓ Test keyboard accessibility
✓ Test realistic user flows

Assertions:
✓ Assert on user-visible output
✓ Avoid testing implementation
✓ Test accessibility
✓ Keep assertions focused

Organization:
✓ One assertion focus per test
✓ Use describe blocks for grouping
✓ Extract common setup
✓ Use meaningful test names

React Testing Library encourages testing from the user's perspective. Prioritize accessible queries, use userEvent for interactions, and assert on visible output rather than implementation details. This approach leads to more maintainable tests that give confidence in your application's behavior.