Pokrycie kodu

Vitest wspiera natywne pokrycie kodu poprzez v8 oraz pokrycie kodu z instrumentacją poprzez istanbul.

Dostawcy pokrycia

Wsparcie dla v8 i istanbul jest opcjonalne. Domyślnie używany będzie v8.

Możesz wybrać narzędzie do pokrycia, ustawiając test.coverage.provider na v8 lub istanbul:

import { defineConfig } from 'vitest/config';

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

Po uruchomieniu procesu Vitest, Vitest wyświetli monit o automatyczną instalację odpowiedniego pakietu wsparcia.

Możesz także zainstalować je ręcznie:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Dostawca V8

INFO

Poniższy opis pokrycia V8 jest specyficzny dla Vitest i nie odnosi się do innych runnerów testów. Od v3.2.0 Vitest używa przemapowania pokrycia opartego na AST dla pokrycia V8, co generuje raporty pokrycia identyczne z tymi z Istanbul.

Pozwala to użytkownikom cieszyć się szybkością pokrycia V8 przy zachowaniu dokładności pokrycia Istanbul.

Domyślnie Vitest używa dostawcy pokrycia 'v8'. Ten dostawca wymaga środowiska uruchomieniowego JavaScript opartego na silniku V8, takiego jak NodeJS, Deno lub dowolne przeglądarki oparte na Chromium, np. Google Chrome.

Zbieranie pokrycia odbywa się w czasie działania poprzez wydawanie instrukcji V8 za pomocą node:inspector i Chrome DevTools Protocol w przeglądarkach. Pliki źródłowe użytkownika mogą być wykonywane bez modyfikacji.

• ✅ Zalecana opcja do zastosowania
• ✅ Brak kroku wstępnej transpilacji. Pliki testowe mogą być wykonywane bez modyfikacji.
• ✅ Szybsze wykonanie niż Istanbul.
• ✅ Mniejsze zużycie pamięci niż Istanbul.
• ✅ Dokładność raportu pokrycia jest porównywalna z tą w Istanbul (od Vitest v3.2.0).
• ⚠️ W niektórych przypadkach może działać wolniej niż Istanbul, np. podczas ładowania wielu modułów. V8 nie obsługuje ograniczania zakresu zbierania pokrycia do konkretnych modułów.
• ⚠️ Istnieją pewne drobne ograniczenia narzucone przez silnik V8. Zobacz ast-v8-to-istanbul | Ograniczenia.
• ❌ Nie działa w środowiskach, które nie używają V8, takich jak Firefox lub Bun. Lub w środowiskach, które nie udostępniają pokrycia V8 za pośrednictwem profilera, takich jak Cloudflare Workers.

Dostawca Istanbul

Narzędzia do pokrycia kodu Istanbul istnieją od 2012 roku i są bardzo dobrze sprawdzone w praktyce. Ten dostawca działa w każdym środowisku uruchomieniowym JavaScript, ponieważ śledzenie pokrycia odbywa się poprzez instrumentację plików źródłowych użytkownika.

W praktyce instrumentacja plików źródłowych oznacza dodawanie dodatkowego kodu JavaScript do plików użytkownika:

