Code-Abdeckung

Vitest unterstützt die native Codeabdeckung über v8 und die instrumentierte Codeabdeckung über istanbul.

Coverage-Provider

Die Unterstützung für v8 und istanbul ist optional. Standardmäßig wird v8 verwendet.

Sie können das Abdeckungs-Tool auswählen, indem Sie test.coverage.provider auf v8 oder istanbul setzen:

import { defineConfig } from 'vitest/config';

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

Wenn Sie den Vitest-Prozess starten, werden Sie aufgefordert, das entsprechende Support-Paket automatisch zu installieren.

Alternativ können Sie es manuell installieren:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

V8-Provider

INFO

Die folgende Beschreibung der V8-Abdeckung ist Vitest-spezifisch und gilt nicht für andere Test-Runner. Seit v3.2.0 verwendet Vitest AST-basierte Neuzuordnung der Abdeckung für die V8-Abdeckung, die identische Abdeckungsberichte wie Istanbul erzeugt.

Dies ermöglicht Benutzern die Geschwindigkeit der V8-Abdeckung bei gleichzeitiger Genauigkeit der Istanbul-Abdeckung.

Standardmäßig verwendet Vitest den 'v8'-Abdeckungsprovider. Dieser Provider erfordert eine JavaScript-Laufzeitumgebung, die auf der V8-Engine implementiert ist, wie z.B. NodeJS, Deno oder beliebige Chromium-basierte Browser wie Google Chrome.

Die Abdeckungserfassung erfolgt zur Laufzeit, indem V8 in Browsern über node:inspector und das Chrome DevTools Protocol instruiert wird. Die Quelldateien des Benutzers können ohne vorherige Instrumentierungsschritte ausgeführt werden.

• ✅ Empfohlene Option
• ✅ Kein vorheriger Transpilationsschritt erforderlich. Testdateien können unverändert ausgeführt werden.
• ✅ Schnellere Ausführungszeiten als Istanbul.
• ✅ Geringerer Speicherverbrauch als bei Istanbul.
• ✅ Die Genauigkeit des Abdeckungsberichts ist ebenso gut wie bei Istanbul (seit Vitest v3.2.0).
• ⚠️ In einigen Fällen kann der V8-Provider langsamer sein als Istanbul, z.B. beim Laden vieler verschiedener Module. V8 ermöglicht keine Begrenzung der Abdeckungserfassung auf bestimmte Module.
• ⚠️ Es gibt einige geringfügige Einschränkungen durch die V8-Engine. Siehe ast-v8-to-istanbul | Limitations.
• ❌ Funktioniert nicht in Umgebungen, die V8 nicht verwenden, wie Firefox oder Bun. Oder in Umgebungen, die keine V8-Abdeckung über den Profiler bereitstellen, wie Cloudflare Workers.

Istanbul-Provider

Das Istanbul Code-Abdeckungs-Tooling existiert seit 2012 und ist sehr gut erprobt. Dieser Provider funktioniert auf jeder JavaScript-Laufzeitumgebung, da die Abdeckungsverfolgung durch Instrumentierung der Quelldateien des Benutzers erfolgt.

In der Praxis bedeutet die Instrumentierung von Quelldateien das Hinzufügen von zusätzlichem JavaScript in den Dateien des Benutzers:

