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-событияfireEvent | user-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 }).