Couverture

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

Fournisseurs de couverture

TIP

Depuis Vitest v0.22.0

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 :

// vitest.config.ts
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 :

# Pour v8
npm i -D @vitest/coverage-v8

# Pour istanbul
npm i -D @vitest/coverage-istanbul

Configuration de la couverture

TIP

Il est recommandé de toujours définir coverage.include dans votre fichier de configuration. Cela aide Vitest à réduire le nombre de fichiers sélectionnés par coverage.all.

Pour exécuter les tests avec la couverture activée, vous pouvez utiliser l'option --coverage dans la CLI. Par défaut, les rapporteurs ['text', 'html', 'clover', 'json'] sont utilisés.

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

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

// vitest.config.ts
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 passant 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écifiez le rapporteur à l'aide du nom du package NPM
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Spécifiez le rapporteur à l'aide du chemin local
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

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

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

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

    // Les options transmises à partir de la configuration sont disponibles ici
    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();
  }
};

Fournisseur de couverture personnalisé

Vous pouvez également fournir votre propre fournisseur de couverture personnalisé en définissant test.coverage.provider sur 'custom' :

// vitest.config.ts
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 un nom de module ou un chemin d'accès où charger le CoverageProviderModule. Ce module doit exporter un objet qui implémente CoverageProviderModule en tant qu'exportation par défaut :

// my-custom-coverage-provider.ts
import type {
  CoverageProvider,
  CoverageProviderModule,
  ResolvedCoverageOptions,
  Vitest,
} from 'vitest';

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

  // Voir l'implémentation complète de CoverageProviderModule...
};

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

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

  // Voir l'implémentation complète de CoverageProvider...
}

export default CustomCoverageProviderModule;

Consultez la définition de type pour plus de détails.

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

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

import { defineConfig } from 'vite';

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

Ignorer du code

Les deux fournisseurs de couverture proposent leurs propres méthodes pour exclure du code des rapports de couverture :

• v8
• ìstanbul

Lorsque vous utilisez TypeScript, le code source est transpilé à l'aide de esbuild, qui supprime tous les commentaires du code source (esbuild#516). Les commentaires considérés comme des commentaires légaux sont conservés.

Pour le fournisseur istanbul, vous pouvez inclure le mot-clé @preserve dans l'annotation d'exclusion. Attention, ces annotations d'exclusion peuvent également être incluses dans la version de production finale.

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

Pour v8, cela ne pose aucun problème. Vous pouvez utiliser les commentaires v8 ignore avec Typescript comme d'habitude :

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

Autres options

Pour consulter toutes les options de configuration disponibles pour la couverture, consultez la Référence de configuration de la couverture.

Interface utilisateur Vitest

Depuis Vitest 0.31.0, vous pouvez consulter votre rapport de couverture dans l'interface utilisateur de Vitest.

L'interface utilisateur de Vitest affichera le rapport de couverture s'il est explicitement activé et si le rapporteur de couverture HTML est présent ; sinon, il ne sera pas disponible.

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