Cobertura

O Vitest oferece suporte à cobertura de código nativa via v8 e à cobertura de código instrumentada via istanbul.

Provedores de Cobertura

O suporte para v8 e istanbul é opcional. Por padrão, v8 será utilizado.

Você pode selecionar a ferramenta de cobertura definindo test.coverage.provider como v8 ou istanbul:

import { defineConfig } from 'vitest/config';

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

Ao iniciar o processo do Vitest, ele solicitará a instalação automática do pacote de suporte correspondente.

Ou, se preferir instalá-los manualmente:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Provedor V8

INFO

A descrição da cobertura V8 abaixo é específica do Vitest e não se aplica a outros executores de testes. Desde a v3.2.0, o Vitest utiliza o remapeamento de cobertura baseado em AST para cobertura V8, o que produz relatórios de cobertura idênticos aos do Istanbul.

Isso permite que os usuários tenham a velocidade da cobertura V8 com a precisão da cobertura Istanbul.

Por padrão, o Vitest utiliza o provedor de cobertura 'v8'. Este provedor requer um ambiente de execução Javascript que seja implementado sobre o motor V8, como NodeJS, Deno ou qualquer navegador baseado em Chromium, como o Google Chrome.

A coleta de cobertura é realizada em tempo de execução, instruindo o V8 usando node:inspector e o Chrome DevTools Protocol em navegadores. Os arquivos de origem do usuário podem ser executados como estão, sem nenhuma etapa de pré-instrumentação.

• ✅ Opção recomendada para uso
• ✅ Nenhuma etapa de pré-transpilação. Os arquivos de teste podem ser executados como estão.
• ✅ Tempos de execução mais rápidos que o Istanbul.
• ✅ Menor uso de memória que o Istanbul.
• ✅ A precisão do relatório de cobertura é tão boa quanto com o Istanbul (desde o Vitest v3.2.0).
• ⚠️ Em alguns casos, pode ser mais lento que o Istanbul, por exemplo, ao carregar muitos módulos diferentes. O V8 não suporta a limitação da coleta de cobertura a módulos específicos.
• ⚠️ Existem algumas pequenas limitações definidas pelo motor V8. Veja ast-v8-to-istanbul | Limitações.
• ❌ Não funciona em ambientes que não utilizam V8, como Firefox ou Bun, ou em ambientes que não expõem a cobertura V8 via profiler, como Cloudflare Workers.

Provedor Istanbul

A ferramenta de cobertura de código Istanbul existe desde 2012 e é muito bem testada e comprovada. Este provedor funciona em qualquer ambiente de execução Javascript, pois o rastreamento de cobertura é feito instrumentando os arquivos de origem do usuário.

Na prática, instrumentar arquivos de origem significa adicionar código Javascript adicional aos arquivos do usuário:

// Exemplo simplificado de contadores de cobertura de ramificação e função
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // A cobertura de função aumenta quando esta é invocada
  coverage.functions['1']++; 

  if (id == null) {
    // A cobertura de ramificação aumenta quando esta é invocada
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // A cobertura implícita do 'else' aumenta quando a condição da instrução 'if' não é atendida
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Funciona em qualquer ambiente de execução Javascript
• ✅ Amplamente utilizado e comprovado por mais de 13 anos.
• ✅ Em alguns casos, mais rápido que o V8. A instrumentação de cobertura pode ser limitada a arquivos específicos, ao contrário do V8, onde todos os módulos são instrumentados.
• ❌ Requer etapa de pré-instrumentação
• ❌ A velocidade de execução é mais lenta que com V8 devido à sobrecarga de instrumentação
• ❌ A instrumentação aumenta o tamanho dos arquivos
• ❌ O uso de memória é maior que com V8

Configuração de Cobertura

TIP

É recomendado sempre definir coverage.include no seu arquivo de configuração. Isso ajuda o Vitest a reduzir a quantidade de arquivos selecionados por coverage.all.

Para testar com cobertura habilitada, você pode passar a opção --coverage na CLI. Por padrão, o relator ['text', 'html', 'clover', 'json'] será utilizado.

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

Para configurá-lo, defina as opções test.coverage no seu arquivo de configuração:

import { defineConfig } from 'vitest/config';

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

Relator de Cobertura Personalizado

Você pode usar relatores de cobertura personalizados passando o nome do pacote ou o caminho absoluto em test.coverage.reporter:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Especificar relator usando o nome do pacote NPM
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Especificar relator usando caminho local
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Os relatores personalizados são carregados pelo Istanbul e devem corresponder à sua interface de relator. Veja a implementação dos relatores embutidos para referência.

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

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

    // As opções passadas da configuração estão disponíveis aqui
    this.file = opts.file;
  }

  onStart(root, context) {
    this.contentWriter = context.writer.writeFile(this.file);
    this.contentWriter.println('Início do relatório de cobertura personalizado');
  }

  onEnd() {
    this.contentWriter.println('Fim do relatório de cobertura personalizado');
    this.contentWriter.close();
  }
};

Provedor de Cobertura Personalizado

Também é possível fornecer seu provedor de cobertura personalizado passando 'custom' em test.coverage.provider:

import { defineConfig } from 'vitest/config';

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

Os provedores personalizados exigem uma opção customProviderModule que é um nome de módulo ou caminho de onde carregar o CoverageProviderModule. Ele deve exportar um objeto que implementa CoverageProviderModule como exportação padrão:

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

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

  // Implementa o restante do CoverageProviderModule ...
};

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

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

  // Implementa o restante do CoverageProvider ...
}

export default CustomCoverageProviderModule;

Por favor, consulte a definição de tipo para mais detalhes.

Alterando o Local da Pasta de Cobertura Padrão

Ao executar um relatório de cobertura, uma pasta coverage é criada no diretório raiz do seu projeto. Se você quiser movê-la para um diretório diferente, use a propriedade test.coverage.reportsDirectory no arquivo vitest.config.js.

import { defineConfig } from 'vite';

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

Ignorando Código

Ambos os provedores de cobertura têm suas próprias maneiras de ignorar código dos relatórios de cobertura:

• v8
• ìstanbul
• v8 com experimentalAstAwareRemapping: true veja ast-v8-to-istanbul | Ignorando código

Ao usar TypeScript, os códigos-fonte são transpilados usando esbuild, que remove todos os comentários dos códigos-fonte (esbuild#516). Comentários que são considerados comentários legais são mantidos.

Você pode incluir a palavra-chave @preserve na dica de ignorar. Cuidado: essas dicas de ignorar também podem ser incluídas na compilação de produção final.

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

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

Outras Opções

Para ver todas as opções configuráveis para cobertura, consulte a Referência de Configuração de Cobertura.

Desempenho da Cobertura

Se a geração de cobertura de código estiver lenta em seu projeto, consulte Analisando o Desempenho dos Testes | Cobertura de código.

Vitest UI

Você pode verificar seu relatório de cobertura na interface do Vitest.

A interface do Vitest habilitará o relatório de cobertura quando ele estiver explicitamente habilitado e o relator de cobertura HTML estiver presente; caso contrário, não estará disponível:

• habilite coverage.enabled=true no seu arquivo de configuração ou execute o Vitest com a opção --coverage.enabled=true
• adicione html à lista coverage.reporter; você também pode habilitar a opção subdir para colocar o relatório de cobertura em um subdiretório