Vitest Browser Mode: компоненты в настоящем браузере
На этой странице
Vitest Browser Mode запускает тесты компонентов не в эмуляции DOM (jsdom), а в настоящем браузере — Chromium, Firefox или WebKit через провайдер Playwright. Это убирает целый класс проблем jsdom: работают реальные layout и CSS (размеры, видимость, overflow, медиазапросы), IntersectionObserver, ResizeObserver, matchMedia, скролл, фокус, <dialog>, Popover API, Canvas, Web Workers, а события генерируются браузером (через CDP/WebDriver), а не синтетически. Тесты пишутся почти так же: render из vitest-browser-react, локаторы page.getByRole(...) и асинхронные утверждения await expect.element(locator).toBeVisible(), которые сами повторяют проверку до успеха (как в Playwright) — без findBy и waitFor. Режим стабилен с Vitest 4 и подходит для дизайн-систем и сложных интерактивных компонентов; цена — медленнее jsdom и нужен установленный браузер в CI. Частая схема: логика — в node, компоненты — в браузере, через projects.
Вопрос
Что такое Vitest Browser Mode, чем он лучше jsdom и как писать в нём тесты компонентов?
jsdom и настоящий браузер
| jsdom / happy-dom | Browser Mode | |
|---|---|---|
| Layout, размеры | Нет (getBoundingClientRect = 0) | Да |
CSS: видимость, display, медиазапросы | Частично | Полностью |
| Observer API, matchMedia | Мокать вручную | Есть |
| События | Синтетические | Настоящие события браузера |
| Скорость | Быстрее | Медленнее (но параллельно) |
| Отладка | Консоль | Видно браузер, DevTools, скриншоты при падении |
| CI | Ничего не нужно | Установка браузера (playwright install) |
Установка и конфиг
pnpm add -D vitest @vitest/browser-playwright vitest-browser-react playwright
pnpm exec playwright install chromium// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import { playwright } from "@vitest/browser-playwright";
export default defineConfig({
plugins: [react()],
test: {
projects: [
{
extends: true,
test: { name: "unit", environment: "node", include: ["src/**/*.test.ts"] },
},
{
extends: true,
test: {
name: "browser",
include: ["src/**/*.browser.test.tsx"],
browser: {
enabled: true,
provider: playwright(),
headless: true,
instances: [{ browser: "chromium" }], // можно добавить firefox, webkit
},
},
},
],
},
});Тест
// src/shared/ui/dialog/dialog.browser.test.tsx
import { render } from "vitest-browser-react";
import { expect, it } from "vitest";
import { page, userEvent } from "vitest/browser";
import { ConfirmDialog } from "./confirm-dialog";
it("открывается, ловит фокус и закрывается по Escape", async () => {
const screen = await render(<ConfirmDialog title="Удалить заказ?" trigger="Удалить" />);
await screen.getByRole("button", { name: "Удалить" }).click();
const dialog = screen.getByRole("dialog", { name: "Удалить заказ?" });
await expect.element(dialog).toBeVisible(); // повторяет до успеха
await expect.element(screen.getByRole("button", { name: "Отмена" })).toHaveFocus();
await userEvent.keyboard("{Escape}");
await expect.element(dialog).not.toBeInTheDocument();
});Отличия от RTL: render возвращает локаторы (в актуальных версиях его нужно await), действия вызываются у локатора (.click(), .fill()), а expect.element ждёт сам — findBy/waitFor не нужны.
Что особенно хорошо тестировать в браузере
it("показывает кнопку «Ещё» только если текст не помещается", async () => {
const screen = await render(
<div style={{ width: 200 }}>
<Truncated text={"Очень длинное описание товара ".repeat(10)} lines={2} />
</div>,
);
await expect.element(screen.getByRole("button", { name: "Ещё" })).toBeVisible(); // нужен реальный layout
});
it("адаптивное меню: на узком экране — бургер", async () => {
await page.viewport(375, 800); // page импортирован из "vitest/browser"
const screen = await render(<Header />);
await expect.element(screen.getByRole("button", { name: "Открыть меню" })).toBeVisible();
});- Тултипы и поповеры с позиционированием (Floating UI).
- Виртуализированные списки (нужны размеры).
- Lazy-загрузка по IntersectionObserver.
- Drag-and-drop, скролл, фокус-ловушки.
- Компоненты дизайн-системы во всех браузерах (Firefox, WebKit).
Скриншоты и визуальные проверки
import { page } from "vitest/browser";
const path = await page.screenshot(); // скриншот при отладке
await expect.element(screen.getByRole("button")).toMatchScreenshot(); // визуальное сравнение (Vitest 4)При падении теста Vitest сохраняет скриншот автоматически.
Моки и сеть
vi.fn, vi.spyOn и vi.mock работают в браузере. Для сети используют MSW в режиме Service Worker (setupWorker из msw/browser) — те же хэндлеры, что и в node-тестах.
Когда выбирать
| Выбирай Browser Mode | Оставайся на jsdom |
|---|---|
| Дизайн-система и UI-кит | Бизнес-экраны с простой разметкой |
| Зависимость от layout, CSS, Observer API | Тысячи быстрых тестов, где скорость критична |
| Кроссбраузерность важна | CI без браузеров |
| Много моков браузерных API в jsdom-тестах | Логика без DOM (там вообще node) |
Browser Mode — это всё ещё тесты компонента в изоляции (без бэкенда и роутинга приложения). Полные пользовательские сценарии — в Playwright e2e.
Что важно помнить
- Browser Mode = тесты компонентов в настоящем браузере через Playwright.
- Реальные layout, CSS, события и Web API без моков.
renderизvitest-browser-react, локаторы иawait expect.element(...).- Удобно сочетать с node-проектом через
projects. - Медленнее jsdom; полные сценарии — всё равно e2e.
Мини-шпаргалка
browser: { enabled: true, provider: playwright(), instances: [{ browser: "chromium" }] }.const screen = await render(<C />).await screen.getByRole(...).click().await expect.element(locator).toBeVisible().page.viewport(w, h),toMatchScreenshot().