testing-library

Testing Library

Simple and complete testing utilities that encourage good testing practices.

Quick Start

Install (React):

npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event

Install (Vue):

npm install --save-dev @testing-library/vue

Basic Test

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

test('renders button with text', () => {
  render(<Button>Click me</Button>);

  expect(screen.getByRole('button', { name: /click me/i })).toBeInTheDocument();
});

test('calls onClick when clicked', async () => {
  const user = userEvent.setup();
  const handleClick = vi.fn();

  render(<Button onClick={handleClick}>Click me</Button>);

  await user.click(screen.getByRole('button'));

  expect(handleClick).toHaveBeenCalledTimes(1);
});

Queries

Query Priority (Accessibility First)

// 1. Accessible to everyone
screen.getByRole('button', { name: /submit/i });
screen.getByLabelText(/email/i);
screen.getByPlaceholderText(/search/i);
screen.getByText(/welcome/i);
screen.getByDisplayValue(/john/i);

// 2. Semantic queries
screen.getByAltText(/profile/i);
screen.getByTitle(/close/i);

// 3. Test IDs (last resort)
screen.getByTestId('submit-button');

Query Types

// getBy* - Throws if not found (for elements that should exist)
screen.getByRole('button');

// queryBy* - Returns null if not found (for asserting absence)
expect(screen.queryByRole('dialog')).not.toBeInTheDocument();

// findBy* - Returns Promise, waits for element (for async)
await screen.findByText('Loaded!');

// getAllBy* - Returns array of all matching elements
screen.getAllByRole('listitem');

// queryAllBy* - Returns empty array if none found
expect(screen.queryAllByRole('alert')).toHaveLength(0);

// findAllBy* - Returns Promise of array
await screen.findAllByRole('option');

Query by Role

// Button
screen.getByRole('button', { name: /submit/i });

// Link
screen.getByRole('link', { name: /learn more/i });

// Textbox
screen.getByRole('textbox', { name: /email/i });

// Checkbox
screen.getByRole('checkbox', { name: /agree/i });

// Radio
screen.getByRole('radio', { name: /option 1/i });

// Combobox (select)
screen.getByRole('combobox', { name: /country/i });

// Heading
screen.getByRole('heading', { name: /welcome/i, level: 1 });

// List
screen.getByRole('list');
screen.getAllByRole('listitem');

// Navigation
screen.getByRole('navigation');

// Dialog
screen.getByRole('dialog');

// Alert
screen.getByRole('alert');

// Tab
screen.getByRole('tab', { name: /settings/i });
screen.getByRole('tabpanel');

Query Options

// Case insensitive regex (recommended)
screen.getByText(/hello world/i);

// Exact string
screen.getByText('Hello World', { exact: true });

// Substring
screen.getByText('Hello', { exact: false });

// Custom function
screen.getByText((content, element) => {
  return element?.tagName === 'SPAN' && content.includes('Hello');
});

// Hidden elements
screen.getByRole('button', { hidden: true });

User Events

Setup

import userEvent from '@testing-library/user-event';

test('user interactions', async () => {
  const user = userEvent.setup();

  render(<MyComponent />);

  // All interactions are async
  await user.click(screen.getByRole('button'));
});

Click Events

const user = userEvent.setup();

// Single click
await user.click(element);

// Double click
await user.dblClick(element);

// Right click
await user.pointer({ keys: '[MouseRight]', target: element });

// Hover
await user.hover(element);
await user.unhover(element);

Keyboard Events

const user = userEvent.setup();

// Type text
await user.type(input, 'Hello World');

// Type with special keys
await user.type(input, 'Hello{Enter}');
await user.type(input, '{Shift>}hello{/Shift}'); // HELLO

// Clear and type
await user.clear(input);
await user.type(input, 'New value');

// Tab navigation
await user.tab();

// Keyboard shortcuts
await user.keyboard('{Control>}a{/Control}'); // Select all
await user.keyboard('{Control>}c{/Control}'); // Copy

Form Interactions

const user = userEvent.setup();

// Select option
await user.selectOptions(select, 'option-value');
await user.selectOptions(select, ['opt1', 'opt2']); // Multiple

// Checkbox
await user.click(checkbox);

// File upload
const file = new File(['hello'], 'hello.png', { type: 'image/png' });
await user.upload(fileInput, file);

// Paste
await user.paste('pasted text');

Async Utilities

waitFor

import { waitFor } from '@testing-library/react';

test('shows success after submit', async () => {
  const user = userEvent.setup();

  render(<Form />);

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

  await waitFor(() => {
    expect(screen.getByText(/success/i)).toBeInTheDocument();
  });
});

