🧪 React Testing Library Basics

Why Test Behavior, Not Internals

Imagine a quality inspector at a car factory. A bad inspector unscrews every panel to verify each bolt was torqued to spec — slow, and if the design changes, every checklist is thrown out. A great inspector drives the car: do the doors open, does the radio play, does it stop when you brake? React Testing Library (RTL) is the second inspector. It renders your component and lets you probe it from the outside — the same surface your users touch.

The alternative — reaching into a component's state, props, or private methods — is called testing implementation details. Those tests break the instant you refactor, even when the app still works perfectly. RTL's guiding principle, from its author Kent C. Dodds, is worth memorizing:

"The more your tests resemble the way your software is used, the more confidence they can give you."

RTL is not a test runner. You still need a runner like Jest or Vitest to execute tests and provide describe, test, and expect. RTL supplies the tools to render components and query the resulting DOM.

render & screen: Your First Test

Every RTL test starts by mounting a component into a virtual DOM (provided by jsdom). The render() function does that, and the screen object gives you a set of queries that search the whole rendered document. Here's a tiny component and its first test.

// Greeting.jsx — the component under test
export function Greeting({ name = 'Stranger' }) {
  return (
    <section>
      <h1>Hello, {name}!</h1>
      <p>Welcome to our application.</p>
    </section>
  );
}

// Greeting.test.jsx
import { render, screen } from '@testing-library/react';
import { Greeting } from './Greeting';

describe('Greeting', () => {
  test('renders the default greeting', () => {
    render(<Greeting />);

    // screen queries search the entire rendered output
    const heading = screen.getByRole('heading', { name: 'Hello, Stranger!' });
    expect(heading).toBeInTheDocument();
  });

  test('renders a custom name', () => {
    render(<Greeting name="Ada" />);
    expect(
      screen.getByRole('heading', { name: 'Hello, Ada!' })
    ).toBeInTheDocument();
  });
});

The RTL Cycle

Almost every RTL test follows the same four-beat rhythm. Internalize it and writing tests becomes muscle memory: render → query → interact → assert.

Simple display components skip the "interact" step — render, query, assert, done. Interactive components loop through query → interact → assert as many times as needed to walk through a scenario. Everything else in this lesson is just filling in the details of each beat.

Queries & Query Priority

A query is how you find an element. RTL deliberately steers you toward queries that mirror how users and assistive technology perceive the page. Following the recommended priority means your tests also verify your UI is accessible — a two-for-one deal.

function QueryExamples() {
  return (
    <div>
      <h1>Query Examples</h1>
      <button>Save</button>
      <label htmlFor="username">Username</label>
      <input id="username" />
      <input type="text" placeholder="Search…" />
      <img src="/logo.png" alt="Company logo" />
    </div>
  );
}

test('demonstrates the query priority in action', () => {
  render(<QueryExamples />);

  // 1. By role — the gold standard
  screen.getByRole('heading', { name: 'Query Examples' });
  screen.getByRole('button', { name: 'Save' });

  // 2. By label text — for form controls
  screen.getByLabelText('Username');

  // 3. By placeholder — when there is no label (prefer a label!)
  screen.getByPlaceholderText('Search…');

  // 6. By alt text — for images
  screen.getByAltText('Company logo');
});

getBy vs queryBy vs findBy

Each query name comes in three variants. Picking the right one is one of the most common early stumbling blocks, so let's make the rule crisp: choose based on whether the element should exist now, should be absent, or will appear later.

// getBy — must exist right now
expect(screen.getByRole('button', { name: 'Login' })).toBeInTheDocument();

// queryBy — proves something is NOT there (getBy would throw)
expect(screen.queryByRole('alert')).not.toBeInTheDocument();

// findBy — waits for an element that shows up later (note: await)
const banner = await screen.findByText('Saved!');
expect(banner).toBeInTheDocument();

Simulating Users with userEvent

To test interactive components you need to drive them. RTL's companion library @testing-library/user-event (v14) simulates real interactions far more faithfully than the older fireEvent: typing dispatches keydown/keypress/input/keyup for each character, clicking includes focus and pointer events, and so on.

Two rules for v14: call userEvent.setup() once at the start of the test, and await every interaction — they are all async.

import { useState } from 'react';

function LoginForm({ onSubmit }) {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');

  const handleSubmit = (e) => {
    e.preventDefault();
    if (!email || !password) {
      setError('All fields are required');
      return;
    }
    onSubmit({ email, password });
  };

  return (
    <form onSubmit={handleSubmit}>
      <h2>Login</h2>
      {error && <div role="alert">{error}</div>}

      <label htmlFor="email">Email</label>
      <input id="email" type="email"
             value={email} onChange={(e) => setEmail(e.target.value)} />

      <label htmlFor="password">Password</label>
      <input id="password" type="password"
             value={password} onChange={(e) => setPassword(e.target.value)} />

      <button type="submit">Login</button>
    </form>
  );
}

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

