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

Vitest поддерживает нативное покрытие через v8 и инструментальное покрытие кода через istanbul.

Провайдеры покрытия

Поддержка v8 и istanbul является опциональной. По умолчанию используется v8.

Вы можете выбрать инструмент покрытия, установив test.coverage.provider в v8 или istanbul:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'istanbul', // или 'v8'
    },
  },
});

При запуске Vitest будет автоматически предложено установить соответствующий пакет поддержки.

Или, если вы предпочитаете установить их вручную:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Провайдер V8

INFO

Описание покрытия V8 ниже специфично для Vitest и не относится к другим средствам запуска тестов. Начиная с v3.2.0, Vitest использует преобразование покрытия на основе AST для покрытия V8, что позволяет генерировать отчеты о покрытии, идентичные Istanbul.

Это позволяет пользователям сочетать скорость покрытия V8 с точностью Istanbul.

По умолчанию Vitest использует провайдер покрытия 'v8'. Этот провайдер требует среду выполнения JavaScript, реализованную на основе движка V8, например NodeJS, Deno или любой браузер на основе Chromium, такой как Google Chrome.

Сбор покрытия выполняется во время выполнения путем инструктирования V8 через node:inspector и Chrome DevTools Protocol в браузерах. Исходные файлы пользователя могут быть выполнены без изменений, без каких-либо предварительных шагов инструментирования.

• ✅ Рекомендуемый вариант использования
• ✅ Нет шага предварительной транспиляции. Тестовые файлы могут быть выполнены как есть.
• ✅ Более высокая скорость выполнения, чем у Istanbul.
• ✅ Меньшее потребление памяти, чем у Istanbul.
• ✅ Точность отчета о покрытии не уступает Istanbul (начиная с Vitest v3.2.0).
• ⚠️ В некоторых случаях может быть медленнее, чем Istanbul, например, при загрузке множества различных модулей. V8 не поддерживает ограничение сбора покрытия только для определенных модулей.
• ⚠️ Существуют некоторые незначительные ограничения движка V8. См. ast-v8-to-istanbl | Limitations.
• ❌ Не работает в средах, не использующих V8 (например, Firefox или Bun), или в средах, не предоставляющих покрытие V8 через профайлер (например, Cloudflare Workers).

Провайдер Istanbul

Инструментарий покрытия кода Istanbul существует с 2012 года и хорошо зарекомендовал себя. Этот провайдер работает в любой среде выполнения JavaScript, поскольку отслеживание покрытия осуществляется путем инструментирования исходных файлов пользователя.

На практике инструментирование исходных файлов означает добавление дополнительного JavaScript в пользовательские файлы:

// Упрощенный пример счетчиков покрытия ветвей и функций
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // Счетчик покрытия функции увеличивается при ее вызове
  coverage.functions['1']++; 

  if (id == null) {
    // Счетчик покрытия ветви увеличивается при ее вызове
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // Покрытие неявной ветви `else` увеличивается, когда условие `if`-оператора не выполняется
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

globalThis.__VITEST_COVERAGE__ ||= {}; 
globalThis.__VITEST_COVERAGE__[filename] = coverage; 

• ✅ Работает в любой среде выполнения JavaScript
• ✅ Широко используется и хорошо зарекомендовал себя более 13 лет.
• ✅ В некоторых случаях быстрее, чем V8. Инструментирование покрытия может быть ограничено определенными файлами, в отличие от V8, где инструментируются все модули без исключения.
• ❌ Требуется предварительное инструментирование.
• ❌ Скорость выполнения медленнее, чем у V8, из-за накладных расходов инструментирования.
• ❌ Инструментирование увеличивает размер файлов кода.
• ❌ Потребление памяти выше, чем у V8.

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

TIP

Рекомендуется всегда определять coverage.include в вашем файле конфигурации. Это помогает Vitest уменьшить количество файлов, обрабатываемых coverage.all.

Чтобы запустить тесты с включенным покрытием, вы можете передать флаг --coverage в CLI. По умолчанию используется репортер ['text', 'html', 'clover', 'json'].

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

Чтобы настроить его, установите параметры test.coverage в вашем файле конфигурации:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: ['text', 'json', 'html'],
    },
  },
});

