Настройка Istanbul через karma-coverage

Karma — это тестовый раннер для JavaScript, который позволяет запускать тесты в различных браузерах и автоматизировать процесс проверки кода. Одной из ключевых задач при тестировании является измерение покрытия кода, и для этого используется интеграция с Istanbul через плагин karma-coverage. Эта интеграция обеспечивает сбор метрик покрытия и позволяет визуализировать, какие участки кода протестированы, а какие нет.

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

Для работы с karma-coverage необходимо установить следующие пакеты через npm:

npm install --save-dev karma karma-jasmine karma-chrome-launcher karma-coverage jasmine-core
  • karma — основной тестовый раннер.
  • karma-jasmine — адаптер для фреймворка Jasmine.
  • karma-chrome-launcher — позволяет запускать тесты в браузере Chrome.
  • karma-coverage — плагин для интеграции с Istanbul и генерации отчётов о покрытии.
  • jasmine-core — фреймворк для написания тестов.

Подключение плагина в конфигурацию Karma

После установки необходимо настроить karma.conf.js для использования плагина. Основные шаги:

  1. Импортировать плагины.
  2. Указать preprocessors для файлов, которые нужно анализировать.
  3. Настроить reporter для генерации отчётов.

Пример конфигурации:

module.exports = function(config) {
  config.set({
    frameworks: ['jasmine'],
    files: [
      'src/**/*.js',
      'test/**/*.spec.js'
    ],
    preprocessors: {
      'src/**/*.js': ['coverage']
    },
    reporters: ['progress', 'coverage'],
    coverageReporter: {
      type: 'html',       // тип отчёта: html, lcov, text-summary
      dir: 'coverage/',   // директория для отчётов
      includeAllSources: true,
      instrumenterOptions: {
        istanbul: { noCompact: true }
      }
    },
    browsers: ['ChromeHeadless'],
    singleRun: true
  });
};

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

  • preprocessors с ключом 'coverage' указывает Karma использовать Istanbul для инструментирования исходного кода перед запуском тестов.
  • coverageReporter настраивает формат и расположение отчётов. Часто используют html для визуального анализа и text-summary для краткой консолидации.
  • includeAllSources: true гарантирует, что покрытие будет рассчитано даже для файлов, на которые нет прямых тестов.

Форматы отчётов

karma-coverage поддерживает несколько форматов:

  • html — создаёт интерактивные HTML-страницы с подсветкой покрытых и непокрытых строк.
  • lcov — используется для интеграции с CI/CD и другими инструментами анализа.
  • text — выводит покрытие в консоль в виде таблицы.
  • text-summary — краткий отчёт с процентами покрытия для строк, функций и ветвлений.

Пример комбинирования форматов:

coverageReporter: {
  dir: 'coverage/',
  reporters: [
    { type: 'html', subdir: 'html' },
    { type: 'lcov', subdir: 'lcov' },
    { type: 'text-summary' }
  ]
}

Такой подход позволяет одновременно получать визуальные отчёты и интегрировать их с CI-системами.

Инструментирование кода

Istanbul работает путём инструментирования исходного кода: он добавляет специальные счётчики перед каждой строкой, функцией или ветвлением кода. Karma с плагином karma-coverage автоматически применяет это инструментирование перед запуском тестов.

Важно: инструментировать следует только исходный код, а не тесты. Поэтому в preprocessors нужно указывать путь только к src/**/*.js.

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

Для автоматической проверки покрытия в CI/CD можно использовать lcov формат и инструменты вроде Codecov или Coveralls. Пример шагов для GitHub Actions:

- name: Run tests
  run: npx karma start --single-run

- name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    files: coverage/lcov/*.info

Это обеспечивает непрерывный контроль качества кода и позволяет автоматически отслеживать снижение покрытия после внесения изменений.

Настройка порогов покрытия

Для строгого контроля качества можно установить минимальные пороги покрытия, при которых сборка будет считаться успешной:

coverageReporter: {
  dir: 'coverage/',
  reporters: [{ type: 'lcov' }],
  check: {
    global: {
      statements: 80,
      branches: 70,
      functions: 75,
      lines: 80
    }
  }
}

Если покрытие падает ниже указанных процентов, Karma завершит работу с ошибкой, что предотвращает слияние непроверенного кода.

Поддержка современных стандартов

Для проектов на ES6+ или TypeScript необходимо использовать транспиляторы (Babel или TypeScript) перед инструментированием:

preprocessors: {
  'src/**/*.js': ['babel', 'coverage']
},
babelPreprocessor: {
  options: {
    presets: ['@babel/preset-env']
  }
}

Это гарантирует, что Istanbul сможет правильно анализировать синтаксис современных стандартов.

Полезные рекомендации

  • Всегда проверять, что includeAllSources включён, чтобы покрытие считалось корректно даже для неиспользуемого кода.
  • Использовать Headless-браузеры (ChromeHeadless) для ускорения тестов и интеграции с CI.
  • Разделять отчёты по папкам (html, lcov) для удобства визуального анализа и автоматизированной проверки.
  • Настраивать пороги покрытия для поддержания стабильного качества кода и предотвращения деградации тестов.

Эта схема позволяет построить надёжный процесс измерения покрытия, объединяя Karma и Istanbul через karma-coverage, и формирует основу для комплексного контроля качества JavaScript-проектов.

Оглавление