Jest: конфигурация и плагины

Jest настраивается через jest.config.js (или поле jest в package.json) и расширяется плагинами — трансформерами, репортерами и кастомными матчерами.

Зачем нужно

Дефолтная конфигурация Jest подходит для простых JS-проектов, но реальные проекты требуют настройки: поддержка TypeScript, ES-модулей, CSS-модулей, path aliases, кастомных окружений. Правильная конфигурация устраняет ошибки трансформации и ускоряет запуск тестов.

Где используется

  • TypeScript-проекты (нужен ts-jest или babel-jest с @babel/preset-typescript)
  • React/Next.js приложения (jsdom-окружение, трансформация JSX)
  • Monorepo: разные конфиги для разных пакетов
  • CI: параллельный запуск, кастомные репортеры для вывода результатов

Основной контент

Базовая структура jest.config.js

// jest.config.js
/** @type {import('jest').Config} */
module.exports = {
  // Окружение исполнения
  testEnvironment: 'node',      // или 'jsdom' для браузерного кода

  // Паттерн поиска тест-файлов
  testMatch: ['**/__tests__/**/*.js', '**/*.test.js', '**/*.spec.js'],

  // Трансформация файлов
  transform: {
    '^.+\\.(js|jsx)$': 'babel-jest',
    '^.+\\.(ts|tsx)$': 'ts-jest',
  },

  // Алиасы путей (синхронизируй с tsconfig.paths)
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '\\.css$': '<rootDir>/__mocks__/styleMock.js',
    '\\.svg$': '<rootDir>/__mocks__/svgMock.js',
  },

  // Файл с глобальными setup
  setupFilesAfterFramework: ['<rootDir>/jest.setup.js'],

  // Coverage
  collectCoverageFrom: ['src/**/*.{js,ts,jsx,tsx}', '!src/**/*.d.ts'],
};

jest.setup.js — глобальные настройки

// jest.setup.js
import '@testing-library/jest-dom'; // кастомные матчеры для DOM

TypeScript через ts-jest

npm install --save-dev ts-jest @types/jest

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  globals: {
    'ts-jest': {
      tsconfig: './tsconfig.test.json()',
    },
  },
};

Полезные плагины и пресеты

Пакет Назначение
ts-jest TypeScript трансформация
babel-jest Babel трансформация (включён по умолчанию)
jest-environment-jsdom Браузерное окружение
@testing-library/jest-dom DOM-матчеры (toBeInTheDocument и др.)
jest-extended Дополнительные матчеры
jest-circus Улучшенный test runner (default с Jest 27)

Параллельный запуск

module.exports = {
  maxWorkers: '50%', // использовать половину ядер CPU
  // или
  maxWorkers: 4,
};

Репортеры

module.exports = {
  reporters: [
    'default',
    ['jest-junit', { outputDirectory: 'reports', outputName: 'junit.xml' }],
  ],
};

Частые ошибки

  • Конфликт testEnvironment — для Node.js кода использование jsdom добавляет лишние зависимости и замедляет тесты; явно указывай нужное окружение
  • Забыл добавить setupFilesAfterFramework — матчеры из @testing-library/jest-dom не подключены, тесты падают с "toBe... is not a function"
  • Path aliases без moduleNameMapper — Jest не знает про алиасы TypeScript, тесты падают с "Cannot find module '@/components/...'"
  • Трансформация node_modules — по умолчанию Jest не трансформирует node_modules; для ESM-only пакетов нужен transformIgnorePatterns

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

Ресурсы