ts-jest для TypeScript: полное руководство с примерами

Что такое ts-jest и зачем она нужна?

ts-jest — это TypeScript-препроцессор для популярного фреймворка тестирования Jest. Он позволяет запускать тесты, написанные на TypeScript, без необходимости предварительной компиляции в JavaScript. Библиотека автоматически преобразует TypeScript-код в JavaScript во время выполнения тестов, используя встроенный компилятор TypeScript.

Основная цель ts-jest — обеспечить бесшовную интеграцию TypeScript с Jest. Без неё пришлось бы вручную настраивать компиляцию TypeScript перед каждым запуском тестов или использовать дополнительные инструменты вроде ts-node. ts-jest делает этот процесс прозрачным и автоматическим.

Ключевые преимущества использования ts-jest:

• Автоматическая компиляция — TypeScript-файлы компилируются "на лету" во время тестирования
• Полная поддержка TypeScript — все фичи языка (декораторы, дженерики, типы) работают корректно
• Source maps — при ошибках вы видите исходный TypeScript-код, а не скомпилированный JavaScript
• Производительность — ts-jest кэширует результаты компиляции, что ускоряет повторные запуски
• Гибкость — можно настраивать параметры компилятора TypeScript через конфигурацию Jest

Установка ts-jest

Для работы с ts-jest вам потребуется Node.js (версия 14 или выше) и менеджер пакетов npm или yarn. Установка выполняется одной командой:

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

Или через yarn:

yarn add --dev jest typescript ts-jest @types/jest

Пояснение пакетов:

• jest — сам фреймворк тестирования
• typescript — компилятор TypeScript
• ts-jest — препроцессор для интеграции
• @types/jest — типы TypeScript для Jest (для автодополнения и проверки типов)

После установки необходимо создать или обновить файл jest.config.js (или jest.config.ts):

// jest.config.js
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/__tests__/**/*.ts?(x)', '**/?(*.)+(spec|test).ts?(x)'],
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node']
};

Также убедитесь, что в tsconfig.json настроены правильные параметры:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "**/*.test.ts"]
}

Быстрый старт с примером кода

Создадим простую функцию и тест для неё. Структура проекта:

my-project/
├── src/
│   ├── math.ts
│   └── __tests__/
│       └── math.test.ts
├── jest.config.js
├── tsconfig.json
└── package.json

Файл: src/math.ts

export function add(a: number, b: number): number {
  return a + b;
}

export function subtract(a: number, b: number): number {
  return a - b;
}

export function multiply(a: number, b: number): number {
  return a * b;
}

export function divide(a: number, b: number): number {
  if (b === 0) {
    throw new Error('Division by zero');
  }
  return a / b;
}

Файл: src/__tests__/math.test.ts

import { add, subtract, multiply, divide } from '../math';

describe('Math functions', () => {
  test('adds 1 + 2 to equal 3', () => {
    expect(add(1, 2)).toBe(3);
  });

  test('subtracts 5 - 3 to equal 2', () => {
    expect(subtract(5, 3)).toBe(2);
  });

  test('multiplies 4 * 3 to equal 12', () => {
    expect(multiply(4, 3)).toBe(12);
  });

  test('divides 10 / 2 to equal 5', () => {
    expect(divide(10, 2)).toBe(5);
  });

  test('throws error when dividing by zero', () => {
    expect(() => divide(10, 0)).toThrow('Division by zero');
  });
});

Запуск тестов:

npx jest

Вы должны увидеть зелёный отчёт о прохождении всех тестов. Обратите внимание, что ts-jest автоматически скомпилировал TypeScript-файлы перед выполнением тестов.

Основные методы и функции ts-jest

ts-jest предоставляет несколько ключевых методов и конфигурационных опций. Рассмотрим их подробно.

1. createTransformer

Описание: Создаёт кастомный трансформер для обработки TypeScript-файлов. Используется для тонкой настройки процесса компиляции.

Параметры:

• tsconfig (string | object) — путь к tsconfig.json или объект с настройками компилятора
• options (object) — дополнительные опции трансформера

Пример:

const { createTransformer } = require('ts-jest');
const transformer = createTransformer({
  tsconfig: './tsconfig.test.json',
  diagnostics: true
});

module.exports = {
  transform: {
    '^.+\\.tsx?$': transformer
  }
};

2. pathsToModuleNameMapper

Описание: Утилита для преобразования алиасов путей из tsconfig.json в формат, понятный Jest. Решает проблему с модульными алиасами (например, @/components).

Параметры:

• paths (object) — объект с путями из tsconfig.json
• prefix (string, optional) — префикс для путей (по умолчанию '<rootDir>')

Пример:

const { pathsToModuleNameMapper } = require('ts-jest');
const { compilerOptions } = require('./tsconfig.json');

module.exports = {
  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths, { prefix: '<rootDir>/' })
};

3. mocked

Описание: TypeScript-утилита для правильной типизации моков. Помогает избежать ошибок типов при работе с jest.mock().

Параметры:

• item (T) — объект или функция, которую нужно замокать
• deep (boolean, optional) — если true, рекурсивно мокает вложенные свойства

Пример:

import { mocked } from 'ts-jest/utils';
import { fetchData } from './api';

jest.mock('./api');

const mockedFetchData = mocked(fetchData);

test('fetchData returns mocked value', () => {
  mockedFetchData.mockResolvedValue({ id: 1, name: 'Test' });
  // Теперь fetchData возвращает замоканное значение
});

4. jest.createMockFromModule

Описание: Создаёт автоматический мок для модуля на основе его TypeScript-типов. ts-jest расширяет эту функцию для корректной работы с типами.

Параметры:

• moduleName (string) — имя модуля для мока

Пример:

import { createMockFromModule } from 'ts-jest/utils';

const mockDb = createMockFromModule('./database');
// mockDb теперь имеет все методы из database, но все они — jest.fn()

5. configure

Описание: Метод для программной настройки ts-jest. Позволяет изменить конфигурацию во время выполнения тестов.

Параметры:

• config (object) — объект с настройками ts-jest

Пример:

const tsJest = require('ts-jest');

tsJest.configure({
  tsconfig: {
    target: 'ES2019',
    module: 'commonjs'
  },
  diagnostics: {
    warnOnly: true
  }
});

6. getCacheKey

Описание: Возвращает ключ кэша для файла. Используется для оптимизации — если файл не изменился, ts-jest использует кэшированную версию.

Параметры:

• fileData (string) — содержимое файла
• filePath (string) — путь к файлу
• configStr (string) — строка конфигурации
• options (object) — дополнительные опции

Пример: (обычно не вызывается напрямую, но можно переопределить)

const { getCacheKey } = require('ts-jest');

const customKey = getCacheKey('content', '/path/to/file.ts', '{}', {});
console.log(customKey); // Уникальный хеш для файла

7. processAsync

Описание: Асинхронная версия process. Используется для обработки TypeScript-файлов с поддержкой async/await.

Параметры:

• src (string) — исходный код TypeScript
• filePath (string) — путь к файлу
• jestConfig (object) — конфигурация Jest
• transformOptions (object) — опции трансформации

Пример:

const { processAsync } = require('ts-jest');

async function transformFile() {
  const result = await processAsync(
    'const x: number = 5;',
    '/test.ts',
    {},
    {}
  );
  console.log(result.code); // Скомпилированный JavaScript
}

8. shouldProcess

Описание: Определяет, должен ли данный файл обрабатываться ts-jest. Позволяет исключить определённые файлы из обработки.

Параметры:

• filePath (string) — путь к файлу
• jestConfig (object) — конфигурация Jest
• transformOptions (object) — опции трансформации

Пример:

const { shouldProcess } = require('ts-jest');

const processThis = shouldProcess('/project/src/app.ts', {}, {});
const skipThis = shouldProcess('/project/src/styles.css', {}, {});
console.log(processThis); // true
console.log(skipThis); // false

9. version

Описание: Возвращает текущую версию ts-jest. Полезно для проверки совместимости.

Параметры: нет

Пример:

const { version } = require('ts-jest');
console.log(`ts-jest version: ${version}`); // Например: 29.1.0

10. diagnostics

Описание: Объек