// Vereinfachtes Beispiel für Branch- und Funktionsabdeckungszähler
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // Funktionsabdeckung wird erhöht, wenn diese aufgerufen wird
  coverage.functions['1']++; 

  if (id == null) {
    // Branch-Abdeckung wird erhöht, wenn diese aufgerufen wird
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // Implizite Else-Zweig-Abdeckung wird erhöht, wenn die If-Anweisung nicht erfüllt ist
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Funktioniert auf jeder JavaScript-Laufzeitumgebung
• ✅ Weit verbreitet und seit über 13 Jahren erprobt.
• ✅ In einigen Fällen schneller als V8. Die Abdeckungsinstrumentierung kann auf bestimmte Dateien beschränkt werden, im Gegensatz zu V8, bei dem alle Module instrumentiert werden.
• ❌ Erfordert einen vorherigen Instrumentierungsschritt
• ❌ Die Ausführungsgeschwindigkeit ist aufgrund des Instrumentierungs-Overheads langsamer als bei V8
• ❌ Die Instrumentierung erhöht die Dateigrößen
• ❌ Der Speicherverbrauch ist höher als bei V8.

Abdeckungs-Setup

TIP

Es wird empfohlen, coverage.include in Ihrer Konfigurationsdatei stets zu definieren. Dies hilft Vitest, die Anzahl der von coverage.all erfassten Dateien zu reduzieren.

Um mit aktivierter Abdeckung zu testen, können Sie das --coverage-Flag in der CLI übergeben. Standardmäßig werden die Reporter ['text', 'html', 'clover', 'json'] verwendet.

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

Um dies zu konfigurieren, passen Sie die test.coverage-Optionen in Ihrer Konfigurationsdatei an:

import { defineConfig } from 'vitest/config';

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

Benutzerdefinierter Abdeckungsreporter

Sie können benutzerdefinierte Abdeckungsreporter verwenden, indem Sie entweder den Namen des Pakets oder den absoluten Pfad in test.coverage.reporter angeben:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Reporter über den Namen des NPM-Pakets angeben
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Reporter über lokalen Pfad angeben
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Benutzerdefinierte Reporter werden von Istanbul geladen und müssen der Reporter-Schnittstelle von Istanbul entsprechen. Siehe die Implementierung der integrierten Reporter als Referenz.

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

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

    // Optionen, die aus der Konfiguration übergeben wurden, sind hier verfügbar.
    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();
  }
};

Benutzerdefinierter Abdeckungsprovider

Es ist auch möglich, einen benutzerdefinierten Abdeckungsprovider bereitzustellen, indem Sie 'custom' in test.coverage.provider übergeben:

import { defineConfig } from 'vitest/config';

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

Benutzerdefinierte Provider erfordern eine customProviderModule-Option, die ein Modulname oder Pfad ist, von dem die CoverageProviderModule geladen werden soll. Sie muss ein Objekt exportieren, das CoverageProviderModule als Standardexport implementiert:

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

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

  // Implementiert den Rest des CoverageProviderModule...
};

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

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

  // Implementiert den Rest des CoverageProvider...
}

export default CustomCoverageProviderModule;

Weitere Details entnehmen Sie bitte der Typdefinition.

Ändern des Standard-Speicherorts des Abdeckungsordners

Beim Ausführen eines Abdeckungsberichts wird ein coverage-Ordner im Stammverzeichnis Ihres Projekts erstellt. Wenn Sie ihn in ein anderes Verzeichnis verschieben möchten, verwenden Sie die Eigenschaft test.coverage.reportsDirectory in der Datei vitest.config.js.

import { defineConfig } from 'vite';

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

Code ignorieren

Beide Abdeckungsprovider haben ihre eigenen Möglichkeiten, Code aus Abdeckungsberichten auszuschließen:

• v8
• ìstanbul
• v8 mit experimentalAstAwareRemapping: true siehe ast-v8-to-istanbul | Ignoring code

Bei der Verwendung von TypeScript werden die Quelldateien mit esbuild transpiliert, wodurch alle Kommentare aus den Quelldateien entfernt werden (esbuild#516). Kommentare, die als zulässige Kommentare gelten, bleiben erhalten.

Sie können ein @preserve-Schlüsselwort in den Ignorierhinweis hinzufügen. Bitte beachten Sie, dass diese Ignorierhinweise nun auch im endgültigen Produktions-Build enthalten sein können.

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

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

Weitere Optionen

Alle konfigurierbaren Optionen für die Abdeckung finden Sie in der Abdeckungs-Konfigurationsreferenz.

Abdeckungs-Performance

Wenn die Generierung der Codeabdeckung in Ihrem Projekt langsam ist, siehe Test-Performance analysieren | Codeabdeckung.

Vitest UI

Sie können Ihren Abdeckungsbericht in der Vitest UI überprüfen.

Die Vitest UI aktiviert den Abdeckungsbericht, wenn dieser explizit aktiviert ist und der HTML-Abdeckungsreporter vorhanden ist; andernfalls ist er nicht verfügbar:

• Aktivieren Sie coverage.enabled=true in Ihrer Konfigurationsdatei oder führen Sie Vitest mit dem Flag --coverage.enabled=true aus.
• Fügen Sie html zur Liste coverage.reporter hinzu. Sie können auch die Option subdir aktivieren, um den Abdeckungsbericht in einem Unterverzeichnis abzulegen.