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

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-domBrowser 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().

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

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

Поиск

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