Teamcity reporter

TeamCity Reporter представляет собой плагин для Karma, который позволяет интегрировать результаты запуска тестов JavaScript с системой непрерывной интеграции TeamCity. Основная цель этого репортера — транслировать информацию о тестах в формате, который TeamCity может корректно интерпретировать, создавая подробные отчёты о прогоне тестов, включая успешные проверки, провалы и пропуски.

Установка и подключение

Для использования TeamCity Reporter необходимо установить соответствующий npm-пакет:

npm install karma-teamcity-reporter --save-dev

После установки плагин подключается в конфигурационном файле Karma (karma.conf.js) через поле reporters:

module.exports = function(config) {
  config.set({
    frameworks: ['jasmine'], // или другой выбранный фреймворк
    reporters: ['teamcity'], // подключение TeamCity Reporter
    browsers: ['ChromeHeadless'],
    singleRun: true
  });
};

Если проект использует несколько репортеров, TeamCity Reporter можно указать наряду с ними:

reporters: ['progress', 'teamcity']

Принцип работы

TeamCity Reporter преобразует события, возникающие в процессе тестирования Karma, в формат, распознаваемый TeamCity. Ключевые типы сообщений:

  • testSuiteStarted и testSuiteFinished — начало и завершение набора тестов (suite).
  • testStarted и testFinished — начало и завершение отдельного теста.
  • testFailed — сообщение о провале теста с подробной информацией об ошибке.
  • testIgnored — пропуск теста, что также фиксируется в отчёте CI.

Каждое сообщение имеет строго определённый синтаксис для TeamCity, включая идентификаторы тестов, имена наборов и сообщения об ошибках. Репортер автоматически экранирует специальные символы, такие как |, ', [, ], чтобы избежать нарушения формата.

Конфигурационные опции

TeamCity Reporter поддерживает несколько настроек, которые позволяют гибко управлять отображением тестов в TeamCity:

  • outputFile — путь к файлу, в который будут записаны результаты. Если не указан, вывод идёт в стандартный поток stdout.
  • suite — имя корневого набора тестов, которое отображается в TeamCity. Полезно для группировки тестов по модулям.
  • showDiff — включение/отключение отображения различий в сообщениях об ошибках. Полезно при тестах, где проверяется точное значение строк или объектов.

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

reporters: ['teamcity'],
teamcityReporter: {
  outputFile: 'karma-teamcity.log',
  suite: 'Frontend Unit Tests',
  showDiff: true
}

Интеграция с TeamCity

TeamCity Reporter особенно ценен в автоматизированных сборках, поскольку позволяет:

  • Отслеживать статус каждого теста прямо в интерфейсе TeamCity.
  • Видеть дерево тестов по suite, с группировкой по модулю или пакету.
  • Получать подробные сообщения об ошибках с указанием трассировки стека.
  • Обрабатывать пропущенные тесты, что важно для метрик покрытия.

Для корректной работы CI достаточно убедиться, что процесс запуска Karma перенаправляет вывод репортера в TeamCity. При использовании TeamCity build agent и запуска Karma через npm-скрипты или командную строку никаких дополнительных настроек не требуется.

Особенности использования с различными фреймворками

TeamCity Reporter поддерживает все популярные фреймворки тестирования:

  • Jasmine — отображение describe как suite и it как тест.
  • Mocha — аналогичная обработка describe и it, поддержка асинхронных тестов через промисы.
  • QUnit — suite и test интерпретируются в соответствии с API QUnit, что позволяет видеть полный контекст теста.

Асинхронные тесты также корректно отображаются, включая тайм-ауты и исключения, что критично для сложных фронтенд-приложений с промисами и сетевыми запросами.

Логирование и отладка

Для отладки TeamCity Reporter можно включить подробное логирование:

logLevel: config.LOG_DEBUG

Это позволит видеть все события тестов и их преобразование в формат TeamCity. Особенно полезно при настройке сложных наборов тестов с вложенными suite.

Практические рекомендации

  • Использовать отдельный suite для каждого модуля, чтобы легко идентифицировать источник ошибки.
  • Настроить showDiff: true для тестов, проверяющих строки и объекты, чтобы TeamCity показывал разницу.
  • При интеграции с CI не смешивать вывод других репортеров в stdout, чтобы TeamCity корректно обрабатывал сообщения TeamCity Reporter.
  • Проверять экранирование специальных символов в сообщениях тестов, чтобы избежать сбоев парсера TeamCity.

TeamCity Reporter в Karma обеспечивает прозрачную интеграцию между JavaScript-тестами и системой CI, позволяя получать структурированные отчёты, наглядное отображение статуса тестов и детализированную информацию об ошибках, что критически важно для поддерживаемого, автоматизированного процесса тестирования.

Оглавление