Пользовательский репортер покрытия

Вы можете использовать пользовательские репортеры покрытия, передав либо имя пакета, либо абсолютный путь в test.coverage.reporter:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Указать репортер с помощью имени NPM-пакета
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Указать репортер по локальному пути
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

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

const { ReportBase } = require('istanbul-lib-report');

module.exports = class CustomReporter extends ReportBase {
  constructor(opts) {
    super();

    // Опции, переданные в конфигурации, доступны здесь
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Начало пользовательского отчета о покрытии');
  }

  onEnd() {
    this.contentWriter.println('Конец пользовательского отчета о покрытии');
    this.contentWriter.close();
  }
};

Пользовательский провайдер покрытия

Также возможно предоставить свой собственный провайдер покрытия, указав 'custom' в test.coverage.provider:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      provider: 'custom',
      customProviderModule: 'my-custom-coverage-provider',
    },
  },
});

Пользовательские провайдеры требуют опции customProviderModule, которая является именем или путем к модулю, из которого загружается CoverageProviderModule. Он должен экспортировать объект, реализующий CoverageProviderModule, как экспорт по умолчанию:

import type {
  CoverageProvider,
  CoverageProviderModule,
  ResolvedCoverageOptions,
  Vitest,
} from 'vitest';

const CustomCoverageProviderModule: CoverageProviderModule = {
  getProvider(): CoverageProvider {
    return new CustomCoverageProvider();
  },

  // Реализует остальные методы CoverageProviderModule ...
};

class CustomCoverageProvider implements CoverageProvider {
  name = 'custom-coverage-provider';
  options!: ResolvedCoverageOptions;

  initialize(ctx: Vitest) {
    this.options = ctx.config.coverage;
  }

  // Реализует остальные методы CoverageProvider ...
}

export default CustomCoverageProviderModule;

Пожалуйста, обратитесь к определению типа для получения более подробной информации.

Изменение расположения папки покрытия по умолчанию

При создании отчета о покрытии в корневом каталоге вашего проекта будет создана папка coverage. Если вы хотите переместить ее в другой каталог, используйте свойство test.coverage.reportsDirectory в файле vitest.config.js.

import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    coverage: {
      reportsDirectory: './tests/unit/coverage',
    },
  },
});

Игнорирование кода

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

• v8
• ìstanbul
• v8 с experimentalAstAwareRemapping: true см. ast-v8-to-istanbul | Ignoring code

При использовании TypeScript исходные коды транспилируются с помощью esbuild, который удаляет все комментарии из исходного кода (esbuild#516). Сохраняются только комментарии, которые считаются легальными комментариями.

Вы можете включить ключевое слово @preserve в директиву игнорирования. Обратите внимание, что эти директивы игнорирования теперь могут попасть и в финальную производственную сборку.

-/* istanbul ignore if */
+/* istanbul ignore if -- @preserve */
if (condition) {

-/* v8 ignore if */
+/* v8 ignore if -- @preserve */
if (condition) {

Другие опции

Чтобы увидеть все настраиваемые параметры для покрытия, см. Справочник по конфигурации покрытия.

Производительность покрытия

Если генерация покрытия кода в вашем проекте происходит медленно, см. Профилирование производительности тестов | Покрытие кода.

Vitest UI

Вы можете проверить свой отчет о покрытии в Vitest UI.

Vitest UI отобразит отчет о покрытии, если он явно включен и доступен HTML-репортер покрытия; в противном случае отчет не будет доступен:

• активируйте coverage.enabled=true в вашем файле конфигурации или запустите Vitest с флагом --coverage.enabled=true
• добавьте html в список coverage.reporter: вы также можете включить опцию subdir, чтобы сохранить отчет о покрытии в подкаталоге