// With options
await waitFor(
  () => {
    expect(screen.getByText(/loaded/i)).toBeInTheDocument();
  },
  { timeout: 3000, interval: 100 }
);

findBy Queries

// findBy = getBy + waitFor
const element = await screen.findByText(/loaded/i);

// With timeout
const element = await screen.findByRole('dialog', {}, { timeout: 5000 });

waitForElementToBeRemoved

import { waitForElementToBeRemoved } from '@testing-library/react';

test('loading disappears', async () => {
  render(<AsyncComponent />);

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

  expect(screen.getByText(/content/i)).toBeInTheDocument();
});

Component Testing

React

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

describe('Counter', () => {
  test('increments counter on click', async () => {
    const user = userEvent.setup();

    render(<Counter initialCount={0} />);

    expect(screen.getByText('Count: 0')).toBeInTheDocument();

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

    expect(screen.getByText('Count: 1')).toBeInTheDocument();
  });
});

With Providers

function renderWithProviders(
  ui: React.ReactElement,
  { initialState, ...options }: RenderOptions = {}
) {
  function Wrapper({ children }: { children: React.ReactNode }) {
    return (
      <QueryClientProvider client={queryClient}>
        <ThemeProvider>{children}</ThemeProvider>
      </QueryClientProvider>
    );
  }

  return render(ui, { wrapper: Wrapper, ...options });
}

test('renders with providers', () => {
  renderWithProviders(<MyComponent />);
  // ...
});

Form Testing

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

describe('LoginForm', () => {
  test('submits form with user data', async () => {
    const user = userEvent.setup();
    const onSubmit = vi.fn();

    render(<LoginForm onSubmit={onSubmit} />);

    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /sign in/i }));

    await waitFor(() => {
      expect(onSubmit).toHaveBeenCalledWith({
        email: 'test@example.com',
        password: 'password123',
      });
    });
  });

  test('shows validation errors', async () => {
    const user = userEvent.setup();

    render(<LoginForm onSubmit={vi.fn()} />);

    await user.click(screen.getByRole('button', { name: /sign in/i }));

    expect(await screen.findByText(/email is required/i)).toBeInTheDocument();
    expect(await screen.findByText(/password is required/i)).toBeInTheDocument();
  });
});

jest-dom Matchers

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

// Visibility
expect(element).toBeVisible();
expect(element).not.toBeVisible();

// Presence
expect(element).toBeInTheDocument();
expect(element).not.toBeInTheDocument();

// Content
expect(element).toHaveTextContent(/hello/i);
expect(element).toContainHTML('<span>Hello</span>');

// Form state
expect(input).toHaveValue('test');
expect(input).toBeDisabled();
expect(input).toBeEnabled();
expect(input).toBeRequired();
expect(input).toBeValid();
expect(input).toBeInvalid();
expect(checkbox).toBeChecked();

// Attributes
expect(element).toHaveAttribute('href', '/about');
expect(element).toHaveClass('active');
expect(element).toHaveStyle({ display: 'flex' });

// Focus
expect(input).toHaveFocus();

// Accessibility
expect(element).toHaveAccessibleName('Submit form');
expect(element).toHaveAccessibleDescription('Click to submit');

Mocking

Mock Functions

test('calls callback on click', async () => {
  const user = userEvent.setup();
  const handleClick = vi.fn();

  render(<Button onClick={handleClick}>Click</Button>);

  await user.click(screen.getByRole('button'));

  expect(handleClick).toHaveBeenCalledTimes(1);
  expect(handleClick).toHaveBeenCalledWith(expect.any(Object));
});

Mock API (with MSW)

import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

const server = setupServer(
  http.get('/api/user', () => {
    return HttpResponse.json({ name: 'John' });
  })
);

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

test('loads and displays user', async () => {
  render(<UserProfile />);

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

Debugging

// Print DOM
screen.debug();

// Print specific element
screen.debug(screen.getByRole('button'));

// Log testing playground URL
screen.logTestingPlaygroundURL();

// Get accessible roles
import { getRoles } from '@testing-library/dom';
console.log(getRoles(container));

Best Practices

1. Query by role - Most accessible selector
2. Use userEvent - Not fireEvent
3. Avoid implementation details - Test behavior
4. Use findBy for async - Not getBy + waitFor
5. Test from user perspective - What they see/do

Common Mistakes

Reference Files

• references/queries.md - All query types
• references/matchers.md - jest-dom matchers
• references/async.md - Async patterns