Быстрый старт с Vitest: установка, vitest.config.ts и запуск в Watch-режиме

Архитектурная база#

На протяжении долгого времени де-факто стандартом тестирования в экосистеме JavaScript оставался Jest. Однако фундаментальная архитектура Jest сформировалась в эпоху CommonJS и синхронных загрузчиков модулей require(). В современных веб-приложениях с нативными ECMAScript Modules (ESM), компиляторами TypeScript, JSX и бандлерами нового поколения Jest требует громоздкой надстройки: тяжелых плагинов трансформации (ts-jest, @swc/jest, babel-jest), сложной настройки регулярных выражений transformIgnorePatterns и ручного мокирования асинхронного импорта ESM-пакетов.

Vitest спроектирован с чистого листа для устранения этого разрыва. Vitest не изобретает собственный компилятор, а использует единый пайплайн трансформации Vite. Это означает, что конфигурация алиасов путей (@/*), обработка CSS-модулей, JSX-синтаксиса React 19 и переменных окружения работают в тестах абсолютно идентично тому, как они работают в основном приложении.

Ключевые архитектурные преимущества Vitest:

1. Нативная поддержка ESM: прямое выполнение современных пакетов без предварительной транспиляции в CommonJS.
2. Многопоточный пул воркеров (Tinypool): тесты распределяются по потокам worker_threads Node.js, обеспечивая полную изоляцию контекстов памяти и линейное ускорение на многоядерных процессорах.
3. Единый конфигурационный файл: отсутствие рассинхронизации настроек сборки приложения и настроек тестового раннера.
4. Умный Watch-режим с графом модулей: Vitest анализирует граф импортов Vite и при изменении исходного файла перезапускает исключительно те тесты, которые прямо или косвенно зависят от измененного модуля.

Ментальная модель#

Взаимодействие компонентов в процессе запуска тестов Vitest можно представить как конвейер, связывающий файловую систему, граф зависимостей и изолированные потоки выполнения:

[Файловая система: *.ts / *.tsx]
                │
                ▼
   [Vite Transformation Pipeline]  <- Обработка TypeScript, JSX, alias '@/*'
                │
                ▼
      [Модульный граф Vite]         <- Определение затронутых тестов в Watch-режиме
                │
                ▼
     [Tinypool Worker Pool]         <- Параллельное распределение задач
      ┌───────────┬───────────┐
      ▼           ▼           ▼
  [Worker 1]  [Worker 2]  [Worker 3]   <- Изолированные контексты рантайма:
    (node)    (happy-dom) (happy-dom)     'node' (быстрый) или 'happy-dom' (DOM API)
      │           │           │
      └───────────┼───────────┘
                  ▼
         [Консольный репортер]        <- Мгновенный вывод Pass/Fail и интерактивный CLI

Тестовый раннер изолирует каждый тестовый файл в отдельном контексте памяти. Глобальные переменные или состояние, мутированное в user.test.ts, гарантированно не попадут в cart.test.ts.

На практике применяется#

1. Мгновенный TDD-цикл (Test-Driven Development): Разработка фичи в фоне с запущенным pnpm vitest: время обратной связи между сохранением файла в VS Code и получением вердикта теста составляет менее 50 миллисекунд.
2. Тестирование серверных утилит и API-маршрутов в Next.js: Быстрый прогон валидаторов схем Zod, утилит форматирования данных и бизнес-логики без запуска тяжелого локального Next.js dev-сервера.
3. Оптимизация CI-пайплайнов с генерацией отчетов покрытия (v8 Coverage): Сбор информации о покрытии строк, веток и функций на базе нативного профилировщика движка V8 без замедления инструментов инструментации типа Istanbul.
4. Унификация окружений монорепозитория: Использование единого конфига vitest.workspace.ts для запуска тестов в десятках пакетов монорепозитория с разделением бэкенд-пакетов (environment: 'node') и фронтенд-библиотек (environment: 'happy-dom').

Как это работает#

1. Установка и настройка vitest.config.ts#

Установим Vitest и окружение happy-dom в проект с помощью pnpm:

pnpm add -D vitest happy-dom @types/node

Создадим конфигурационный файл vitest.config.ts в корне проекта:

import { defineConfig } from 'vitest/config';
import path from 'node:path';

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src'),
    },
  },
  test: {
    // Включение глобальных переменных (describe, it, expect) без явного импорта
    // Для строгой типизации рекомендуется оставить globals: false
    globals: false,

    // Окружение по умолчанию: 'node' (для чистого TS) или 'happy-dom' (для DOM)
    environment: 'node',

    // Маски поиска тестовых файлов
    include: ['src/**/*.{test,spec}.{ts,tsx}'],

    // Исключаемые директории
    exclude: ['node_modules', 'dist', '.next'],

    // Конфигурация генератора покрытия кода
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: [
        'node_modules/',
        'src/**/*.d.ts',
        'src/**/index.ts',
      ],
    },
  },
});

