Cobertura

Vitest ofrece soporte para la cobertura de código nativa a través de v8 y la cobertura de código instrumentada mediante istanbul.

Proveedores de Cobertura

El soporte para v8 e istanbul es opcional. Por defecto, se utilizará v8.

Puedes seleccionar la herramienta de cobertura configurando test.coverage.provider a v8 o istanbul:

import { defineConfig } from 'vitest/config';

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

Al iniciar el proceso de Vitest, se te solicitará instalar automáticamente el paquete de soporte correspondiente.

Alternativamente, puedes instalarlos manualmente:

v8

npm i -D @vitest/coverage-v8

istanbul

npm i -D @vitest/coverage-istanbul

Proveedor V8

INFO

La siguiente descripción de la cobertura V8 es específica de Vitest y no se aplica a otros ejecutores de pruebas. Desde la v3.2.0, Vitest ha implementado el remapeo de cobertura basado en AST para la cobertura V8, lo que genera informes de cobertura idénticos a los de Istanbul.

Esto permite a los usuarios beneficiarse de la velocidad de la cobertura V8 con la precisión de la cobertura Istanbul.

Por defecto, Vitest utiliza el proveedor de cobertura 'v8'. Este proveedor requiere un entorno de ejecución de Javascript implementado sobre el motor V8, como NodeJS, Deno o cualquier navegador basado en Chromium (ej. Google Chrome).

La recolección de cobertura se realiza durante el tiempo de ejecución, instruyendo a V8 a través de node:inspector y el Protocolo de Herramientas de Desarrollo de Chrome en los navegadores. Los archivos fuente del usuario pueden ejecutarse directamente sin necesidad de un paso de pre-instrumentación.

• ✅ Opción recomendada.
• ✅ No requiere paso de pre-transpilación. Los archivos de prueba se ejecutan tal cual.
• ✅ Ejecución más rápida que con Istanbul.
• ✅ Menor uso de memoria que con Istanbul.
• ✅ Precisión del informe de cobertura comparable a la de Istanbul (desde Vitest v3.2.0 (ver blog)).
• ⚠️ En algunos casos, puede ser más lento que Istanbul, por ejemplo, al cargar muchos módulos diferentes. V8 no permite limitar la recolección de cobertura a módulos específicos.
• ⚠️ Existen algunas limitaciones menores impuestas por el motor V8. Consulta ast-v8-to-istanbul | Limitaciones.
• ❌ No funciona en entornos que no utilizan V8, como Firefox o Bun, o en entornos que no ofrecen cobertura V8 a través del perfilador, como Cloudflare Workers.

Proveedor Istanbul

Las herramientas de cobertura de código de Istanbul existen desde 2012 y han demostrado su robustez. Este proveedor funciona en cualquier entorno de ejecución de Javascript, ya que el seguimiento de la cobertura se realiza instrumentando los archivos fuente del usuario.

En la práctica, instrumentar archivos fuente implica añadir código Javascript adicional a los archivos del usuario:

// Ejemplo simplificado de contadores de cobertura de ramas y funciones
const coverage = { 
  branches: { 1: [0, 0] }, 
  functions: { 1: 0 }, 
} 

export function getUsername(id) {
  // La cobertura de la función aumenta cuando se invoca
  coverage.functions['1']++; 

  if (id == null) {
    // La cobertura de la rama aumenta cuando se invoca
    coverage.branches['1'][0]++; 

    throw new Error('User ID is required');
  }
  // La cobertura implícita del 'else' aumenta si la condición de la sentencia 'if' no se cumple
  coverage.branches['1'][1]++; 

  return database.getUser(id);
}

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

• ✅ Funciona en cualquier entorno de ejecución de Javascript.
• ✅ Ampliamente utilizado y probado en entornos reales durante más de 13 años.
• ✅ En algunos casos, es más rápido que V8. La instrumentación de cobertura puede limitarse a archivos específicos, a diferencia de V8, donde todos los módulos se instrumentan.
• ❌ Requiere un paso de pre-instrumentación.
• ❌ La velocidad de ejecución es más lenta que con V8 debido a la sobrecarga de la instrumentación.
• ❌ La instrumentación aumenta el tamaño de los archivos.
• ❌ Mayor uso de memoria que con V8.

