Codeabdeckung (Coverage)

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

Abdeckungsanbieter

TIP

Verfügbar seit Vitest v0.22.0

Sowohl v8 als auch istanbul sind optionale Abhängigkeiten. Standardmäßig wird der v8-Provider verwendet.

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

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

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

Beim ersten Start von Vitest mit aktivierter Codeabdeckung werden Sie automatisch aufgefordert, das entsprechende Paket zu installieren.

Alternativ können Sie diese auch manuell installieren:

# Für v8
npm i -D @vitest/coverage-v8

# Für istanbul
npm i -D @vitest/coverage-istanbul

Konfiguration der Codeabdeckung

TIP

Es wird empfohlen, immer coverage.include in Ihrer Konfigurationsdatei zu definieren. Dies hilft Vitest, die Anzahl der von coverage.all ausgewählten Dateien zu reduzieren.

Um Tests mit aktivierter Codeabdeckung auszuführen, verwenden Sie das Flag --coverage in der CLI. Standardmäßig werden die Reporter ['text', 'html', 'clover', 'json'] verwendet.

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

Um dies zu konfigurieren, setzen Sie die Option test.coverage in Ihrer Konfigurationsdatei.

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

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

Benutzerdefinierter Coverage-Reporter

Sie können benutzerdefinierte Coverage-Reporter verwenden, indem Sie entweder den Namen des Pakets oder den absoluten Pfad in test.coverage.reporter übergeben:

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 den lokalen Pfad angeben
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Benutzerdefinierte Reporter werden von Istanbul geladen und müssen mit dessen Reporter-Schnittstelle übereinstimmen. Eine Referenz finden Sie in der Implementierung integrierter Reporter.

// custom-reporter.cjs
const { ReportBase } = require('istanbul-lib-report');

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

    // Hier sind die aus der Konfiguration übergebenen Optionen 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 Coverage-Anbieter

Sie können auch einen eigenen Coverage-Anbieter bereitstellen, indem Sie 'custom' in test.coverage.provider angeben:

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

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

Benutzerdefinierte Anbieter benötigen die Option customProviderModule, die einen Modulnamen oder -pfad angibt, von dem das CoverageProviderModule geladen wird. Es muss ein Objekt exportiert werden, das das Interface CoverageProviderModule als Standardexport implementiert:

// my-custom-coverage-provider.ts
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 Informationen finden Sie in der Typdefinition.

Ändern des Standard-Speicherorts für den Coverage-Ordner

Standardmäßig wird der coverage-Ordner im Stammverzeichnis Ihres Projekts erstellt, wenn Sie einen Coverage-Bericht ausführen. Um ihn in ein anderes Verzeichnis zu verschieben, verwenden Sie die Eigenschaft test.coverage.reportsDirectory in der Datei vite.config.js.

import { defineConfig } from 'vite';

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

Code ignorieren

Beide Coverage-Anbieter bieten verschiedene Möglichkeiten, um Code in Coverage-Berichten auszuschließen:

• v8
• istanbul

Bei Verwendung von TypeScript werden die Quellcodes mit esbuild transpiliert, wodurch alle Kommentare aus den Quellcodes entfernt werden (esbuild#516). Kommentare, die als legale Kommentare gelten, bleiben erhalten.

Für den istanbul-Anbieter können Sie das Schlüsselwort @preserve in den Ignore-Hinweis aufnehmen. Beachten Sie, dass diese Ignore-Hinweise auch im endgültigen Produktions-Build enthalten sein können.

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

Für v8 entstehen dadurch keine Probleme. Sie können v8 ignore-Kommentare wie gewohnt in Typescript verwenden:

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

Weitere Optionen

Eine vollständige Liste der konfigurierbaren Optionen für die Codeabdeckung finden Sie in der Coverage-Konfigurationsreferenz.

Vitest UI

Seit Vitest 0.31.0 können Sie Ihren Coverage-Bericht in der Vitest UI einsehen.

Die Vitest UI zeigt den Coverage-Bericht an, wenn dieser explizit aktiviert wurde und der HTML-Coverage-Reporter vorhanden ist. Andernfalls ist er nicht verfügbar:

• Aktivieren Sie coverage.enabled=true in Ihrer Konfiguration oder führen Sie Vitest mit dem Flag --coverage.enabled=true aus.
• Fügen Sie html zur coverage.reporter-Liste hinzu. Optional können Sie die Option subdir aktivieren, um den Coverage-Bericht in einem Unterverzeichnis zu speichern.