re:re:actable
Урок 015 минут чтения

React Testing Library: философия и запросы

На этой странице
Кратко

React Testing Library (RTL) — стандарт тестирования React-компонентов. Её принцип: тест должен взаимодействовать с компонентом так же, как пользователь — находить элементы по тому, что видно и слышно (роль, доступное имя, текст, подпись поля), а не по классам, id и внутренней структуре. Поэтому RTL не даёт доступа к стейту и инстансам, а рендерит компонент в настоящий (jsdom/браузерный) DOM. Запросы различаются префиксом: getBy* — элемент должен быть, иначе ошибка; queryBy* — возвращает null (для проверки отсутствия); findBy* — асинхронно ждёт появления (до 1 с по умолчанию); *AllBy* — массив. И суффиксом — приоритет: ByRole (лучший: проверяет и доступность), ByLabelText (поля форм), ByPlaceholderText, ByText, ByDisplayValue, ByAltText, ByTitle и в последнюю очередь ByTestId. Если элемент нельзя найти по роли и имени — часто это проблема доступности самого компонента. Используй объект screen, within для поиска внутри области и screen.debug() / Testing Playground для отладки.

Вопрос

Как устроена React Testing Library и в чём её философия? Какие бывают запросы и в каком порядке их выбирать?

Минимальный тест компонента

import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { it, expect, vi } from "vitest";
import { LoginForm } from "./login-form";
 
it("отправляет email и пароль", async () => {
  const user = userEvent.setup();
  const onSubmit = vi.fn();
  render(<LoginForm onSubmit={onSubmit} />);
 
  await user.type(screen.getByLabelText("Email"), "anna@example.com");
  await user.type(screen.getByLabelText("Пароль"), "secret123");
  await user.click(screen.getByRole("button", { name: "Войти" }));
 
  expect(onSubmit).toHaveBeenCalledWith({ email: "anna@example.com", password: "secret123" });
});

Типы запросов

ПрефиксНет элементаНесколькоАсинхронноКогда
getByОшибкаОшибкаНетЭлемент точно есть
queryBynullОшибкаНетПроверить отсутствие
findByОшибка после ожиданияОшибкаДа (промис)Элемент появится
getAllBy / queryAllBy / findAllBy—Массив—Списки
expect(screen.getByRole("heading", { name: "Корзина" })).toBeInTheDocument();
expect(screen.queryByRole("alert")).not.toBeInTheDocument();      // ✓ отсутствие
expect(await screen.findByText("Заказ оформлен")).toBeInTheDocument(); // ✓ появится
expect(screen.getAllByRole("listitem")).toHaveLength(3);

Приоритет запросов

ПриоритетЗапросПример
1getByRolegetByRole("button", { name: "Сохранить" })
2getByLabelTextgetByLabelText("Email")
3getByPlaceholderTextЕсли нет подписи (лучше добавить подпись)
4getByTextНеинтерактивный текст: абзацы, сообщения
5getByDisplayValueПоле с текущим значением
6getByAltTextИзображения
7getByTitleРедко
8getByTestIdПоследний вариант: нет видимого признака

getByRole подробно

screen.getByRole("button", { name: "Удалить" });              // доступное имя (текст, aria-label, label)
screen.getByRole("button", { name: /удалить/i });             // регулярка
screen.getByRole("heading", { level: 2, name: "Отзывы" });
screen.getByRole("checkbox", { checked: true });
screen.getByRole("tab", { selected: true });
screen.getByRole("button", { expanded: false, name: "Меню" });
screen.getByRole("link", { name: "Заказ №42" });
screen.getByRole("textbox", { name: "Комментарий" });         // input/textarea
screen.getByRole("combobox", { name: "Город" });              // select или ARIA combobox
screen.getByRole("dialog", { name: "Подтвердите удаление" });
ЭлементРоль
<button>button
<a href>link
<input type="text">, <textarea>textbox
<input type="checkbox">checkbox
<input type="radio">radio
<select>combobox (или listbox с multiple)
<h1>–<h6>heading
<ul>, <li>list, listitem
<nav>, <main>, <header>navigation, main, banner
<table>, <tr>, <td>table, row, cell
<img alt="...">img

Если getByRole("button", { name: "Закрыть" }) не находит иконку-кнопку — у неё нет доступного имени, и скринридер тоже её не озвучит. Тест подсказал баг доступности: добавь aria-label.

within: поиск внутри области

const row = screen.getByRole("row", { name: /Заказ №42/ });
await user.click(within(row).getByRole("button", { name: "Отменить" }));
 
const dialog = await screen.findByRole("dialog");
expect(within(dialog).getByText("Отменить заказ №42?")).toBeInTheDocument();

Когда data-testid допустим

  • Элемент без роли и текста (контейнер графика, canvas, пустая обёртка с данными).
  • Текст динамический/переводится, а нужно найти конкретный блок.
  • Третьесторонний компонент без доступной разметки.
<div data-testid="price-chart">{/* canvas */}</div>
screen.getByTestId("price-chart");

Если getByTestId в каждом тесте — тесты не проверяют доступность, и это сигнал улучшить разметку.

Отладка

screen.debug();                         // напечатать DOM
screen.debug(screen.getByRole("form")); // часть DOM
screen.logTestingPlaygroundURL();       // ссылка на testing-playground.com с подсказкой лучшего запроса

Ошибка «Unable to find role "button" with name "Сохранить"» выводит все доступные роли и имена на странице — читай её внимательно.

Чего RTL намеренно не делает

Enzyme / старые подходыRTL
wrapper.state(), instance()Нет доступа к внутренностям
Shallow renderingРендерится всё дерево
Поиск по имени компонентаТолько по тому, что в DOM
simulate("click")user-event — реальная последовательность событий

Что важно помнить

  • Тестируй как пользователь: роль, доступное имя, текст, подпись.
  • getBy — есть; queryBy — нет; findBy — появится.
  • getByRole — первый выбор; getByTestId — последний.
  • Не находится по роли → вероятная проблема доступности.
  • screen, within, screen.debug, Testing Playground.

Мини-шпаргалка

  • render(<C />) + screen.getByRole(role, { name }).
  • queryBy... + not.toBeInTheDocument().
  • await screen.findBy....
  • within(container).getBy....
  • Приоритет: Role → LabelText → PlaceholderText → Text → DisplayValue → AltText → Title → TestId.

Документация

Дочитали до конца?
Отметьте урок — прогресс сохранится в браузере.

Поиск

Поиск по урокам