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

user-event: взаимодействие как у пользователя

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

@testing-library/user-event имитирует действия пользователя полной последовательностью событий, как в браузере: клик — это pointerdown → mousedown → focus → pointerup → mouseup → click, ввод — keydown → beforeinput → input → keyup для каждого символа, с учётом disabled, pointer-events: none, maxLength и фокуса. Поэтому он находит баги, которые пропускает низкоуровневый fireEvent (он отправляет одно событие: например, fireEvent.click по элементу, перекрытому pointer-events: none, сработает, а у пользователя — нет; fireEvent.change меняет значение без фокуса и нажатий клавиш). Правила v14: создавай экземпляр const user = userEvent.setup() в начале теста (до render), все методы асинхронные — их нужно await. Основные методы: click, dblClick, type, clear, keyboard (сочетания клавиш, {Enter}, {Shift>}), tab, hover/unhover, selectOptions, upload, paste, pointer. fireEvent остаётся для событий, которые user-event не умеет (scroll, resize, кастомные события).

Вопрос

Чем user-event отличается от fireEvent и как с его помощью тестировать клики, ввод текста, клавиатуру и загрузку файлов?

Основы

import userEvent from "@testing-library/user-event";
 
it("добавляет задачу по Enter", async () => {
  const user = userEvent.setup();          // до render
  render(<TodoApp />);
 
  await user.type(screen.getByRole("textbox", { name: "Новая задача" }), "Купить молоко{Enter}");
 
  expect(screen.getByRole("listitem")).toHaveTextContent("Купить молоко");
  expect(screen.getByRole("textbox", { name: "Новая задача" })).toHaveValue("");
});

Удобный хелпер — setup-функция, которая возвращает и user, и результат рендера:

function setup(ui: React.ReactElement) {
  return { user: userEvent.setup(), ...render(ui) };
}
 
const { user } = setup(<TodoApp />);

fireEvent и user-event

render(<button style={{ pointerEvents: "none" }} onClick={onClick}>Купить</button>);
 
fireEvent.click(screen.getByRole("button"));   // onClick вызовется — пользователь так кликнуть не может
await user.click(screen.getByRole("button"));  // user-event бросит ошибку: элемент недоступен для указателя
 
// Ввод
fireEvent.change(input, { target: { value: "abc" } }); // одно событие change, без фокуса и клавиш
await user.type(input, "abc");                         // фокус + 3 нажатия + input-события
fireEventuser-event
СобытияОдно, которое указалиПолная последовательность, как в браузере
ФокусНе меняетсяМеняется, срабатывают focus/blur
ПроверкиНетdisabled, pointer-events, видимость для указателя
АсинхронностьСинхронныйawait
КогдаScroll, resize, кастомные событияВсё пользовательское

Методы

await user.click(el);
await user.dblClick(el);
await user.tripleClick(input);                       // выделить текст
await user.hover(el);                                // тултипы, меню
await user.unhover(el);
 
await user.type(input, "hello");
await user.clear(input);
await user.type(input, "{Backspace}{Backspace}");
await user.paste("скопированный текст");             // в элемент с фокусом
 
await user.keyboard("{Enter}");
await user.keyboard("{Escape}");
await user.keyboard("{Control>}a{/Control}");        // Ctrl+A: > — зажать, {/…} — отпустить
await user.keyboard("{Shift>}{Tab}{/Shift}");
await user.keyboard("[ArrowDown][ArrowDown][Enter]"); // [] — по коду клавиши
 
await user.tab();                                    // следующий фокусируемый
await user.tab({ shift: true });
 
await user.selectOptions(screen.getByRole("combobox", { name: "Город" }), "Казань");
await user.deselectOptions(select, "Казань");
 
const file = new File(["(image)"], "avatar.png", { type: "image/png" });
await user.upload(screen.getByLabelText("Аватар"), file);
expect(screen.getByLabelText("Аватар").files?.[0]).toBe(file);

Тестирование клавиатурной доступности

it("меню управляется с клавиатуры", async () => {
  const user = userEvent.setup();
  render(<ActionsMenu />);
 
  await user.tab();
  expect(screen.getByRole("button", { name: "Действия" })).toHaveFocus();
 
  await user.keyboard("{Enter}");
  expect(screen.getByRole("menu")).toBeVisible();
  expect(screen.getByRole("menuitem", { name: "Редактировать" })).toHaveFocus();
 
  await user.keyboard("{ArrowDown}");
  expect(screen.getByRole("menuitem", { name: "Удалить" })).toHaveFocus();
 
  await user.keyboard("{Escape}");
  expect(screen.queryByRole("menu")).not.toBeInTheDocument();
  expect(screen.getByRole("button", { name: "Действия" })).toHaveFocus();   // фокус вернулся
});

Такой тест проверяет то, что важно пользователям клавиатуры и скринридеров, и ловит регрессии доступности.

Опции setup

userEvent.setup({
  advanceTimers: vi.advanceTimersByTime,   // с фейковыми таймерами
  delay: null,                             // без задержки между символами (по умолчанию 0)
  pointerEventsCheck: 0,                   // отключить проверку pointer-events (если jsdom ошибается)
});

Частые ошибки

ОшибкаРешение
Забыт await перед user.clickВсе методы асинхронные
userEvent.click(...) без setup()Создавать user = userEvent.setup() в каждом тесте
setup() после render в beforeEach с общим userСоздавать в тесте или setup-функции
fireEvent.change для обычного вводаuser.type
act(...) вокруг user-вызововНе нужно: RTL уже оборачивает
Фейковые таймеры без advanceTimersТаймаут теста

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

  • user-event повторяет реальную последовательность событий и проверяет доступность для указателя.
  • const user = userEvent.setup() в начале теста, все вызовы — с await.
  • keyboard и tab — для тестов клавиатурной навигации.
  • fireEvent — только для событий, которых нет в user-event.

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

  • click, type, clear, keyboard, tab, hover, selectOptions, upload, paste.
  • {Enter}, {Escape}, {Control>}a{/Control}, [ArrowDown].
  • userEvent.setup({ advanceTimers }).

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

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

Поиск

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