describe('LoginForm', () => {
  test('renders all fields', () => {
    render(<LoginForm onSubmit={() => {}} />);

    expect(screen.getByLabelText('Email')).toBeInTheDocument();
    expect(screen.getByLabelText('Password')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: 'Login' })).toBeInTheDocument();
  });

  test('shows an error when submitting an empty form', async () => {
    const onSubmit = jest.fn();
    const user = userEvent.setup();          // 1. set up once
    render(<LoginForm onSubmit={onSubmit} />);

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

    expect(screen.getByRole('alert')).toHaveTextContent('All fields are required');
    expect(onSubmit).not.toHaveBeenCalled();  // behavior, not internals
  });

  test('submits the entered credentials', async () => {
    const onSubmit = jest.fn();
    const user = userEvent.setup();
    render(<LoginForm onSubmit={onSubmit} />);

    await user.type(screen.getByLabelText('Email'), 'ada@example.com');
    await user.type(screen.getByLabelText('Password'), 's3cret!');
    await user.click(screen.getByRole('button', { name: 'Login' }));

    expect(onSubmit).toHaveBeenCalledWith({
      email: 'ada@example.com',
      password: 's3cret!',
    });
  });
});

Notice how these tests read almost like a QA script: "find the email box, type an address, click Login, expect the form to submit." That readability is the payoff of the user-first approach. The most common actions you'll reach for:

Assertions with jest-dom

The @testing-library/jest-dom package adds DOM-aware matchers to expect so your assertions describe intent clearly. Instead of expect(el).not.toBeNull() you write expect(el).toBeInTheDocument(). Register it once in your test setup file and every test can use it.

// setupTests.js — imported once (via Jest's setupFilesAfterEach)
import '@testing-library/jest-dom';

// A tour of the matchers you'll use most
expect(el).toBeInTheDocument();               // element is in the DOM
expect(el).toHaveTextContent('Welcome');      // contains this text
expect(input).toHaveValue('ada@example.com'); // form field value
expect(checkbox).toBeChecked();               // checkbox / radio state
expect(button).toBeDisabled();                // disabled attribute
expect(el).toBeVisible();                     // not hidden by CSS
expect(link).toHaveAttribute('href', '/home');

expect(element).toBeInTheDocument()

  received value must be an HTMLElement or an SVGElement.
  Received has value: null
    // → your query found nothing; check the role/name

Practice & Quiz

function Counter() {
  const [count, setCount] = useState(0);
  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount((c) => c + 1)}>Increment</button>
    </div>
  );
}

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

test('starts at zero', () => {
  render(<Counter />);
  expect(screen.getByText('Count: 0')).toBeInTheDocument();
});

test('increments on click', async () => {
  const user = userEvent.setup();
  render(<Counter />);

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

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

test('reveals details on demand', async () => {
  const user = userEvent.setup();
  render(<Disclosure />);

  // queryBy proves it is NOT there yet
  expect(screen.queryByRole('region')).not.toBeInTheDocument();

  await user.click(screen.getByRole('button', { name: 'Show details' }));

  // now it exists — getBy is fine
  expect(screen.getByRole('region')).toBeInTheDocument();
});

Best Practices & Pitfalls

✅ Do

• Use screen.getByRole(...) with an accessible name as your default query
• Prefer userEvent over fireEvent, and await every interaction
• Assert on what the user sees — visible text, enabled/disabled state, form values
• Give inputs real <label>s so getByLabelText and screen readers both work

❌ Don't

• Reach into component state, spy on useState, or test private methods
• Sprinkle data-testid everywhere as a shortcut around accessible queries
• Use getBy to check for absence — that throws; use queryBy
• Forget to await a findBy or a user.* call

// userEvent can't simulate a raw scroll — fireEvent can
import { fireEvent } from '@testing-library/react';
fireEvent.scroll(container, { target: { scrollTop: 500 } });

Summary

📚 Additional Resources

• Testing Library — React Testing Library intro
• Testing Library — Query priority guide
• Testing Library — user-event v14
• jest-dom — custom DOM matchers

🚀 What's Next?

You can now render, query, and interact with components. But real apps fetch data and use timers, which happen over time. The next lesson tackles that head-on: Testing Hooks and Async Code — findBy, waitFor, renderHook, and fake timers.