Programmatic API

Programmatic API в Karma предоставляет возможность управлять запуском тестов, конфигурацией и обработкой результатов напрямую из кода JavaScript, минуя стандартный CLI. Это особенно полезно для интеграции Karma в сложные сборочные процессы, динамическое создание конфигураций и автоматизацию тестирования.

Импорт и инициализация

Для работы с Programmatic API необходимо импортировать конструктор Server из пакета karma:

const { Server } = require('karma');

Создание экземпляра сервера происходит через передачу объекта конфигурации и функции обратного вызова, которая вызывается по завершении тестов:

const server = new Server({
  configFile: __dirname + '/karma.conf.js',
  singleRun: true
}, exitCode => {
  console.log('Karma завершила работу с кодом выхода:', exitCode);
});

Запуск тестов осуществляется вызовом метода start():

server.start();

Метод start() возвращает промис, который завершится после окончания выполнения всех тестов, что позволяет использовать его в асинхронных сценариях.

Динамическая конфигурация

Programmatic API позволяет полностью управлять конфигурацией Karma через объект config. Это включает:

  • Фреймворки (frameworks) — например, ['jasmine'].
  • Браузеры (browsers) — например, ['ChromeHeadless'].
  • Файлы для тестирования (files) — шаблоны или конкретные файлы с тестами.
  • Пресеты и плагины (plugins) — подключение кастомных или сторонних плагинов.
  • Репортеры (reporters) — управление выводом результатов тестов.

Пример динамической конфигурации:

const server = new Server({
  frameworks: ['mocha'],
  files: ['test/**/*.spec.js'],
  browsers: ['ChromeHeadless'],
  reporters: ['progress', 'kjhtml'],
  singleRun: true
}, exitCode => {
  console.log('Код выхода:', exitCode);
});

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

Использование Programmatic API для CI/CD

В системах непрерывной интеграции часто требуется запускать тесты без ручного вмешательства. Programmatic API предоставляет полный контроль над процессом:

  • Возможность захватывать код выхода (exitCode) для определения успешности сборки.
  • Настройка singleRun: true гарантирует завершение процесса после выполнения тестов.
  • Возможность динамически генерировать список тестов на основе условий, например, ветки в Git или изменённых файлов.

Пример интеграции в скрипт CI:

const { Server } = require('karma');

const server = new Server({
  configFile: __dirname + '/karma.conf.js',
  singleRun: true
}, exitCode => {
  process.exit(exitCode);
});

server.start();

Отладка и обработка событий

Programmatic API позволяет подписываться на события Karma, что удобно для расширенного логирования или создания кастомных обработчиков:

server.on('browser_register', browser => {
  console.log('Зарегистрирован браузер:', browser.name);
});

server.on('run_complete', (browsers, results) => {
  console.log('Тесты завершены. Успешных:', results.success, 'Ошибок:', results.failed);
});

Основные события, доступные через Server:

  • browser_register — новый браузер подключился.
  • browser_complete — завершение тестов в конкретном браузере.
  • run_start — начало выполнения всех тестов.
  • run_complete — завершение всех тестов, с результатами.

Подписка на события позволяет создавать сложные сценарии автоматизации, например, запуск тестов в нескольких браузерах параллельно и агрегацию результатов.

Расширение и кастомизация

Programmatic API предоставляет возможность интеграции кастомных плагинов и репортеров напрямую через объект конфигурации:

const server = new Server({
  frameworks: ['jasmine'],
  files: ['test/**/*.js'],
  plugins: [
    'karma-jasmine',
    'karma-chrome-launcher',
    {
      'reporter:custom': ['type', function CustomReporter() {
        this.onRunCompl ete = function(browsers, results) {
          console.log('Кастомный репортер:', results);
        };
      }]
    }
  ],
  reporters: ['progress', 'custom'],
  singleRun: true
}, exitCode => {
  process.exit(exitCode);
});

Такой подход позволяет полностью контролировать процесс тестирования и интегрировать Karma в любые нестандартные рабочие процессы.

Асинхронная работа с API

С версии Karma 6+ Server.start() возвращает промис, что упрощает асинхронное управление:

async function runTests() {
  const server = new Server({
    configFile: __dirname + '/karma.conf.js',
    singleRun: true
  });

  try {
    await server.start();
    console.log('Тесты выполнены успешно');
  } catch (err) {
    console.error('Ошибка при выполнении тестов:', err);
  }
}

runTests();

Это делает интеграцию с современными сборщиками, такими как Webpack или Gulp, более удобной, позволяя запускать тесты как часть асинхронного пайплайна.

Преимущества Programmatic API

  • Полная автоматизация запуска тестов без CLI.
  • Динамическая конфигурация и адаптация под любые условия.
  • Возможность интеграции с CI/CD, системами сборки и кастомными инструментами.
  • Поддержка событийного подхода для расширенного логирования и кастомизации.
  • Совместимость с асинхронными сценариями через промисы.

Programmatic API превращает Karma из инструмента командной строки в мощный модуль для программного управления тестированием, обеспечивая гибкость и контроль, недоступные при использовании стандартного запуска через karma start.

Оглавление