Vitest: установка, конфигурация и окружения
На этой странице
Vitest — стандартный тест-раннер для современного фронтенда: использует конфигурацию и плагины Vite (те же алиасы, JSX, TypeScript, CSS), нативно поддерживает ESM и TypeScript без отдельной настройки Babel, совместим с API Jest (describe, it, expect, vi вместо jest), очень быстрый благодаря параллельным воркерам и умному watch-режиму (перезапускает только тесты, затронутые изменением). Ключевые настройки: environment — где выполняются тесты (node для чистой логики и серверного кода, jsdom или happy-dom — эмуляция DOM для компонентов), Browser Mode — запуск в настоящем браузере через Playwright (стабилен с Vitest 4), setupFiles (подключение @testing-library/jest-dom, MSW, очистка), projects — несколько конфигураций в одном запуске (unit в node + компоненты в браузере), coverage через V8. Jest по-прежнему встречается в legacy-проектах; миграция на Vitest обычно сводится к замене jest. на vi. и конфига.
Вопрос
Что такое Vitest, чем он отличается от Jest и как настроить его для React/Next.js-проекта?
Установка
pnpm add -D vitest @vitejs/plugin-react jsdom @testing-library/react @testing-library/dom @testing-library/user-event @testing-library/jest-dom vite-tsconfig-paths// vitest.config.ts
import { defineConfig } from "vitest/config";
import react from "@vitejs/plugin-react";
import tsconfigPaths from "vite-tsconfig-paths";
export default defineConfig({
plugins: [react(), tsconfigPaths()], // алиасы @/… из tsconfig
test: {
environment: "jsdom",
setupFiles: ["./vitest.setup.ts"],
globals: false, // явные импорты describe/it/expect — понятнее
css: false, // не обрабатывать CSS, если стили не важны для тестов
restoreMocks: true, // восстанавливать spyOn после каждого теста
unstubEnvs: true,
unstubGlobals: true,
},
});// vitest.setup.ts
import "@testing-library/jest-dom/vitest"; // toBeInTheDocument, toBeDisabled, toHaveValue…
import { cleanup } from "@testing-library/react";
import { afterEach } from "vitest";
afterEach(() => cleanup()); // при globals: false RTL не чистит DOM автоматически// package.json
{
"scripts": {
"test": "vitest",
"test:run": "vitest run",
"test:coverage": "vitest run --coverage"
}
}Первый тест
// src/shared/lib/format-price.test.ts
import { describe, it, expect } from "vitest";
import { formatPrice } from "./format-price";
describe("formatPrice", () => {
it("форматирует рубли с пробелом между разрядами", () => {
expect(formatPrice(1234567)).toBe("1 234 567 ₽");
});
});Тесты кладут рядом с кодом (format-price.ts + format-price.test.ts) — так видно, что покрыто, и тест переезжает вместе с модулем.
Окружения
| Окружение | Что это | Когда |
|---|---|---|
node | Без DOM | Утилиты, сервисы, серверный код, Server Actions |
jsdom | Эмуляция DOM на JS (самая полная) | Компоненты, по умолчанию для RTL |
happy-dom | Более быстрая и лёгкая эмуляция | Компоненты, если хватает совместимости |
| Browser Mode | Настоящий Chromium/Firefox/WebKit через Playwright | Компоненты, где важны реальные layout, CSS, события, Web API |
Ограничения jsdom: нет layout (getBoundingClientRect возвращает нули), нет IntersectionObserver, ResizeObserver, matchMedia, реального скролла, CSS-анимаций — их приходится мокать. Browser Mode снимает эти ограничения ценой скорости.
Окружение можно переопределить для отдельного файла:
// @vitest-environment nodeProjects: несколько конфигураций
// vitest.config.ts
export default defineConfig({
plugins: [react(), tsconfigPaths()],
test: {
projects: [
{
extends: true,
test: { name: "unit", environment: "node", include: ["src/**/*.test.ts"] },
},
{
extends: true,
test: { name: "dom", environment: "jsdom", include: ["src/**/*.test.tsx"], setupFiles: ["./vitest.setup.ts"] },
},
],
},
});vitest --project unit # только unitВ монорепо каждый пакет может иметь свой конфиг, а корневой — перечислять их в projects.
Полезные команды
vitest # watch-режим: перезапуск затронутых тестов
vitest run # однократный прогон (CI)
vitest run src/cart # фильтр по пути
vitest -t "промокод" # фильтр по имени теста
vitest --ui # веб-интерфейс (@vitest/ui)
vitest run --changed # только тесты, связанные с изменёнными файлами
vitest run --shard=1/4 # шардирование в CIit.only("...", ...); // временно запустить только этот тест (не коммитить!)
it.skip("...", ...);
it.todo("обработать 429"); // напоминание
it.concurrent("...", ...); // параллельно внутри файлаVitest и Jest
| Vitest | Jest | |
|---|---|---|
| Конфиг и трансформации | Из Vite: TS, JSX, алиасы, CSS без настройки | Babel/ts-jest, moduleNameMapper |
| ESM | Нативно | Исторически сложно |
| Скорость и watch | Быстрее, граф модулей Vite | Медленнее на больших проектах |
| API | Совместим: vi.fn, vi.mock, vi.spyOn | jest.fn, jest.mock |
| Браузер | Browser Mode | Только jsdom |
| Где встретишь | Новые проекты, Vite, Next.js (официальный гайд) | Legacy, React Native |
Next.js
Для Next.js используется тот же конфиг с @vitejs/plugin-react. Синхронные Server и Client Components, хуки и утилиты тестируются в Vitest; асинхронные Server Components Vitest пока не рендерит — их проверяют e2e-тестами (см. тему про Next.js в этом разделе).
Что важно помнить
- Vitest = конфиг Vite + API, совместимый с Jest + скорость.
- Окружение:
nodeдля логики,jsdom/happy-domдля компонентов, Browser Mode для реального браузера. setupFiles: jest-dom-матчеры, cleanup, MSW.projectsобъединяют разные конфигурации.- Тесты рядом с кодом;
vitest runв CI.
Мини-шпаргалка
defineConfig({ test: { environment, setupFiles, projects } }).import "@testing-library/jest-dom/vitest".vitest/vitest run/--coverage/-t/--changed/--shard.// @vitest-environment node.