Copertura

Vitest supporta la copertura del codice nativa tramite v8 e la copertura del codice strumentato tramite istanbul.

Provider di Copertura

Il supporto sia per v8 che per istanbul è opzionale. Per impostazione predefinita, Vitest utilizzerà v8.

È possibile selezionare lo strumento di copertura impostando test.coverage.provider su v8 o istanbul:

import { defineConfig } from 'vitest/config';

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

All'avvio del processo Vitest, verrà richiesto di installare automaticamente il pacchetto di supporto corrispondente.

In alternativa, se si preferisce installarli manualmente:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Provider V8

INFO

La descrizione della copertura V8 di seguito è specifica di Vitest e non si applica ad altri test runner. Dalla versione v3.2.0, Vitest utilizza il remapping della copertura basato su AST per la copertura V8, producendo report di copertura identici a Istanbul.

Ciò consente agli utenti di beneficiare della velocità della copertura V8 con la precisione della copertura Istanbul.

Per impostazione predefinita, Vitest utilizza il provider di copertura 'v8'. Questo provider richiede un runtime Javascript implementato sul motore V8, come NodeJS, Deno o qualsiasi browser basato su Chromium (ad esempio, Google Chrome).

La raccolta della copertura viene eseguita durante il runtime, istruendo V8 tramite node:inspector e il Chrome DevTools Protocol nei browser. I file sorgente dell'utente possono essere eseguiti senza alcun passaggio di pre-strumentazione.

• ✅ Opzione consigliata
• ✅ Nessun passaggio di pre-strumentazione. I file di test possono essere eseguiti così come sono.
• ✅ Tempi di esecuzione più rapidi rispetto a Istanbul.
• ✅ Minore consumo di memoria rispetto a Istanbul.
• ✅ La precisione del report di copertura è equivalente a quella di Istanbul (dalla versione Vitest v3.2.0).
• ⚠️ In alcuni casi può essere più lento di Istanbul, ad esempio quando si caricano molti moduli diversi. V8 non supporta la limitazione della raccolta della copertura a moduli specifici.
• ⚠️ Esistono alcune piccole limitazioni imposte dal motore V8. Vedere ast-v8-to-istanbul | Limitations.
• ❌ Non funziona su ambienti che non utilizzano V8, come Firefox o Bun, o su ambienti che non espongono la copertura V8 tramite profiler, come Cloudflare Workers.

Provider Istanbul

Gli strumenti di copertura del codice Istanbul esistono dal 2012 e sono ampiamente collaudati. Questo provider funziona su qualsiasi runtime Javascript poiché il tracciamento della copertura viene eseguito strumentando i file sorgente dell'utente.

In pratica, strumentare i file sorgente significa aggiungere codice Javascript aggiuntivo nei file dell'utente:

// Esempio semplificato di contatori di copertura di rami e funzioni
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // La copertura della funzione viene incrementata quando questa viene invocata
  coverage.functions['1']++; 

  if (id == null) {
    // La copertura del ramo viene incrementata quando questa viene invocata
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // La copertura implicita dell'else aumenta quando la condizione dell'istruzione if non è verificata
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Funziona su qualsiasi runtime Javascript.
• ✅ Ampiamente utilizzato e collaudato da oltre 13 anni.
• ✅ In alcuni casi più veloce di V8. La strumentazione della copertura può essere limitata a file specifici, a differenza di V8 dove tutti i moduli sono strumentati.
• ❌ Richiede un passaggio di pre-strumentazione.
• ❌ La velocità di esecuzione è più lenta di V8 a causa dell'overhead dovuto alla strumentazione.
• ❌ La strumentazione aumenta le dimensioni dei file.
• ❌ L'utilizzo della memoria è superiore a V8.

Configurazione della Copertura

TIP

È consigliabile definire sempre coverage.include nel file di configurazione. Questo aiuta Vitest a ridurre il numero di file selezionati da coverage.all.

Per eseguire i test con la copertura abilitata, è possibile utilizzare il flag --coverage nella CLI. Per impostazione predefinita, verranno utilizzati i reporter ['text', 'html', 'clover', 'json'].

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

Per configurarlo, impostare le opzioni test.coverage nel file di configurazione:

import { defineConfig } from 'vitest/config';

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

Reporter di Copertura Personalizzato

È possibile utilizzare reporter di copertura personalizzati passando il nome del pacchetto o il percorso assoluto in test.coverage.reporter:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Specifica il reporter usando il nome del pacchetto NPM
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Specifica il reporter usando il percorso locale
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

I reporter personalizzati vengono caricati da Istanbul e devono implementare la sua interfaccia di reporter. Vedere l'implementazione dei reporter integrati per riferimento.

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

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

    // Le opzioni passate tramite configurazione sono disponibili qui
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Inizio del report di copertura personalizzato.');
  }

  onEnd() {
    this.contentWriter.println('Fine del report di copertura personalizzato.');
    this.contentWriter.close();
  }
};

Provider di Copertura Personalizzato

È anche possibile fornire il proprio provider di copertura personalizzato passando 'custom' in test.coverage.provider:

import { defineConfig } from 'vitest/config';

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

I provider personalizzati richiedono un'opzione customProviderModule che è un nome di modulo o un percorso da cui caricare il CoverageProviderModule. Deve esportare un oggetto che implementa CoverageProviderModule come esportazione predefinita:

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

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

  // Implementa la parte restante di CoverageProviderModule ...
};

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

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

  // Implementa il resto di CoverageProvider ...
}

export default CustomCoverageProviderModule;

Per maggiori dettagli, fare riferimento alla definizione del tipo.

Modifica della Posizione Predefinita della Cartella di Copertura

Quando si genera un report di copertura, viene creata una cartella coverage nella directory principale del progetto. Se si desidera spostarla in una directory diversa, utilizzare la proprietà test.coverage.reportsDirectory nel file vitest.config.js.

import { defineConfig } from 'vite';

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

Ignorare il Codice

Entrambi i provider di copertura hanno i propri metodi per ignorare il codice dai report di copertura:

• v8
• ìstanbul
• v8 con experimentalAstAwareRemapping: true vedere ast-v8-to-istanbul | Ignoring code

Quando si usa TypeScript, il codice sorgente viene trasformato usando esbuild, che rimuove tutti i commenti dal codice sorgente (esbuild#516). I commenti considerati commenti legali vengono mantenuti.

È possibile includere una parola chiave @preserve nel suggerimento per ignorare. Si noti che questi suggerimenti per ignorare potrebbero ora essere inclusi anche nella build di produzione finale.

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

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

Altre Opzioni

Per vedere tutte le opzioni configurabili per la copertura, consultare il Riferimento alla Configurazione della Copertura.

Prestazioni della Copertura

Se la generazione della copertura del codice è lenta nel tuo progetto, consulta Profilazione delle Prestazioni dei Test | Copertura del codice.

Vitest UI

È possibile visualizzare il report di copertura in Vitest UI.

Vitest UI abiliterà il report di copertura solo se è esplicitamente abilitato e il reporter di copertura HTML è presente; altrimenti, non sarà disponibile:

• abilita coverage.enabled=true nel file di configurazione o esegui Vitest con il flag --coverage.enabled=true
• aggiungi html all'elenco coverage.reporter: è anche possibile abilitare l'opzione subdir per inserire il report di copertura in una sottodirectory