Настройка karma-typescript

karma-typescript — это плагин для Karma, позволяющий интегрировать TypeScript в процесс тестирования JavaScript-приложений. Он выполняет компиляцию TypeScript, обрабатывает зависимости модулей и обеспечивает покрытие кода с минимальной настройкой. Правильная конфигурация этого инструмента критична для стабильной работы тестов и точной генерации отчетов о покрытии.

Установка зависимостей

Для работы karma-typescript необходимы следующие пакеты:

npm install --save-dev karma karma-typescript typescript
npm install --save-dev karma-jasmine jasmine-core
  • karma — тестовый раннер, основной инструмент для запуска тестов.
  • karma-typescript — обеспечивает интеграцию TypeScript с Karma.
  • typescript — компилятор TS.
  • karma-jasmine и jasmine-core — фреймворк для написания тестов (можно заменить на Mocha, Jest и т.д.).

Дополнительно можно установить плагины для генерации отчетов о покрытии кода:

npm install --save-dev karma-coverage-istanbul-reporter

Настройка TypeScript

Файл tsconfig.json должен быть адаптирован под тестирование. Основные параметры:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "commonjs",
    "sourceMap": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*.ts", "test/**/*.ts"]
}

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

  • sourceMap: true необходим для корректного отображения ошибок в тестах и покрытия кода.
  • include должен содержать и исходники, и тесты.
  • module: commonjs требуется для работы Karma с NodeJS-плагинами.

Конфигурация Karma

Файл karma.conf.js содержит настройки для интеграции TypeScript через плагин:

module.exports = function(config) {
  config.set({
    frameworks: ['jasmine', 'karma-typescript'],

    files: [
      { pattern: 'src/**/*.ts' },
      { pattern: 'test/**/*.ts' }
    ],

    preprocessors: {
      'src/**/*.ts': ['karma-typescript'],
      'test/**/*.ts': ['karma-typescript']
    },

    reporters: ['progress', 'karma-typescript'],

    browsers: ['ChromeHeadless'],

    singleRun: true,

    karmaTypescriptConfig: {
      tsconfig: './tsconfig.json',
      bundlerOptions: {
        sourceMap: true,
        transforms: [
          require('karma-typescript-es6-transform')()
        ]
      },
      coverageOptions: {
        instrumentation: true
      },
      reports: {
        "html": "coverage",
        "text-summary": ""
      }
    }
  });
};

Разбор ключевых блоков:

  • frameworks — включает karma-typescript перед тестовым фреймворком, чтобы TypeScript компилировался до запуска тестов.

  • files — указывает на все файлы, которые должны участвовать в тестировании.

  • preprocessors — задаёт обработку файлов через karma-typescript.

  • reporters — определяет вывод прогресса и отчетов о покрытии.

  • karmaTypescriptConfig — внутренние настройки плагина:

    • tsconfig — путь к конфигурации TypeScript.
    • bundlerOptions.transforms — позволяет добавлять трансформации, например для поддержки ES6.
    • coverageOptions.instrumentation — включение подсчета покрытия кода.
    • reports — определяет формат и путь для отчётов.

Интеграция с CI/CD

Для непрерывной интеграции важно использовать безголовые браузеры (ChromeHeadless, FirefoxHeadless) и singleRun: true. Это гарантирует автоматическое завершение тестов без вмешательства пользователя. Пример скрипта в package.json:

"scripts": {
  "test": "karma start --single-run",
  "test:watch": "karma start"
}
  • test запускает один раз и завершает процесс.
  • test:watch запускает тесты в режиме наблюдения за изменениями файлов.

Тонкости работы с модулями

karma-typescript использует встроенный бандлер. Основные моменты:

  1. CommonJS vs ES Modules Karma автоматически бандлит CommonJS. Для ES Modules нужна дополнительная трансформация через karma-typescript-es6-transform.

  2. Порядок файлов Включение зависимостей в files должно соответствовать порядку импорта, иначе могут возникнуть ошибки ReferenceError.

  3. Совместимость с библиотеками Для некоторых библиотек (например, RxJS, Lodash) может понадобиться исключить исходники из покрытия через coverageOptions.exclude:

    coverageOptions: {
  instrumentation: true,
  exclude: [/node_modules/]
}

Генерация отчетов о покрытии

karma-typescript поддерживает HTML, lcov, текстовые отчеты. Пример настройки:

reports: {
  "html": "coverage",
  "lcovonly": {
    "directory": "coverage",
    "filename": "lcov.info"
  },
  "text-summary": ""
}

Особенности:

  • HTML-отчёты позволяют визуально просмотреть непокрытые строки.
  • lcov используется для CI-сервисов, таких как GitHub Actions, GitLab CI.
  • text-summary выводит краткую сводку в консоль.

Оптимизация производительности

  1. Кэширование karma-typescript автоматически кэширует скомпилированные файлы для ускорения повторных запусков.

    karmaTypescriptConfig: {
  bundlerOptions: {
    cache: true
  }
}

  2. Избегание лишних файлов Не включать большие внешние библиотеки или node_modules в files.

  3. Совместное использование sourceMap sourceMap: true ускоряет дебаг и обеспечивает корректные отчеты покрытия без дополнительных трансформаций.

Расширенные возможности

  • Трансформации Позволяют интегрировать Babel, ES6-полифиллы или другие компиляторы поверх TypeScript.

  • Настройка coverage Возможность исключения конкретных файлов или папок, установка порогов покрытия:

    coverageOptions: {
  instrumentation: true,
  exclude: ["test/**/*.ts"],
  thresholds: {
    global: {
      statements: 80,
      branches: 75,
      functions: 85,
      lines: 80
    }
  }
}

  • Совместимость с другими фреймворками Помимо Jasmine, можно использовать Mocha, QUnit, Jest в связке с Karma через соответствующие плагины.

karma-typescript обеспечивает полный цикл тестирования TypeScript-проектов: компиляцию, бандлинг, запуск тестов и генерацию отчетов покрытия. Грамотная настройка конфигурации повышает стабильность тестов, ускоряет повторные запуски и упрощает интеграцию в CI/CD.

Оглавление