2. Сравнение окружений: node vs jsdom vs happy-dom#

Выбор окружения выполнения (environment) напрямую влияет на скорость выполнения тестов и потребление оперативной памяти.

[!TIP] Вы можете переопределять окружение точечно для каждого файла с помощью директивы в самом верху файла:

typescript

Copy code

// @vitest-environment happy-dom

Это позволяет держать глобальным быстрое окружение node, а happy-dom подключать только там, где реально тестируются React-компоненты.

3. Написание первого теста#

Создадим простой служебный модуль форматирования чисел и денежных значений:

export interface FormatCurrencyOptions {
  readonly locale?: string;
  readonly currency?: string;
}

export function formatCurrency(
  amountInCents: number,
  options: FormatCurrencyOptions = {}
): string {
  if (!Number.isFinite(amountInCents)) {
    throw new TypeError('Сумма должна быть конечным числом');
  }

  const { locale = 'ru-RU', currency = 'RUB' } = options;
  const majorUnits = amountInCents / 100;

  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency,
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  }).format(majorUnits);
}

Теперь создадим файл спецификации src/utils/formatCurrency.test.ts:

import { describe, it, expect } from 'vitest';
import { formatCurrency } from './formatCurrency';

describe('formatCurrency', () => {
  it('корректно конвертирует копейки в рубли с правильным символом валюты', () => {
    // 150 000 копеек = 1 500,00 ₽
    const formatted = formatCurrency(150000, { locale: 'ru-RU', currency: 'RUB' });
    
    // Заменяем неразрывные пробелы \u00A0 на обычные для надежного сравнения
    const normalized = formatted.replace(/\u00A0/g, ' ');
    expect(normalized).toBe('1 500,00 ₽');
  });

  it('форматирует доллары США с дефолтной локалью', () => {
    const formatted = formatCurrency(4999, { locale: 'en-US', currency: 'USD' });
    expect(formatted).toBe('$49.99');
  });

  it('выбрасывает TypeError при передаче NaN или Infinity', () => {
    expect(() => formatCurrency(Number.NaN)).toThrow(TypeError);
    expect(() => formatCurrency(Number.POSITIVE_INFINITY)).toThrow(
      'Сумма должна быть конечным числом'
    );
  });
});

4. Архитектурный конвейер исполнения тестов и интерактивный Watch-режим#

Запуск тестов в консоли:

# Интерактивный watch-режим для локальной разработки
pnpm vitest

# Разовый прогон для CI/CD с кодом завершения процесса
pnpm vitest run

# Прогон с генерацией таблицы покрытия кода
pnpm vitest run --coverage

В интерактивном Watch-режиме доступны горячие клавиши:

• p — фильтрация по имени файла (File Name Pattern): введите часть пути или имени файла, чтобы запускать только его;
• t — фильтрация по названию теста (Test Name Pattern): запускает только тесты, чье имя внутри it(...) совпадает с шаблоном;
• f — запуск только упавших (Failed) тестов;
• u — обновление снапшотов (Update Snapshots);
• q — выход из Watch-режима.

Распространённые ошибки#

// ❌ package.json: зависание в CI
{
  "scripts": {
    "test:ci": "vitest"
  }
}

// ✅ package.json: корректный однократный прогон
{
  "scripts": {
    "test": "vitest",
    "test:ci": "vitest run"
  }
}

// ❌ Медленно: jsdom глобально для всех 500 тестов бэкенда и утилит
export default defineConfig({
  test: {
    environment: 'jsdom',
  },
});

// ✅ Быстро: глобальный 'node' и точечный 'happy-dom' через директиву в UI-файлах
// В файле Button.test.tsx:
// @vitest-environment happy-dom

// ✅ Обязательно синхронизируйте alias в vitest.config.ts
resolve: {
  alias: {
    '@': path.resolve(__dirname, './src'),
  },
}

// ❌ Опасно: пропустит все остальные тесты в CI
it.only('проверяет форматирование валюты', () => { ... });

// ✅ Безопасно: используйте флаг --no-focused-tests в CI или линтер eslint-plugin-vitest
// Vitest в CI можно запускать с флагом: vitest run --allowOnly=false

Вопросы для собеседования#

Связанные темы#