Тестирование форм
На этой странице
Формы — самый «багоопасный» UI: валидация, состояния отправки, ошибки сервера, доступность сообщений. Тест формы проверяет поведение глазами пользователя: заполнить поля по подписям (getByLabelText), отправить кнопкой или Enter, убедиться, что невалидные данные не уходят и ошибки видны рядом с полем и связаны с ним (aria-invalid, aria-describedby → toHaveAccessibleDescription), что во время отправки кнопка заблокирована (нет двойной отправки), что ошибка сервера показана и введённые данные не потеряны, и что успешная отправка приводит к ожидаемому результату (сообщение, переход, вызов колбэка с нужными данными). Тест не должен зависеть от библиотеки (React Hook Form, Formik, useActionState) — тогда смена библиотеки не ломает тесты. Серверную валидацию (Zod-схема, Server Action) дополнительно покрывают unit-тестами, а полный путь — e2e.
Вопрос
Как тестировать формы в React: валидацию, отправку, состояние загрузки и ошибки сервера?
Компонент
export function SignupForm({ onSuccess }: { onSuccess: (user: User) => void }) {
// Реализация: React Hook Form + zodResolver или useActionState — для тестов неважно
}Набор тестов
function setup() {
const user = userEvent.setup();
const onSuccess = vi.fn();
renderWithProviders(<SignupForm onSuccess={onSuccess} />);
const fields = {
email: screen.getByLabelText("Email"),
password: screen.getByLabelText("Пароль"),
submit: screen.getByRole("button", { name: "Зарегистрироваться" }),
};
return { user, onSuccess, ...fields };
}
describe("<SignupForm />", () => {
it("показывает ошибки валидации и не отправляет форму", async () => {
const { user, email, submit, onSuccess } = setup();
await user.type(email, "not-an-email");
await user.click(submit);
expect(email).toBeInvalid(); // aria-invalid="true"
expect(email).toHaveAccessibleDescription("Некорректный email"); // связано через aria-describedby
expect(screen.getByLabelText("Пароль")).toHaveAccessibleDescription("Минимум 8 символов");
expect(onSuccess).not.toHaveBeenCalled();
});
it("переводит фокус на первое поле с ошибкой", async () => {
const { user, submit, email } = setup();
await user.click(submit);
expect(email).toHaveFocus();
});
it("блокирует кнопку во время отправки и вызывает onSuccess", async () => {
const { user, email, password, submit, onSuccess } = setup();
await user.type(email, "anna@example.com");
await user.type(password, "supersecret");
await user.click(submit);
expect(submit).toBeDisabled(); // нет двойной отправки
await waitFor(() => expect(onSuccess).toHaveBeenCalledWith(expect.objectContaining({ email: "anna@example.com" })));
});
it("показывает ошибку сервера и сохраняет введённые данные", async () => {
server.use(http.post("/api/signup", () => HttpResponse.json({ code: "EMAIL_TAKEN" }, { status: 409 })));
const { user, email, password, submit } = setup();
await user.type(email, "taken@example.com");
await user.type(password, "supersecret");
await user.click(submit);
expect(await screen.findByText("Этот email уже зарегистрирован")).toBeInTheDocument();
expect(email).toHaveValue("taken@example.com"); // ввод не потерян
expect(submit).toBeEnabled(); // можно исправить и повторить
});
it("отправляется по Enter", async () => {
const { user, email, password, onSuccess } = setup();
await user.type(email, "anna@example.com");
await user.type(password, "supersecret{Enter}");
await waitFor(() => expect(onSuccess).toHaveBeenCalled());
});
});Проверка отправленных данных
Колбэк из props — самый простой способ. Если форма сама ходит в сеть, проверяй запрос через MSW:
it("отправляет нормализованный email", async () => {
let body: unknown;
server.use(http.post("/api/signup", async ({ request }) => {
body = await request.json();
return HttpResponse.json({ id: "u1", email: "anna@example.com" }, { status: 201 });
}));
const { user, email, password, submit } = setup();
await user.type(email, " Anna@Example.com ");
await user.type(password, "supersecret");
await user.click(submit);
await waitFor(() => expect(body).toEqual({ email: "anna@example.com", password: "supersecret" }));
});Формы с Server Actions
Клиентская часть формы с useActionState тестируется так же, но Server Action нужно заменить: в Vitest серверный код не выполняется через сетевую границу.
// Компонент принимает action через props (удобно для тестов и Storybook)
<ProfileForm action={updateProfile} />
it("показывает ошибки, которые вернул action", async () => {
const action = vi.fn(async () => ({ ok: false, fieldErrors: { name: "Слишком короткое имя" } }));
const user = userEvent.setup();
render(<ProfileForm action={action} />);
await user.type(screen.getByLabelText("Имя"), "А");
await user.click(screen.getByRole("button", { name: "Сохранить" }));
expect(await screen.findByText("Слишком короткое имя")).toBeInTheDocument();
});Сам Server Action (валидация, права, запись) тестируется отдельно unit/интеграционным тестом, а полный путь — e2e в Playwright.
Сложные поля
| Поле | Как тестировать |
|---|---|
Нативный <select> | user.selectOptions(combobox, "Казань") |
| Кастомный селект (Radix, React Aria) | Клик по триггеру → findByRole("option", { name }) → клик |
| Дата | Ввести текст в поле или выбрать день в календаре по роли gridcell/button |
| Маска телефона | user.type(input, "9991234567") → toHaveValue("+7 (999) 123-45-67") |
| Загрузка файла | user.upload(input, file) + проверка превью/имени |
| Чекбокс согласия | user.click(getByRole("checkbox", { name: /согласен/ })) |
| Динамический список полей | «Добавить телефон» → новое поле с подписью «Телефон 2» |
Чек-лист тестов формы
- Валидные данные → успешный результат (колбэк/запрос/навигация).
- Каждое правило валидации: сообщение у поля,
aria-invalid, связь с описанием. - Фокус на первом поле с ошибкой.
- Кнопка заблокирована во время отправки.
- Ошибка сервера: сообщение, данные не потеряны, повтор возможен.
- Отправка с клавиатуры (Enter).
- Граничные значения (тест-дизайн).
Что важно помнить
- Находи поля по подписям — заодно проверяешь доступность формы.
- Проверяй и ошибки валидации, и ошибки сервера, и состояние отправки.
- Тесты не должны зависеть от библиотеки форм.
- Отправленные данные — через колбэк или MSW.
- Server Action — отдельно; полный путь — e2e.
Мини-шпаргалка
getByLabelText→user.type→user.click(submit).toBeInvalid(),toHaveAccessibleDescription(),toHaveFocus().toBeDisabled()во время отправки.server.use(http.post(..., 409))для ошибки сервера.