Couverture de code

Vitest prend en charge la couverture de code native via v8 et la couverture de code instrumentée via istanbul.

Fournisseurs de couverture

La prise en charge de v8 et istanbul est optionnelle. Par défaut, v8 est utilisé.

Vous pouvez sélectionner l'outil de couverture en définissant test.coverage.provider sur 'v8' ou 'istanbul' :

import { defineConfig } from 'vitest/config';

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

Lorsque vous lancez Vitest, il vous proposera d'installer automatiquement le package de support correspondant.

Ou si vous préférez les installer manuellement :

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Fournisseur V8

INFO

La description de la couverture V8 ci-dessous est spécifique à Vitest et ne s'applique pas aux autres lanceurs de tests. Depuis la version v3.2.0, Vitest utilise le remapping de couverture basé sur l'AST pour la couverture V8, ce qui produit des rapports de couverture identiques à Istanbul.

Cela permet aux utilisateurs de bénéficier de la vitesse de la couverture V8 avec la précision de la couverture Istanbul.

Par défaut, Vitest utilise le fournisseur de couverture 'v8'. Ce fournisseur nécessite un runtime JavaScript basé sur le moteur V8, tel que NodeJS, Deno ou tout navigateur basé sur Chromium comme Google Chrome.

La collecte de couverture s'effectue pendant l'exécution en interrogeant V8 à l'aide de node:inspector et du Protocole Chrome DevTools dans les navigateurs. Les fichiers source de l'utilisateur peuvent être exécutés directement sans aucune étape de pré-instrumentation.

• ✅ Option recommandée
• ✅ Pas d'étape de pré-transpilation. Les fichiers de test peuvent être exécutés tels quels.
• ✅ Exécution plus rapide qu'Istanbul.
• ✅ Consommation de mémoire inférieure à celle d'Istanbul.
• ✅ La précision du rapport de couverture est aussi bonne qu'avec Istanbul (depuis Vitest v3.2.0).
• ⚠️ Dans certains cas, il peut être plus lent qu'Istanbul, par exemple lors du chargement de nombreux modules différents. V8 ne prend pas en charge la limitation de la collecte de couverture à des modules spécifiques.
• ⚠️ Il y a quelques limitations mineures du moteur V8. Voir ast-v8-to-istanbul | Limitations.
• ❌ Ne fonctionne pas sur les environnements qui n'utilisent pas V8 (tels que Firefox ou Bun) ou qui n'exposent pas la couverture V8 via le profileur (tels que Cloudflare Workers).

Fournisseur Istanbul

L'outil de couverture de code Istanbul existe depuis 2012 et a largement fait ses preuves. Ce fournisseur fonctionne sur n'importe quel runtime JavaScript car le suivi de la couverture est effectué en instrumentant les fichiers source de l'utilisateur.

En pratique, l'instrumentation des fichiers source consiste à ajouter du JavaScript supplémentaire dans les fichiers de l'utilisateur :

// Exemple simplifié de compteurs de couverture de branche et de fonction
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // La couverture de fonction augmente lorsque cette fonction est appelée
  coverage.functions['1']++; 

  if (id == null) {
    // La couverture de branche augmente lorsque cette branche est exécutée
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // La couverture implicite du else augmente lorsque la condition du if n'est pas remplie
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Fonctionne sur n'importe quel runtime JavaScript
• ✅ Largement utilisé et éprouvé depuis plus de 13 ans.
• ✅ Dans certains cas, plus rapide que V8. L'instrumentation de la couverture peut être limitée à des fichiers spécifiques, contrairement à V8 où tous les modules sont instrumentés.
• ❌ Nécessite une étape de pré-instrumentation
• ❌ L'exécution est plus lente que V8 en raison du surcoût d'instrumentation
• ❌ L'instrumentation augmente la taille des fichiers
• ❌ L'utilisation de la mémoire est plus élevée que celle de V8

Configuration de la couverture

TIP

Il est recommandé de toujours spécifier coverage.include dans votre fichier de configuration. Cela aide Vitest à réduire le nombre de fichiers pris en compte par coverage.all.

Pour effectuer les tests avec la couverture activée, vous pouvez passer le drapeau --coverage dans la CLI. Par défaut, les rapporteurs ['text', 'html', 'clover', 'json'] seront utilisés.

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

Pour le configurer, définissez les options test.coverage dans votre fichier de configuration :

import { defineConfig } from 'vitest/config';

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

Rapporteur de couverture personnalisé

Vous pouvez utiliser des rapporteurs de couverture personnalisés en spécifiant soit le nom du package, soit le chemin absolu dans test.coverage.reporter :

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Spécifier le rapporteur en utilisant le nom du package NPM
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Spécifier le rapporteur en utilisant un chemin local
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Les rapporteurs personnalisés sont chargés par Istanbul et doivent correspondre à son interface de rapporteur. Voir l'implémentation des rapporteurs intégrés pour référence.

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

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

    // Les options définies dans la configuration sont disponibles ici
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Début du rapport de couverture personnalisé');
  }

  onEnd() {
    this.contentWriter.println('Fin du rapport de couverture personnalisé');
    this.contentWriter.close();
  }
};

Fournisseur de couverture personnalisé

Il est également possible de fournir votre propre fournisseur de couverture personnalisé en définissant 'custom' dans test.coverage.provider :

import { defineConfig } from 'vitest/config';

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

Les fournisseurs personnalisés nécessitent une option customProviderModule, qui est le nom ou le chemin du module à partir duquel charger le CoverageProviderModule. Il doit exporter un objet implémentant CoverageProviderModule comme exportation par défaut :

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

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

  // Implémente le reste du CoverageProviderModule ...
};

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

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

  // Implémente le reste du CoverageProvider ...
}

export default CustomCoverageProviderModule;

Veuillez vous référer à la définition de type pour plus de précisions.

Changer l'emplacement du dossier de couverture par défaut

Lors de la génération d'un rapport de couverture, un dossier coverage est créé dans le répertoire racine de votre projet. Si vous souhaitez le déplacer vers un autre dossier, utilisez la propriété test.coverage.reportsDirectory dans le fichier vitest.config.js.

import { defineConfig } from 'vite';

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

Ignorer le code

Les deux fournisseurs de couverture disposent de leurs propres méthodes pour ignorer le code des rapports de couverture :

• v8
• ìstanbul
• v8 avec experimentalAstAwareRemapping: true voir ast-v8-to-istanbul | Ignoring code

Lors de l'utilisation de TypeScript, le code source est transpilé à l'aide de esbuild, ce qui supprime tous les commentaires (esbuild#516). Seuls les commentaires légaux sont conservés.

Vous pouvez inclure un mot-clé @preserve dans la directive d'ignorance. Sachez que ces directives d'ignorance peuvent désormais être incluses également dans la version de production finale.

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

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

Autres options

Pour consulter toutes les options de configuration de la couverture, voir la Référence de configuration de la couverture.

Performances de la couverture

Si le calcul de la couverture de code est lent dans votre projet, consultez Profilage des performances des tests | Couverture de code.

Interface utilisateur de Vitest

Vous pouvez consulter votre rapport de couverture dans l'interface utilisateur de Vitest.

L'interface utilisateur de Vitest affichera le rapport de couverture si celui-ci est explicitement activé et que le rapporteur de couverture HTML est configuré ; sinon, il ne sera pas disponible :

• activez coverage.enabled=true dans votre fichier de configuration ou exécutez Vitest avec le drapeau --coverage.enabled=true
• ajoutez html à la liste coverage.reporter : vous pouvez également activer l'option subdir afin de placer le rapport de couverture dans un sous-répertoire