RTL и user-event: тестируйте контракт, который видит пользователь

Запрос — это и есть проверка

Главный принцип Testing Library — тесты должны походить на то, как софт используют, — не лозунг: он закодирован в API запросов как порядок приоритета, и каждый шаг вниз по этому порядку отдаёт класс регрессий, который тест способен поймать. getByRole запрашивает вычисленное дерево доступности — ту же структуру, которую потребляют вспомогательные технологии, — а опция name фиксирует доступное имя (вычисляемое из label, aria-label, aria-labelledby или текста по алгоритму accname W3C). Запрос по роли — это две проверки в одной: элемент существует и он показан пользователю как правильный тип контрола с правильным именем. getByLabelText проверяет привязку подписи к полю формы — htmlFor, обёртывание или aria-labelledby — ровно ту связь, которую разрешает скринридер; визуально соседняя, но не привязанная подпись проходит проверку getByText и валит эту. getByText утверждает видимый контент для неинтерактивных элементов. getByTestId не утверждает ничего, кроме того, что тест и разметка согласны насчёт одной строки. Это осознанный аварийный люк — область с canvas, сторонний виджет, чью разметку вы не можете поправить, — а не дефолт.

screen запрашивает весь документ. within(node) ограничивает запросы поддеревом — и ради читаемости («кнопка Save внутри этого диалога»), и ради производительности на больших DOM, что важнее, чем ожидает большинство команд (цифры ниже).

Что на самом деле диспатчит user-event

fireEvent.click диспатчит ровно одно синтетическое MouseEvent. Реальный клик пользователя — это последовательность: pointerover → pointerenter → pointermove → pointerdown → mousedown → focus → pointerup → mouseup → click — и user-event v14 проигрывает всё взаимодействие целиком, порядка девяти событий с правильным порядком, координатами и побочными эффектами фокуса. user.type диспатчит keydown → keypress → input → keyup на каждый символ: строка из 20 символов — это 80 с лишним событий, каждое из которых уважает maxLength, disabled, readonly и текущее выделение. fireEvent.change телепортирует значение в инпут целиком — он никогда не вызывает обработчики keydown, его не ограничивает maxLength, и он даст зелёный свет состояниям, которые пользователь буквально не может создать. Компонент, отправляющий форму по Enter через onKeyDown, нетестируем через fireEvent.change и тривиально тестируется через await user.type(input, "query{Enter}").

Механика v14 важна на код-ревью. const user = userEvent.setup() до render создаёт инстанс, привязанный к одному согласованному состоянию устройств ввода (клавиатура, указатель, буфер обмена). Каждый API асинхронный — await user.click(...) — потому что user-event уступает поток между событиями цепочки, чтобы React успевал коммитить промежуточное состояние, как реальный браузер перемежает диспатч событий с рендерингом. Пропущенный await — не вопрос стиля: взаимодействие начинает гоняться с идущими следом проверками и становится постоянным источником act-предупреждений и флейков.

// ❌ проходит, даже когда пользователь заблокирован:
fireEvent.change(input, { target: { value: "abcdefgh" } }); // игнорирует maxLength
fireEvent.click(saveButton); // срабатывает на disabled и нефокусируемых узлах

// ✅ падает так же, как падает пользователь:
const user = userEvent.setup();
await user.type(input, "abcdefgh"); // остановится на maxLength, события на каждую клавишу
await user.click(saveButton);      // бросит исключение на pointer-events: none

Компромисс — цена и строгость. user-event медленнее — больше событий, точки await между ними — и он отказывается выполнять невозможные взаимодействия: клик по элементу с pointer-events: none бросает исключение. Эта строгость и есть смысл: когда user.click падает, пользователь тоже заблокирован. Берите fireEvent только для событий, которые пользователь не может породить напрямую (scroll, кастомное событие из не-UI источника), а не по умолчанию.

act()-предупреждения: симптом, а не цель

Предупреждение — «An update to X inside a test was not wrapped in act(…)» — не означает «сыпьте act, пока не замолчит». RTL уже оборачивает render, fireEvent и каждый вызов user-event в act. Предупреждение означает: обновление состояния произошло, когда ни один act-осведомлённый скоуп не был открыт — почти всегда это асинхронная операция, которую тест не дождался: fetch, зарезолвившийся после последней проверки, таймер, сработавший после возврата из теста, пропущенный await у user-event. Правильное лечение — дождаться видимого пользователю результата (await screen.findByText(...)) или заставить тест владеть своей незавершённой работой; обёртывание случайных строк в act() глушит пожарную сигнализацию, пока обновление всё равно приземляется в неконтролируемый момент. Команды, глобально фильтрующие act-предупреждения из console.error, встречают их снова как флейки в CI, и хуже: позднее обновление протекает в следующий тест — так рождаются падения, зависящие от порядка.

Инвентарь отказов из Hook этого урока обобщается: сьют на сплошных testid переживает рефакторинги и пропускает сломанный UX; сьют только на fireEvent остаётся зелёным, пока гниёт обработка клавиатуры и ограничений; сьют, глушащий act, конвертирует детерминированные предупреждения в вероятностные флейки. У всех трёх один корень: тест перестал походить на пользователя.