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

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

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

TIP

Начиная с версии Vitest 0.22.0

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

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

// vitest.config.ts
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

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

TIP

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

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

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

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

// vitest.config.ts
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 и должны соответствовать его интерфейсу отчетов. См. реализацию встроенных отчетов для справки.

// custom-reporter.cjs
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('Start of custom coverage report');
  }

  onEnd() {
    this.contentWriter.println('End of custom coverage report');
    this.contentWriter.close();
  }
};

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

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

// vitest.config.ts
import { defineConfig } from 'vitest/config';

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

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

// my-custom-coverage-provider.ts
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 в файле vite.config.js.

import { defineConfig } from 'vite';

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

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

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

• v8
• ìstanbul

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

Для провайдера istanbul можно добавить ключевое слово @preserve в комментарий для игнорирования. Имейте в виду, что эти комментарии для игнорирования могут попасть в финальную сборку.

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

Для v8 это не представляет проблемы. Вы можете использовать комментарии v8 ignore с Typescript как обычно:

/* v8 ignore next 3 */
if (condition) {

Другие опции

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

Vitest UI

Начиная с Vitest 0.31.0, вы можете просматривать отчет о покрытии кода в Vitest UI.

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

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