Karma-typescript

Karma — это тест-раннер для JavaScript, который обеспечивает автоматический запуск тестов в различных браузерах. В сочетании с TypeScript он позволяет создавать строгие, масштабируемые и поддерживаемые тестовые среды. Интеграция TypeScript с Karma требует понимания особенностей компиляции, настройки конфигурационных файлов и взаимодействия с фреймворками тестирования.

Настройка проекта для работы с TypeScript и Karma

Для начала необходимо установить основные зависимости:

npm install --save-dev karma karma-jasmine jasmine-core karma-chrome-launcher typescript ts-node karma-typescript

karma: ядро тест-раннера.
karma-jasmine и jasmine-core: фреймворк для написания тестов.
karma-chrome-launcher: запуск тестов в браузере Chrome.
typescript и ts-node: компиляция TypeScript.
karma-typescript: плагин, обеспечивающий корректную обработку TypeScript-файлов и их трансляцию в JavaScript в процессе тестирования.

Создание структуры проекта обычно включает папки:

/src        - исходный код
/tests      - тестовые файлы
/tsconfig.json
/karma.conf.js

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

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

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

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

strict: true обеспечивает максимальную типовую проверку.
sourceMap: true позволяет Karma связывать исходные TypeScript-файлы с скомпилированными JavaScript-файлами для удобного отладки.
include должен охватывать как исходный код, так и тесты.

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

Файл karma.conf.js настраивается для работы с TypeScript:

module.exports = function(config) {
  config.set({
    frameworks: ["jasmine", "karma-typescript"],
    files: [
      { pattern: "src/**/*.ts" },
      { pattern: "tests/**/*.ts" }
    ],
    preprocessors: {
      "**/*.ts": ["karma-typescript"]
    },
    reporters: ["progress", "karma-typescript"],
    browsers: ["ChromeHeadless"],
    singleRun: true,
    karmaTypescriptConfig: {
      tsconfig: "./tsconfig.json",
      compilerOptions: {
        sourceMap: true
      }
    }
  });
};

Объяснение ключевых параметров:

frameworks: указывает на используемые фреймворки; порядок важен — сначала Jasmine, затем karma-typescript.
files: список файлов, которые будут загружены в браузеры.
preprocessors: позволяет обрабатывать TypeScript-файлы перед запуском тестов.
reporters: karma-typescript обеспечивает детальный вывод с информацией о покрытии кода.
browsers: ChromeHeadless позволяет запускать тесты без графического интерфейса, что важно для CI/CD.
singleRun: при значении true Karma запускает тесты один раз и завершает процесс.
karmaTypescriptConfig: дополнительная конфигурация для компилятора TypeScript, включая source maps и другие параметры компиляции.

Структура тестов в TypeScript

Файлы тестов обычно имеют расширение .spec.ts. Пример простого теста:

import { sum } from "../src/math";

describe("sum function", () => {
  it("должна корректно суммировать два числа", () => {
    const result = sum(2, 3);
    expect(result).toBe(5);
  });

  it("должна возвращать число", () => {
    const result = sum(2, 3);
    expect(typeof result).toBe("number");
  });
});

Особенности использования TypeScript в тестах:

Поддержка типов делает тесты более надёжными.
Можно использовать интерфейсы и типы для проверки аргументов функций.
Компилятор обнаруживает ошибки до выполнения теста.

Поддержка модулей и импорта

TypeScript требует явного указания модульной системы (commonjs или ES6). Karma с karma-typescript автоматически обрабатывает import/export. Важно следить за корректными путями и расширениями файлов. Использование относительных путей в тестах (../src/...) предпочтительно для простоты настройки.

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

Для автоматического тестирования в пайплайнах достаточно:

karma start --single-run --browsers ChromeHeadless

Преимущества использования ChromeHeadless:

Минимизация ресурсов на сервере CI.
Быстрый запуск тестов без графического интерфейса.
Поддержка всех возможностей современных браузеров.

Отчёты о покрытии кода

karma-typescript поддерживает генерацию отчётов о покрытии:

reporters: ["progress", "karma-typescript"],
karmaTypescriptConfig: {
  coverageOptions: { instrumentation: true },
  reports: {
    "html": "coverage",
    "text-summary": ""
  }
}

html: создаёт визуальный отчёт в виде веб-страницы.
text-summary: выводит краткую сводку в консоли.
Инструмент instrumentation автоматически добавляет обёртки для анализа покрытия кода.

Совместимость с другими фреймворками

Karma совместим не только с Jasmine, но и с Mocha, QUnit. При использовании Mocha необходимо установить соответствующие адаптеры:

npm install --save-dev karma-mocha chai karma-chrome-launcher karma-typescript

Конфигурация будет аналогичной, с заменой frameworks: ["mocha", "karma-typescript"].

Особенности отладки

Source maps позволяют видеть исходные TypeScript-файлы в DevTools браузера.
Использование debug.html позволяет открыть тесты в браузере с возможностью пошагового выполнения кода.
Логирование в тестах (console.log) полностью поддерживается и отображается в браузере.