Configuración de Cobertura

TIP

Siempre se recomienda definir coverage.include en tu archivo de configuración. Esto ayuda a Vitest a reducir la cantidad de archivos que se seleccionan por coverage.all.

Para ejecutar pruebas con la cobertura habilitada, puedes pasar la bandera --coverage en la CLI. Por defecto, se utilizarán los reporteros ['text', 'html', 'clover', 'json'].

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

Para configurarlo, establece las opciones test.coverage en tu archivo de configuración:

import { defineConfig } from 'vitest/config';

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

Reportero de Cobertura Personalizado

Puedes usar reporteros de cobertura personalizados especificando el nombre del paquete o la ruta absoluta en test.coverage.reporter:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      reporter: [
        // Especificar el reportero usando el nombre del paquete NPM
        ['@vitest/custom-coverage-reporter', { someOption: true }],

        // Especificar el reportero usando una ruta local
        '/absolute/path/to/custom-reporter.cjs',
      ],
    },
  },
});

Los reporteros personalizados son cargados por Istanbul y deben coincidir con su interfaz de reportero. Consulta la implementación de los reporteros incorporados como referencia.

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

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

    // Las opciones pasadas desde la configuración están disponibles aquí
    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();
  }
};

Proveedor de Cobertura Personalizado

También es posible proporcionar tu propio proveedor de cobertura personalizado pasando 'custom' en test.coverage.provider:

import { defineConfig } from 'vitest/config';

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

Los proveedores personalizados requieren una opción customProviderModule, que es el nombre de un módulo o una ruta desde la que cargar el CoverageProviderModule. Debe exportar un objeto que implemente CoverageProviderModule como exportación por defecto:

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

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

  // Implementa el resto de CoverageProviderModule ...
};

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

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

  // Implementa el resto de CoverageProvider ...
}

export default CustomCoverageProviderModule;

Por favor, consulta la definición de tipo para más detalles.

Cambiar la Ubicación Predeterminada de la Carpeta de Cobertura

Al generar un informe de cobertura, se crea una carpeta coverage en el directorio raíz de tu proyecto. Si deseas moverla a un directorio diferente, utiliza la propiedad test.coverage.reportsDirectory en el archivo vitest.config.js.

import { defineConfig } from 'vite';

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

Ignorar Código

Ambos proveedores de cobertura tienen sus propios métodos para ignorar código en los informes de cobertura:

• v8
• ìstanbul
• v8 con experimentalAstAwareRemapping: true ver ast-v8-to-istanbul | Ignorar código

Cuando se usa TypeScript, el código fuente se transpila usando esbuild, lo que elimina todos los comentarios (esbuild#516). Los comentarios considerados legales se conservan.

Puedes incluir la palabra clave @preserve en la directiva para ignorar. Ten en cuenta que estas directivas para ignorar pueden incluirse también en la compilación de producción final.

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

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

Otras Opciones

Para ver todas las opciones configurables para la cobertura, consulta la Referencia de Configuración de Cobertura.

Rendimiento de Cobertura

Si la generación de cobertura de código es lenta en tu proyecto, consulta Análisis de Rendimiento en Pruebas | Cobertura de código.

Vitest UI

Puedes verificar tu informe de cobertura en Vitest UI.

Vitest UI mostrará el informe de cobertura cuando este esté explícitamente habilitado y el reportero de cobertura HTML esté presente; de lo contrario, no estará disponible:

• habilita coverage.enabled=true en tu archivo de configuración o ejecuta Vitest con el flag --coverage.enabled=true
• añade html a la lista de coverage.reporter: también puedes habilitar la opción subdir para colocar el informe de cobertura en un subdirectorio