Конфигурация tsconfig для тестов

При использовании TypeScript в проектах с Karma тестированием крайне важно правильно настроить tsconfig. Ошибки в конфигурации могут приводить к проблемам с компиляцией, некорректной работой модулей и неправильной интерпретации путей. Для тестовой среды конфигурация TypeScript отличается от основной сборки приложения, поскольку цель компиляции и набор опций ориентированы на юнит-тесты и их совместимость с Karma и выбранными фреймворками тестирования, например, Jasmine или Mocha.

Основные принципы настройки tsconfig для тестов

  1. Отдельный tsconfig для тестов Рекомендуется создавать отдельный файл tsconfig.spec.json или tsconfig.test.json, который наследует базовый tsconfig.json приложения. Это позволяет не изменять основные опции компиляции для боевой сборки.

    {
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "types": ["jasmine", "node"],
    "module": "commonjs",
    "target": "es6",
    "sourceMap": true,
    "inlineSourceMap": true,
    "inlineSources": true
  },
  "include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
}

    Ключевые моменты:

    • outDir — отдельная папка для компилированных тестов, чтобы не смешивать артефакты с основной сборкой.
    • types — подключение типов фреймворка тестирования и Node.js.
    • module и target — настройки совместимости с Karma и браузером.
    • inlineSourceMap и inlineSources — необходимы для корректной работы отладчика в браузере и отображения исходного кода при ошибках тестов.

  2. Включение исходников тестов Включение тестовых файлов в include обеспечивает компиляцию только необходимых файлов:

    "include": [
  "src/**/*.spec.ts",
  "src/**/*.test.ts"
]

    При этом исходники приложения (.ts файлы без .spec) не компилируются отдельно для тестов, что ускоряет процесс и снижает вероятность конфликтов типов.

  3. Совместимость модулей и фреймворков Karma использует загрузчики, такие как Webpack или SystemJS. Параметры компиляции TypeScript должны быть согласованы с ними:

    • module: "commonjs" — при использовании Webpack или Node.js окружения.
    • module: "esnext" — при использовании современных сборщиков с поддержкой ES модулей.
    • target: "es6" — минимальный стандарт для большинства браузеров, поддерживающий Promise и async/await, часто используемых в тестах.

  4. Подключение деклараций типов Для корректной работы TypeScript с Jasmine, Mocha или Jest необходимо добавить типы:

    "types": ["jasmine", "node"]

    Это позволяет использовать глобальные функции тестовых фреймворков (describe, it, beforeEach) без ошибок компиляции.

  5. Source maps и отладка Для Karma важно видеть точные строки исходного кода при ошибках:

    • sourceMap: true — генерация .map файлов.
    • inlineSourceMap: true — включение карт прямо в выходной .js файл.
    • inlineSources: true — включение исходного TypeScript кода для удобной отладки в браузере.

  6. Исключение ненужных файлов Для ускорения компиляции и предотвращения конфликтов исключаются артефакты сборки и node_modules:

    "exclude": [
  "node_modules",
  "dist",
  "out-tsc"
]

Особенности интеграции с Karma

  • Preprocessor TypeScript: Karma использует karma-typescript или Webpack с ts-loader для компиляции тестов на лету. В этом случае tsconfig.spec.json должен быть согласован с настройками загрузчика.
  • Пути и алиасы: Если основной проект использует paths в tsconfig, для тестов нужно дублировать эти алиасы или использовать tsconfig-paths с Karma.
  • Совместимость с Jasmine: Для корректного распознавания глобальных функций Jasmine необходимо, чтобы types включали "jasmine", иначе компилятор TypeScript будет ругаться на неопределённые идентификаторы.

Практические советы

  • Разделение конфигураций для основной сборки и тестов облегчает масштабирование проекта.
  • Всегда использовать inlineSourceMap и inlineSources для улучшенной отладки в браузере.
  • Проверка корректности типов тестов перед запуском Karma предотвращает runtime ошибки.
  • Для больших проектов рекомендуется добавить отдельный скрипт tsc -p tsconfig.spec.json --noEmit для проверки тестовых типов без фактической компиляции, ускоряя процесс CI.

Настройка tsconfig для тестов — это ключевой элемент стабильной интеграции TypeScript с Karma. Грамотно составленный файл конфигурации позволяет ускорить сборку, улучшить отладку и исключить распространённые ошибки типов и совместимости.

Оглавление