// Uproszczony przykład liczników pokrycia gałęzi i funkcji
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // Pokrycie funkcji wzrasta, gdy jest wywoływana
  coverage.functions['1']++; 

  if (id == null) {
    // Pokrycie gałęzi zwiększone, gdy ta gałąź jest wywoływana
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // Pokrycie niejawnego bloku `else` zwiększone, gdy warunek instrukcji `if` nie jest spełniony
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Działa w każdym środowisku uruchomieniowym JavaScript
• ✅ Szeroko stosowany i dobrze przetestowany przez ponad 13 lat.
• ✅ W niektórych przypadkach może być szybszy niż V8. Instrumentacja pokrycia może być ograniczona do konkretnych plików, w przeciwieństwie do V8, gdzie wszystkie moduły są instrumentowane.
• ❌ Wymaga kroku wstępnej instrumentacji
• ❌ Wykonanie jest wolniejsze niż V8 z powodu narzutu instrumentacji
• ❌ Instrumentacja powoduje zwiększenie rozmiarów plików
• ❌ Zużycie pamięci jest większe niż V8

Konfiguracja pokrycia

TIP

Zaleca się, aby zawsze definiować coverage.include w pliku konfiguracyjnym. Pomaga to Vitest zmniejszyć liczbę plików uwzględnianych przez coverage.all.

Aby testować z włączonym pokryciem, możesz dodać flagę --coverage w CLI. Domyślnie używane będą następujące formaty raportów: ['text', 'html', 'clover', 'json'].

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

Aby skonfigurować pokrycie, ustaw opcje test.coverage w pliku konfiguracyjnym:

import { defineConfig } from 'vitest/config';

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

Niestandardowy raport pokrycia

Możesz użyć niestandardowych raportów pokrycia, podając nazwę pakietu lub ścieżkę absolutną w test.coverage.reporter:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Określ reporter za pomocą nazwy pakietu NPM
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Określ reporter za pomocą ścieżki lokalnej
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Niestandardowe raporty są ładowane przez Istanbul i muszą odpowiadać jego interfejsowi reportera. Zobacz implementację wbudowanych raportów jako punkt odniesienia.

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

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

    // Opcje przekazane z konfiguracji są dostępne tutaj
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Start niestandardowego raportu z pokrycia');
  }

  onEnd() {
    this.contentWriter.println('Koniec niestandardowego raportu z pokrycia');
    this.contentWriter.close();
  }
};

Niestandardowy dostawca pokrycia

Możliwe jest również dostarczenie własnego niestandardowego dostawcy pokrycia, przekazując 'custom' w test.coverage.provider:

import { defineConfig } from 'vitest/config';

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

Niestandardowi dostawcy wymagają opcji customProviderModule, która jest nazwą modułu lub ścieżką, z której ładowany jest CoverageProviderModule. Musi eksportować obiekt, który implementuje CoverageProviderModule jako domyślny eksport:

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

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

  // Implementuje pozostałe elementy CoverageProviderModule ...
};

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

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

  // Implementuje pozostałe elementy CoverageProvider ...
}

export default CustomCoverageProviderModule;

Więcej szczegółów można znaleźć w definicji typu.

Zmiana domyślnej lokalizacji folderu pokrycia

Podczas generowania raportu z pokrycia kodu, w katalogu głównym projektu tworzony jest folder coverage. Jeśli chcesz przenieść go do innego katalogu, użyj właściwości test.coverage.reportsDirectory w pliku vitest.config.js.

import { defineConfig } from 'vite';

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

Ignorowanie kodu

Obaj dostawcy pokrycia mają własne metody ignorowania kodu w raportach pokrycia:

• v8
• ìstanbul
• v8 z experimentalAstAwareRemapping: true zobacz ast-v8-to-istanbul | Ignorowanie kodu

Podczas używania TypeScriptu kod źródłowy jest transpilowany za pomocą esbuild, który usuwa wszystkie komentarze z kodu źródłowego (esbuild#516). Komentarze, które są uważane za legalne komentarze, zostają zachowane.

Możesz dołączyć słowo kluczowe @preserve w komentarzu ignorującym. Pamiętaj, że te komentarze ignorujące mogą teraz również znaleźć się w końcowej wersji produkcyjnej.

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

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

Inne opcje

Aby zobaczyć wszystkie konfigurowalne opcje dotyczące pokrycia, zobacz dokumentację konfiguracji pokrycia.

Wydajność pokrycia

Jeśli generowanie pokrycia kodu jest powolne w Twoim projekcie, zobacz Profilowanie wydajności testów | Pokrycie kodu.

Interfejs użytkownika Vitest

Możesz sprawdzić swój raport z pokrycia kodu w interfejsie użytkownika Vitest.

Interfejs użytkownika Vitest udostępni raport pokrycia, gdy zostanie on jawnie włączony i dostępny będzie raport pokrycia HTML, w przeciwnym razie nie będzie on dostępny:

• włącz coverage.enabled=true w pliku konfiguracyjnym lub uruchom Vitest z flagą --coverage.enabled=true
• dodaj html do listy coverage.reporter: możesz również włączyć opcję subdir, aby zapisać raport pokrycia w podkatalogu