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 | Ошибка | Ошибка | Нет | Элемент точно есть |
queryBy | null | Ошибка | Нет | Проверить отсутствие |
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);Приоритет запросов
| Приоритет | Запрос | Пример |
|---|---|---|
| 1 | getByRole | getByRole("button", { name: "Сохранить" }) |
| 2 | getByLabelText | getByLabelText("Email") |
| 3 | getByPlaceholderText | Если нет подписи (лучше добавить подпись) |
| 4 | getByText | Неинтерактивный текст: абзацы, сообщения |
| 5 | getByDisplayValue | Поле с текущим значением |
| 6 | getByAltText | Изображения |
| 7 | getByTitle | Редко |
| 8 | getByTestId | Последний вариант: нет видимого признака |
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.