Pokrytí kódu

Vitest podporuje nativní pokrytí kódu pomocí v8 a instrumentované pokrytí kódu pomocí istanbul.

Poskytovatelé pokrytí kódu

Podpora pro v8 i istanbul je volitelná. Ve výchozím nastavení se použije v8.

Nástroj pro pokrytí kódu můžete vybrat nastavením test.coverage.provider na v8 nebo istanbul:

import { defineConfig } from 'vitest/config';

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

Když spustíte proces Vitest, automaticky vás vyzve k instalaci potřebného balíčku podpory.

Nebo je můžete nainstalovat ručně:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Poskytovatel V8

INFO

Popis pokrytí V8 níže je specifický pro Vitest a nevztahuje se na jiné testovací nástroje. Od verze v3.2.0 Vitest používá pro pokrytí V8 přemapování založené na AST, které vytváří identické zprávy o pokrytí jako Istanbul.

To uživatelům umožňuje využívat rychlost pokrytí V8 s přesností pokrytí Istanbul.

Ve výchozím nastavení Vitest používá poskytovatele pokrytí V8. Tento poskytovatel vyžaduje Javascript runtime, který je postaven na V8 enginu, jako je NodeJS, Deno nebo jakékoli prohlížeče založené na Chromiu (například Google Chrome).

Sběr pokrytí se provádí za běhu pomocí instrukcí pro V8, které využívají node:inspector a Chrome DevTools Protocol v prohlížečích. Zdrojové soubory uživatele mohou být spuštěny přímo, bez jakýchkoli kroků předinstrumentace.

• ✅ Doporučená možnost použití
• ✅ Není potřeba předběžná kompilace. Testovací soubory lze spustit přímo.
• ✅ Rychlejší spouštění než Istanbul.
• ✅ Menší nároky na paměť než Istanbul.
• ✅ Stejně přesné výsledky pokrytí jako Istanbul (od Vitest v3.2.0).
• ⚠️ V některých případech může být pomalejší než Istanbul, např. při načítání mnoha různých modulů. V8 nepodporuje omezení sběru pokrytí na konkrétní moduly.
• ⚠️ Existují některá drobná omezení nastavená enginem V8. Viz ast-v8-to-istanbl | Omezení.
• ❌ Nefunguje v prostředích, která nepoužívají V8 (jako je Firefox nebo Bun), ani v prostředích, která nevystavují pokrytí V8 přes profiler (jako jsou Cloudflare Workers).

Poskytovatel Istanbul

Nástroj Istanbul pro pokrytí kódu existuje od roku 2012 a je velmi dobře osvědčený. Tento poskytovatel funguje na jakémkoli Javascript runtime, protože sledování pokrytí se provádí instrumentací uživatelských zdrojových souborů.

V praxi instrumentace zdrojových souborů znamená přidání dalšího Javascriptu do souborů uživatele:

// Zjednodušený příklad sledování pokrytí větví a funkcí
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // Pokrytí funkce se zvýší při jejím volání
  coverage.functions['1']++; 

  if (id == null) {
    // Pokrytí větve se zvýší, když je tato větev provedena
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // Pokrytí implicitní else větve se zvýší, když podmínka if-příkazu není splněna
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Funguje na jakémkoli Javascript runtime
• ✅ Široce používané a prověřené po více než 13 let.
• ✅ V některých případech rychlejší než V8. Instrumentace pokrytí může být omezena na konkrétní soubory, na rozdíl od V8, kde jsou instrumentovány všechny moduly.
• ❌ Vyžaduje předinstrumentaci
• ❌ Provádění je pomalejší než V8 kvůli režii instrumentace
• ❌ Instrumentace zvětšuje soubory
• ❌ Spotřeba paměti je vyšší než V8

Nastavení pokrytí kódu

TIP

Vždy se doporučuje definovat coverage.include ve vašem konfiguračním souboru. To pomáhá Vitestu snížit počet souborů vybraných pomocí coverage.all.

Pro testování s měřením pokrytí můžete v CLI použít příznak --coverage. Ve výchozím nastavení se použije výstupní formát ['text', 'html', 'clover', 'json'].

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

Pro konfiguraci nastavte možnosti test.coverage ve vašem konfiguračním souboru:

import { defineConfig } from 'vitest/config';

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

Vlastní reportér pokrytí kódu

Můžete použít vlastní reportéry pokrytí kódu předáním buď názvu balíčku, nebo absolutní cesty v test.coverage.reporter:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Uveďte reportér pomocí názvu npm balíčku
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Zadejte reportér pomocí lokální cesty
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Vlastní reportéry zpracovává Istanbul a musí odpovídat jeho rozhraní reportéru. Pro referenci viz implementace vestavěných reportérů.

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

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

    // Zde jsou dostupné parametry z konfigurace
    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();
  }
};

Vlastní poskytovatel pokrytí kódu

Je také možné poskytnout vlastního poskytovatele pokrytí kódu předáním 'custom' v test.coverage.provider:

import { defineConfig } from 'vitest/config';

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

Vlastní poskytovatelé vyžadují možnost customProviderModule, což je název modulu nebo cesta, odkud se má načíst CoverageProviderModule. Musí exportovat objekt, který implementuje CoverageProviderModule jako výchozí export:

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

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

  // Implementuje zbytek CoverageProviderModule ...
};

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

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

  // Implementuje zbytek CoverageProvider ...
}

export default CustomCoverageProviderModule;

Pro více podrobností se prosím podívejte na definici typu.

Změna výchozího umístění složky pokrytí kódu

Při generování reportu o pokrytí kódu se v kořenovém adresáři vašeho projektu vytvoří složka coverage. Pokud ji chcete přesunout do jiného adresáře, použijte vlastnost test.coverage.reportsDirectory v souboru vitest.config.js.

import { defineConfig } from 'vite';

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

Ignorování kódu

Oba poskytovatelé pokrytí kódu mají své vlastní způsoby, jak ignorovat kód ze zpráv o pokrytí:

• v8
• ìstanbul
• v8 s experimentalAstAwareRemapping: true viz ast-v8-to-istanbul | Ignorování kódu

Při použití TypeScriptu jsou zdrojové kódy transpilovány pomocí esbuild, který odstraňuje všechny komentáře ze zdrojových kódů (esbuild#516). Komentáře, které jsou považovány za legální komentáře, jsou zachovány.

Do komentáře pro ignorování můžete přidat klíčové slovo @preserve. Pozor, tyto komentáře pro ignorování mohou být nyní zahrnuty i do finální produkční sestavy.

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

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

Další možnosti

Všechny nastavitelné parametry pro pokrytí kódu naleznete v referenci konfigurace pokrytí kódu.

Výkon pokrytí kódu

Pokud je měření pokrytí kódu ve vašem projektu pomalé, podívejte se na Profilování výkonu testů | Pokrytí kódu.

Vitest UI

Zprávu o pokrytí kódu si můžete zkontrolovat v Vitest UI.

Vitest UI povolí zprávu o pokrytí kódu, pokud je explicitně povolena a je přítomen html reportér pokrytí, jinak nebude k dispozici:

• povolte coverage.enabled=true ve vašem konfiguračním souboru nebo spusťte Vitest s příznakem --coverage.enabled=true
• přidejte html do seznamu coverage.reporter: můžete také povolit možnost subdir pro umístění zprávy o pokrytí do podadresáře