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

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 node

Projects: несколько конфигураций

// 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       # шардирование в CI
it.only("...", ...);         // временно запустить только этот тест (не коммитить!)
it.skip("...", ...);
it.todo("обработать 429");   // напоминание
it.concurrent("...", ...);   // параллельно внутри файла

Vitest и Jest

VitestJest
Конфиг и трансформацииИз Vite: TS, JSX, алиасы, CSS без настройкиBabel/ts-jest, moduleNameMapper
ESMНативноИсторически сложно
Скорость и watchБыстрее, граф модулей ViteМедленнее на больших проектах
APIСовместим: vi.fn, vi.mock, vi.spyOnjest.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.

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

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

Поиск

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