Покрытие кода тестами

Покрытие кода показывает, какие строки, ветви и функции вашего кода действительно выполнялись во время запуска тестов. В Deno поддержка покрытия встроена: не нужны этап инструментирования и дополнительные зависимости. Рабочий процесс состоит из двух команд: deno test --coverage собирает данные, а deno coverage преобразует их в отчёт.

Сбор данных о покрытии

Передайте --coverage при запуске тестов:

deno test --coverage

Необработанные данные о покрытии записываются в каталог coverage/ — по одному профилю JSON для каждого модуля. Данные поступают напрямую от движка JavaScript V8, который отслеживает выполнение кода, поэтому показатели точно отражают то, что выполнилось, а не приблизительную оценку на основе преобразования исходного кода.

Deno также выводит сводную таблицу покрытия после результатов тестов и записывает файл lcov.info и HTML-отчёт в каталог покрытия. Если нужны только необработанные профили, передайте --coverage-raw-data-only.

Чтобы использовать другой каталог, укажите значение для флага или задайте переменную окружения DENO_COVERAGE_DIR:

deno test --coverage=cov_profile

Данные о покрытии накапливаются при каждом запуске. После переименования или удаления файлов устаревшие профили могут остаться и исказить отчёт, поэтому передайте --clean, чтобы очистить каталог перед запуском тестов:

deno test --clean --coverage

Сбор данных о покрытии вне deno test

deno run принимает тот же флаг --coverage. Это удобно, если нужный код не запускается тестовым раннером: например, для скриптов интеграции, вызова вашей программы через CLI или сервера, который проверяется извне.

deno run --coverage=cov_profile main.ts

Если ваши тесты запускают дочерние процессы Deno, задайте вместо этого переменную окружения DENO_COVERAGE_DIR. Дочерние процессы наследуют её, поэтому данные об их выполнении собираются в тот же каталог и попадают в общий отчёт:

DENO_COVERAGE_DIR=cov_profile deno test --allow-run
deno coverage cov_profile

Чтение отчёта

Укажите для deno coverage каталог, в который вы собирали данные:

deno coverage coverage/

Для нового проекта, созданного с помощью deno init, который генерирует обработчик HTTP main.ts и main_test.ts для его проверки, отчёт выглядит так:

$ deno coverage coverage/
| File      | Branch % | Function % | Line % |
| --------- | -------- | ---------- | ------ |
| main.ts   |     75.0 |      100.0 |   80.0 |
| All files |     75.0 |      100.0 |   80.0 |

В каждой строке показаны три процентных показателя для файла:

• Ветви %: доля выполненных условных путей (каждая ветвь if, тернарного оператора и т. д.)
• Функции %: доля объявленных функций, вызванных хотя бы один раз
• Строки %: доля выполненных исполняемых строк

Чтобы увидеть, какие строки не были выполнены, добавьте --detailed. Непокрытые строки перечислены под каждым файлом:

$ deno coverage --detailed coverage/
cover file:///dev/my-project/main.ts ... 80.000% (12/15)
  16 | if (import.meta.main) {
  17 |   Deno.serve(handler);
  18 | }

В этом примере тесты напрямую импортируют и вызывают функцию handler, но не запускают сервер, поэтому блок import.meta.main в конце main.ts — это код, который не выполнялся. Именно на такие выводы стоит обратить внимание: либо протестируйте отсутствующий путь выполнения, либо исключите его намеренно.

Создание HTML-отчёта

Если файлов больше пары, в HTML-отчёте проще ориентироваться. В нём сводная таблица представлена в виде интерактивного дерева файлов, а исходный код каждого файла отображается построчно с подсветкой непокрытого кода:

deno coverage --html coverage/

Отчёт записывается в coverage/html/. Откройте coverage/html/index.html в браузере, чтобы просмотреть его.

Экспорт lcov для CI

Большинство сервисов анализа покрытия и расширений редакторов используют формат lcov. Создайте файл в этом формате с помощью --lcov:

deno coverage --lcov --output=coverage.lcov coverage/

Если не указать --output, отчёт lcov выводится в stdout. В рабочем процессе GitHub Actions создайте файл и загрузите его в сервис анализа покрытия, например с помощью действия Codecov:

steps:
  - uses: actions/checkout@v4
  - uses: denoland/setup-deno@v2
  - run: deno test --coverage
  - run: deno coverage --lcov --output=coverage.lcov coverage/
  - uses: codecov/codecov-action@v5
    with:
      files: coverage.lcov

Контроль порогового значения покрытия

deno coverage сообщает о покрытии, но не имеет встроенного флага для завершения с ошибкой, если покрытие опустится ниже заданного порога. Существуют два распространённых способа контролировать покрытие:

1. Поручить это сервису анализа покрытия. Codecov, Coveralls и подобные сервисы могут завершать проверку статуса pull request с ошибкой, если покрытие снизилось или оказалось ниже заданного порога, а также отслеживать динамику изменений.
2. Самостоятельно проверять файл lcov в CI. Запись для каждого файла содержит LF (найденные строки) и LH (выполненные строки), поэтому их суммирование даёт общее покрытие строк:

deno coverage --lcov coverage/ > coverage.lcov
awk -F: '/^LF/ {lf += $2} /^LH/ {lh += $2}
  END {pct = 100 * lh / lf; printf "line coverage: %.1f%%\n", pct;
  exit (pct < 80)}' coverage.lcov

Сценарий awk завершает работу с ненулевым кодом возврата, если покрытие строк ниже 80%, что приводит к сбою шага CI.

Выбор файлов для отчёта

По умолчанию в отчёт включается ваш локальный код и его импорты (URL, соответствующие ^file:), а также исключаются файлы, в именах которых есть test.js, test.mjs, test.ts, test.jsx или test.tsx, чтобы тестовые файлы не завышали показатели. Настройте это с помощью регулярных выражений --include и --exclude. Файл попадёт в отчёт, только если соответствует шаблону включения и не соответствует шаблону исключения:

# Report on main.ts only
deno coverage --include="main.ts" coverage/

# Also include remote modules fetched over https
deno coverage --include="^file:|https:" coverage/

Исключение кода из отчёта

Некоторый код намеренно не тестируется: резервные варианты для отдельных платформ, отладочные функции или блок точки входа, такой как пример import.meta.main выше. Пометьте его комментариями для исключения из анализа покрытия — тогда он будет считаться пустыми строками и не повлияет на показатели:

// deno-coverage-ignore
console.log("this single line is ignored");

// deno-coverage-ignore-start
if (import.meta.main) {
  Deno.serve(handler);
}
// deno-coverage-ignore-stop

Чтобы исключить из отчёта весь файл, добавьте // deno-coverage-ignore-file в начало файла. Для каждого комментария -start должен быть соответствующий -stop, а диапазоны нельзя вкладывать друг в друга. Полные правила см. в разделе исключение кода справочной документации.

Что дальше

• Тестирование в Deno: тестовый раннер, проверки и имитация зависимостей
• Справочник по deno coverage: все флаги и правила комментариев для исключения кода
• Справочник по deno test: все параметры тестового раннера, включая сбор данных о покрытии