Configuración de Vitest

Si utilizas Vite y dispones de un archivo vite.config, Vitest lo leerá para alinear los plugins y la configuración con tu aplicación Vite. Si necesitas una configuración de prueba distinta o si tu aplicación principal no depende específicamente de Vite, puedes optar por las siguientes alternativas:

Crear vitest.config.ts: Este archivo tendrá mayor prioridad y anulará la configuración de vite.config.ts (Vitest es compatible con todas las extensiones convencionales de JS y TS, pero no con json). Esto implica que todas las opciones definidas en tu vite.config serán ignoradas.
Pasar la opción --config a la CLI: Por ejemplo, vitest --config ./ruta/a/vitest.config.ts.
Utilizar process.env.VITEST o la propiedad mode en defineConfig (se establecerá en test/benchmark si no se anula con --mode) para aplicar condicionalmente una configuración diferente en vite.config.ts.

Para configurar vitest directamente, añade la propiedad test en tu configuración de Vite. Además, si importas defineConfig desde vite, deberás incluir una referencia a los tipos de Vitest utilizando una directiva de triple barra en la parte superior de tu archivo de configuración.

Abrir ejemplos de configuración

Al usar defineConfig de vite, debes seguir este patrón:

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... Especifica las opciones aquí.
  },
});

La directiva <reference types="vitest" /> dejará de funcionar en Vitest 4. Sin embargo, ya puedes empezar a migrar a vitest/config:

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... Especifica las opciones aquí.
  },
});

Si utilizas defineConfig de vitest/config, el enfoque es el siguiente:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ... Especifica las opciones aquí.
  },
});

Puedes recuperar las opciones predeterminadas de Vitest para extenderlas si es necesario:

import { configDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    exclude: [...configDefaults.exclude, 'packages/template/*'],
  },
});

Al usar un vitest.config.js separado, también puedes extender las opciones de Vite desde otro archivo de configuración si es necesario:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      exclude: ['packages/template/*'],
    },
  })
);

Si tu configuración de Vite está definida como una función, puedes definir la configuración de esta manera:

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config';

export default defineConfig(configEnv =>
  mergeConfig(
    viteConfig(configEnv),
    defineConfig({
      test: {
        exclude: ['packages/template/*'],
      },
    })
  )
);

WARNING

Todas las opciones listadas en esta página se encuentran dentro de una propiedad test en la configuración:

export default defineConfig({
  test: {
    exclude: [],
  },
});

Dado que Vitest utiliza la configuración de Vite, también puedes emplear cualquier opción de configuración de Vite. Por ejemplo, define para definir variables globales, o resolve.alias para establecer alias. Estas opciones deben definirse en el nivel superior, no dentro de una propiedad test.

Las opciones de configuración que no son compatibles dentro de una configuración de proyecto se identifican con el signo *. Esto significa que solo pueden establecerse en la configuración raíz de Vitest.

include

Tipo: string[]
Predeterminado: ['**/*.{test,spec}.?(c|m)[jt]s?(x)']
CLI: vitest [...include], vitest **/*.test.js

Una lista de patrones glob que coinciden con tus archivos de prueba.

NOTA

Cuando se utiliza la cobertura, Vitest añade automáticamente los patrones include de los archivos de prueba a los patrones exclude predeterminados de la cobertura. Consulta coverage.exclude.

exclude

Tipo: string[]
Predeterminado: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**', '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*']
CLI: vitest --exclude "**/archivo-excluido"

Una lista de patrones glob que deben ser excluidos de tus archivos de prueba.

WARNING

Esta opción no afecta la cobertura. Si necesitas eliminar ciertos archivos del informe de cobertura, usa coverage.exclude.

Esta es la única opción que no anula tu configuración si la proporcionas con un parámetro CLI. Todos los patrones glob añadidos a través del parámetro --exclude se añadirán a la opción exclude de la configuración.

includeSource

Tipo: string[]
Predeterminado: []

Patrones glob a incluir para archivos de prueba en el código fuente.

Cuando se define, Vitest ejecutará todos los archivos coincidentes que contengan import.meta.vitest.

name

Tipo: string | { label: string, color?: LabelColor }

Asigna un nombre personalizado al proyecto de prueba o al proceso de Vitest. El nombre será visible en la CLI y la UI, y estará disponible en la API de Node.js a través de project.name.

El color utilizado por la CLI y la UI se puede cambiar proporcionando un objeto con la propiedad color.

server

Tipo: { sourcemap?, deps?, ... }

Opciones del servidor Vite-Node.

server.sourcemap

Tipo: 'inline' | boolean
Predeterminado: 'inline'

Inyecta un mapa de origen en línea en los módulos.

server.debug

Tipo: { dumpModules?, loadDumppedModules? }

Opciones del depurador Vite-Node.

server.debug.dumpModules

Tipo: boolean | string

Vuelca el módulo transformado al sistema de archivos. Si se pasa una cadena, se volcará a la ruta especificada.

server.debug.loadDumppedModules

Tipo: boolean

Lee el módulo volcado del sistema de archivos cuando esté presente. Útil para depurar modificando el resultado del volcado desde el sistema de archivos.

server.deps

Tipo: { external?, inline?, ... }

Manejo de la resolución de dependencias.

server.deps.external

Tipo: (string | RegExp)[]
Predeterminado: [/\/node_modules\//]

Externalizar significa que Vite pasará el control del paquete directamente a Node nativo. Las dependencias externalizadas no se aplicarán a los transformadores y resolutores de Vite, por lo que no soportan HMR al recargar. Por defecto, todos los paquetes dentro de node_modules están externalizados.

Estas opciones soportan nombres de paquetes exactamente como aparecen en node_modules o especificados dentro de deps.moduleDirectories. Por ejemplo, el paquete @company/some-name ubicado dentro de packages/some-name debe especificarse como some-name, y packages debe incluirse en deps.moduleDirectories. Básicamente, Vitest siempre comprueba la ruta del archivo, no el nombre real del paquete.

Si se usa una expresión regular, Vitest la aplica a la ruta del archivo, no al nombre del paquete.

server.deps.inline

Tipo: (string | RegExp)[] | true
Predeterminado: []

Vite procesará los módulos integrados. Esto podría ser útil para manejar paquetes que distribuyen .js en formato ESM (que Node no soporta).

Si es true, cada dependencia se incluirá en línea. Todas las dependencias, especificadas en ssr.noExternal se incluirán en línea por defecto.

server.deps.fallbackCJS

Tipo boolean
Predeterminado: false

Cuando una dependencia es un paquete ESM válido, se intenta determinar la versión CJS basándose en la ruta. Esto podría ser útil si una dependencia incluye un archivo ESM incorrecto.

Esto podría causar inconsistencias si un paquete tiene una lógica diferente en modo ESM y CJS.

server.deps.cacheDir

Tipo string
Predeterminado: 'node_modules/.vite'

Directorio para guardar archivos de caché.

deps

Tipo: { optimizer?, ... }

Manejo de la resolución de dependencias.

deps.optimizer

Tipo: { ssr?, web? }
Ver también: Opciones de optimización de dependencias

Habilita la optimización de dependencias. Si tienes muchas pruebas, esto podría mejorar su rendimiento.

Cuando Vitest encuentra la biblioteca externa listada en include, se agrupará en un solo archivo usando esbuild y se importará como un módulo completo. Esto es bueno por varias razones:

Importar paquetes con muchas importaciones es ineficiente. Al empaquetarlos en un solo archivo podemos ahorrar mucho tiempo.
Importar bibliotecas de UI es ineficiente porque no están destinadas a ejecutarse dentro de Node.js.
Tu configuración de alias ahora es tenida en cuenta dentro de los paquetes agrupados.
El código en tus pruebas se ejecuta de manera más parecida a como lo haría en el navegador.

Ten en cuenta que solo los paquetes en la opción deps.optimizer?.[mode].include se agrupan (algunos plugins lo configuran automáticamente, como Svelte). Puedes leer más sobre las opciones disponibles en la documentación de Vite (Vitest no soporta las opciones disable y noDiscovery). Por defecto, Vitest usa optimizer.web para los entornos jsdom y happy-dom, y optimizer.ssr para los entornos node y edge, pero es configurable a través de transformMode.

Esta opción también hereda tu configuración de optimizeDeps (para web Vitest extenderá optimizeDeps, para ssr - ssr.optimizeDeps). Si redefines la opción include/exclude en deps.optimizer, se aplicará sobre tu optimizeDeps al ejecutar las pruebas. Vitest elimina automáticamente las opciones duplicadas de include si están listadas en exclude.

TIP

No podrás editar el código de tus node_modules al depurar, ya que el código se encuentra realmente en tu directorio cacheDir o test.cache.dir. Si quieres depurar con instrucciones console.log, edítalo directamente o fuerza la reagrupación con la opción deps.optimizer?.[mode].force.

deps.optimizer.{mode}.enabled

Tipo: boolean
Predeterminado: false

Habilita la optimización de dependencias.

deps.web

Tipo: { transformAssets?, ... }

Opciones que afectan a archivos externos cuando el modo de transformación se establece en web. Por defecto, jsdom y happy-dom usan el modo web, mientras que los entornos node y edge usan el modo de transformación ssr, por lo que estas opciones no afectarán a los archivos dentro de esos entornos.

Por lo general, los archivos dentro de node_modules se externalizan, pero estas opciones también afectan a los archivos en server.deps.external.

deps.web.transformAssets

Tipo: boolean
Predeterminado: true

¿Debe Vitest procesar los archivos de recursos (.png, .svg, .jpg, etc.) y resolverlos como lo hace Vite en el navegador?

Este módulo tendrá una exportación predeterminada que será la ruta del activo, si no se especifica ninguna consulta.

WARNING

Por el momento, esta opción solo funciona con los pools vmThreads y vmForks.

deps.web.transformCss

Tipo: boolean
Predeterminado: true

¿Debe Vitest procesar los archivos CSS (.css, .scss, .sass, etc.) y resolverlos de la misma manera que Vite en el navegador?

Si los archivos CSS están deshabilitados con las opciones css, esta opción simplemente silenciará los errores ERR_UNKNOWN_FILE_EXTENSION.

WARNING

Por el momento, esta opción solo funciona con los pools vmThreads y vmForks.

deps.web.transformGlobPattern

Tipo: RegExp | RegExp[]
Predeterminado: []

Patrón de expresión regular para identificar los archivos externos que deben transformarse.

Por defecto, los archivos dentro de node_modules se externalizan y no se transforman, a menos que sea CSS o un recurso, y la opción correspondiente no esté deshabilitada.

WARNING

Por el momento, esta opción solo funciona con los pools vmThreads y vmForks.

deps.interopDefault

Tipo: boolean
Predeterminado: true

Interpreta la exportación predeterminada del módulo CJS como exportaciones con nombre. Algunas dependencias solo distribuyen módulos CJS y no usan exportaciones con nombre que Node.js pueda analizar estáticamente cuando un paquete se importa usando la sintaxis import en lugar de require. Al importar dichas dependencias en un entorno Node usando exportaciones con nombre, verás este error:

import { read } from 'fs-jetpack';
         ^^^^
SyntaxError: Named export 'read' not found. The requested module 'fs-jetpack' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export.

Vitest no realiza análisis estáticos y no puede detectar errores antes de la ejecución de tu código, por lo que lo más probable es que veas este error al ejecutar las pruebas si esta característica está deshabilitada:

TypeError: createAsyncThunk is not a function
TypeError: default is not a function

Por defecto, Vitest asume que estás usando un empaquetador para manejar esto y no fallará, pero puedes deshabilitar este comportamiento manualmente si tu código no se procesa.

deps.moduleDirectories

Tipo: string[]
Predeterminado: ['node_modules']

Una lista de directorios que se considerarán directorios de módulos. Esta opción de configuración afecta el comportamiento de vi.mock: cuando no se proporciona una fábrica y la ruta del módulo que estás simulando coincide con uno de los valores de moduleDirectories, Vitest intentará resolver la simulación buscando una carpeta __mocks__ en la raíz del proyecto.

Esta opción también afectará la determinación de si un archivo debe considerarse un módulo al externalizar dependencias. Por defecto, Vitest importa módulos externos directamente con Node.js, omitiendo el paso de transformación de Vite.

Establecer esta opción anulará el valor predeterminado; si deseas seguir buscando paquetes en node_modules, debes incluirlo junto con cualquier otra opción:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    deps: {
      moduleDirectories: ['node_modules', path.resolve('../../packages')],
    },
  },
});

runner

Tipo: VitestRunnerConstructor
Predeterminado: node, al ejecutar pruebas, o benchmark, al ejecutar pruebas de rendimiento

Ruta a un ejecutor de pruebas personalizado. Esta es una característica avanzada y debe usarse con ejecutores de pruebas de bibliotecas personalizadas. Puedes leer más al respecto en la documentación.

benchmark

Tipo: { include?, exclude?, ... }

Opciones utilizadas al ejecutar vitest bench.

benchmark.include

Tipo: string[]
Predeterminado: ['**/*.{bench,benchmark}.?(c|m)[jt]s?(x)']

Patrones glob a incluir para archivos de prueba de rendimiento.

benchmark.exclude

Tipo: string[]
Predeterminado: ['node_modules', 'dist', '.idea', '.git', '.cache']

Patrones glob a excluir para archivos de prueba de rendimiento.

benchmark.includeSource

Tipo: string[]
Predeterminado: []

Incluye patrones glob para archivos de prueba de rendimiento en el código fuente. Esta opción es similar a includeSource.

Cuando se define, Vitest ejecutará todos los archivos coincidentes con import.meta.vitest dentro.

benchmark.reporters

Tipo: Arrayable<BenchmarkBuiltinReporters | Reporter>
Predeterminado: 'default'

Generador de informes personalizado para la salida. Puede contener uno o más nombres de informes predefinidos, instancias de reporteros y/o rutas a reporteros personalizados.

benchmark.outputFile

Obsoleto; usar benchmark.outputJson en su lugar.

benchmark.outputJson

Tipo: string | undefined
Predeterminado: undefined

Una ruta de archivo para almacenar el resultado del benchmark, útil para la opción --compare más tarde.

Por ejemplo:

# guarda el resultado de la rama principal
git checkout main
vitest bench --outputJson main.json

# cambia de rama y compara con la principal
git checkout feature
vitest bench --compare main.json

benchmark.compare

Tipo: string | undefined
Predeterminado: undefined

Una ruta de archivo a un resultado de benchmark anterior para comparar con las ejecuciones actuales.

alias

Tipo: Record<string, string> | Array<{ find: string | RegExp, replacement: string, customResolver?: ResolverFunction | ResolverObject }>

Define alias personalizados para usar en las pruebas. Se combinarán con los alias de resolve.alias.

WARNING

Vitest utiliza componentes básicos SSR de Vite para ejecutar pruebas, lo que tiene ciertos inconvenientes.

Los alias afectan solo a los módulos importados directamente con una palabra clave import desde un módulo integrado (todo el código fuente se incluye en línea por defecto).
Vitest no soporta el alias de llamadas require.
Si estás creando un alias para una dependencia externa (por ejemplo, react -> preact), es posible que desees aliar directamente los paquetes node_modules para que funcione con las dependencias externalizadas. Tanto Yarn como pnpm soportan alias mediante el prefijo npm:.

globals

Tipo: boolean
Predeterminado: false
CLI: --globals, --globals=false

Por defecto, vitest no proporciona APIs globales con el fin de ser más explícito. Si prefieres usar las APIs globalmente como Jest, puedes pasar la opción --globals en la CLI o añadir globals: true en la configuración.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
  },
});

Para habilitar el soporte de TypeScript para las APIs globales, añade vitest/globals al campo types en tu tsconfig.json.

json

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Si has redefinido tus typeRoots para incluir más tipos en tu compilación, tendrás que reincluir node_modules para que vitest/globals sea detectable.

json

{
  "compilerOptions": {
    "typeRoots": ["./types", "./node_modules/@types", "./node_modules"],
    "types": ["vitest/globals"]
  }
}

Si ya estás utilizando unplugin-auto-import en tu proyecto, también puedes usarlo directamente para autoimportar esas APIs.

import { defineConfig } from 'vitest/config';
import AutoImport from 'unplugin-auto-import/vite';

export default defineConfig({
  plugins: [
    AutoImport({
      imports: ['vitest'],
      dts: true, // generar declaración de TypeScript
    }),
  ],
});

environment

Tipo: 'node' | 'jsdom' | 'happy-dom' | 'edge-runtime' | string
Predeterminado: 'node'
CLI: --environment=<env>

El entorno a utilizar para las pruebas. El entorno predeterminado en Vitest es un entorno Node.js. Si estás construyendo una aplicación web, puedes usar un entorno similar al navegador a través de jsdom o happy-dom.

Si estás construyendo funciones de borde, puedes usar el entorno edge-runtime.

TIP

También puedes usar el Modo Navegador para ejecutar pruebas de integración o unitarias en el navegador sin simular el entorno.

Al añadir un bloque de documentación o comentario @vitest-environment en la parte superior del archivo, puedes especificar otro entorno para todas las pruebas de ese archivo:

Estilo Docblock:

/**
 * @vitest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Estilo de comentario:

// @vitest-environment happy-dom

test('use happy-dom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Para compatibilidad con Jest, también se puede usar @jest-environment:

/**
 * @jest-environment jsdom
 */

test('use jsdom in this test file', () => {
  const element = document.createElement('div');
  expect(element).not.toBeNull();
});

Si estás ejecutando Vitest con el parámetro --isolate=false, tus pruebas se ejecutarán en este orden: node, jsdom, happy-dom, edge-runtime, entornos personalizados. Es decir, cada prueba con el mismo entorno se agrupa, pero sigue ejecutándose secuencialmente.

A partir de la versión 0.23.0, también puedes definir un entorno personalizado. Cuando se utiliza un entorno personalizado, Vitest intentará cargar el paquete vitest-environment-${name}. Ese paquete debe exportar un objeto que cumpla con la interfaz Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  setup() {
    // configuración personalizada
    return {
      teardown() {
        // se llama después de que se hayan ejecutado todas las pruebas con este entorno
      },
    };
  },
};

Vitest también expone builtinEnvironments mediante la entrada vitest/environments, en caso de que solo quieras extenderlo. Puedes leer más sobre la extensión de entornos en nuestra guía.

TIP

El entorno jsdom expone la variable global jsdom, que es la instancia actual de JSDOM. Si quieres que TypeScript la identifique, puedes añadir vitest/jsdom a tu tsconfig.json cuando uses este entorno:

json

{
  "compilerOptions": {
    "types": ["vitest/jsdom"]
  }
}

environmentOptions

Tipo: Record<'jsdom' | string, unknown>
Predeterminado: {}

Estas opciones se proporcionan al método setup del environment actual. Por defecto, solo puedes configurar las opciones de JSDOM, si lo utilizas como tu entorno de prueba.

environmentMatchGlobs

Tipo: [string, EnvironmentName][]
Predeterminado: []

DEPRECATED

Esta API fue deprecada en Vitest 3. Usa proyectos para definir diferentes configuraciones en su lugar.

export default defineConfig({
  test: {
    environmentMatchGlobs: [ 
      ['./*.jsdom.test.ts', 'jsdom'], 
    ], 
    projects: [ 
      { 
        extends: true, 
        test: { 
          environment: 'jsdom', 
        }, 
      }, 
    ], 
  },
})

Asigna automáticamente el entorno según patrones glob. La primera coincidencia será la que se aplique.

Por ejemplo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environmentMatchGlobs: [
      // todas las pruebas en tests/dom se ejecutarán con el entorno jsdom
      ['tests/dom/**', 'jsdom'],
      // todas las pruebas en tests/ con .edge.test.ts se ejecutarán con el entorno edge-runtime
      ['**/*.edge.test.ts', 'edge-runtime'],
      // ...
    ],
  },
});

poolMatchGlobs

Tipo: [string, 'threads' | 'forks' | 'vmThreads' | 'vmForks' | 'typescript'][]
Predeterminado: []

DEPRECATED

Esta API fue deprecada en Vitest 3. Usa proyectos para definir diferentes configuraciones en su lugar:

export default defineConfig({
  test: {
    poolMatchGlobs: [ 
      ['./*.threads.test.ts', 'threads'], 
    ], 
    projects: [ 
      { 
        test: { 
          extends: true, 
          pool: 'threads', 
        }, 
      }, 
    ], 
  },
})

Asigna automáticamente el pool para la ejecución de las pruebas basándose en patrones glob. Se utilizará la primera coincidencia.

Por ejemplo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolMatchGlobs: [
      // todas las pruebas en el directorio "worker-specific" se ejecutarán dentro de un worker como si se hubiera habilitado `--pool=threads` para ellas,
      ['**/tests/worker-specific/**', 'threads'],
      // ejecuta todas las pruebas en el directorio "browser" directamente en el navegador
      ['**/tests/browser/**', 'browser'],
      // todas las demás pruebas se ejecutarán según las opciones "browser.enabled" y "threads", si no especificaste otros patrones glob
      // ...
    ],
  },
});

update*

Tipo: boolean
Predeterminado: false
CLI: -u, --update, --update=false

Actualiza los archivos de instantáneas. Esto actualizará todas las instantáneas que hayan cambiado y eliminará las obsoletas.

watch*

Tipo: boolean
Predeterminado: !process.env.CI && process.stdin.isTTY
CLI: -w, --watch, --watch=false

Habilita el modo de vigilancia.

En entornos interactivos, este es el valor predeterminado, a menos que se especifique --run explícitamente.

En CI, o cuando se ejecuta desde un shell no interactivo, el modo "watch" no es el predeterminado, pero se puede habilitar explícitamente con este parámetro.

watchTriggerPatterns 3.2.0+ *

Tipo: WatcherTriggerPattern[]

Vitest vuelve a ejecutar las pruebas basándose en el grafo de módulos que se construye a partir de las sentencias import estáticas y dinámicas. Sin embargo, si estás leyendo del sistema de archivos o recuperando datos de un proxy, Vitest no puede detectar esas dependencias.

Para volver a ejecutar correctamente esas pruebas, puedes definir un patrón de expresión regular y una función que devuelva una lista de archivos de prueba a ejecutar.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    watchTriggerPatterns: [
      {
        pattern: /^src\/(mailers|templates)\/(.*)\.(ts|html|txt)$/,
        testToRun: (id, match) => {
          // relativo al valor raíz
          return `./api/tests/mailers/${match[2]}.test.ts`;
        },
      },
    ],
  },
});

WARNING

Los archivos devueltos deben especificarse como rutas absolutas o relativas a la raíz. Ten en cuenta que esta es una opción global y no se puede usar dentro de las configuraciones de proyecto.

root

Tipo: string
CLI: -r <ruta>, --root=<ruta>

Raíz del proyecto.

dir

Tipo: string
CLI: --dir=<ruta>
Predeterminado: igual que root

Directorio base para buscar los archivos de prueba. Puedes especificar esta opción para acelerar el descubrimiento de pruebas si tu raíz abarca todo el proyecto.

reporters*

Tipo: Reporter | Reporter[]
Predeterminado: 'default'
CLI: --reporter=<nombre>, --reporter=<nombre1> --reporter=<nombre2>

Generadores de informes personalizados para la salida. Los reporteros pueden ser una instancia de Reporter, una cadena para seleccionar reporteros incorporados, o una ruta a una implementación personalizada (por ejemplo, './ruta/a/reporter.ts', '@scope/reporter').

outputFile*

Tipo: string | Record<string, string>
CLI: --outputFile=<ruta>, --outputFile.json=./ruta

Escribe los resultados de las pruebas en un archivo si también se especifica la opción --reporter=json, --reporter=html o --reporter=junit. Al proporcionar un objeto en lugar de una cadena, puedes definir rutas de salida individuales cuando uses varios reporteros.

pool*

Tipo: 'threads' | 'forks' | 'vmThreads' | 'vmForks'
Predeterminado: 'forks'
CLI: --pool=threads

Grupo de procesos utilizado para ejecutar pruebas.

threads*

Habilita el multiprocesamiento usando tinypool (una versión ligera derivada de Piscina). Al usar hilos, no es posible utilizar APIs relacionadas con procesos como process.chdir(). Algunas bibliotecas escritas en lenguajes nativos, como Prisma, bcrypt y canvas, tienen problemas al ejecutarse en múltiples hilos y pueden causar fallos de segmentación. En estos casos, se recomienda usar el grupo de procesos forks en su lugar.

forks*

Similar al pool threads pero usa child_process en lugar de worker_threads mediante tinypool. La comunicación entre las pruebas y el proceso principal no es tan rápida como con el grupo de procesos threads. Las APIs relacionadas con procesos como process.chdir() están disponibles en el pool forks.

vmThreads*

Ejecuta pruebas usando contexto VM (dentro de un entorno aislado) en un grupo de procesos de threads.

Esto hace que las pruebas se ejecuten más rápido, pero el módulo VM presenta inestabilidad cuando se ejecuta código ESM. Tus pruebas tendrán fugas de memoria [https://github.com/nodejs/node/issues/33439] - para mitigar esto, considera editar manualmente el valor de poolOptions.vmThreads.memoryLimit.

WARNING

Ejecutar código en un entorno aislado tiene algunas ventajas (pruebas más rápidas), pero también conlleva una serie de desventajas.

Las variables globales dentro de los módulos nativos, como (fs, path, etc.), difieren de los globales presentes en tu entorno de prueba. Como resultado, cualquier error lanzado por estos módulos nativos utilizará un constructor de Error diferente al utilizado en tu código:

try {
  fs.writeFileSync('/no existe');
} catch (err) {
  console.log(err instanceof Error); // false
}

La importación de módulos ES los mantiene en caché de forma indefinida, lo que introduce fugas de memoria si tienes muchos contextos (archivos de prueba). No hay una API en Node.js que limpie esa caché.
Acceder a las variables globales tarda más en un entorno aislado.

Por favor, sé consciente de estos problemas al usar esta opción. El equipo de Vitest no puede solucionar ninguno de estos problemas desde nuestro lado.

vmForks*

Similar al pool vmThreads pero usa child_process en lugar de worker_threads mediante tinypool. La comunicación entre las pruebas y el proceso principal no es tan rápida como con el grupo de procesos vmThreads. Las APIs relacionadas con procesos como process.chdir() están disponibles en el pool vmForks. Ten en cuenta que este pool tiene los mismos inconvenientes mencionados en la sección vmThreads.

poolOptions*

Tipo: Record<'threads' | 'forks' | 'vmThreads' | 'vmForks', {}>
Predeterminado: {}

poolOptions.threads

Opciones para el pool threads.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      threads: {
        // Opciones relacionadas con hilos aquí
      },
    },
  },
});

poolOptions.threads.maxThreads*

Tipo: number | string
Predeterminado: CPUs disponibles

Número máximo o porcentaje de hilos de ejecución. También puedes usar la variable de entorno VITEST_MAX_THREADS.

poolOptions.threads.minThreads*

Tipo: number | string
Predeterminado: CPUs disponibles

Número mínimo o porcentaje de hilos de ejecución. También puedes usar la variable de entorno VITEST_MIN_THREADS.

poolOptions.threads.singleThread

Tipo: boolean
Predeterminado: false

Ejecuta todas las pruebas con el mismo entorno dentro de un único worker. Esto deshabilitará el aislamiento de módulos nativo (tu código fuente o código integrado se reevaluará para cada prueba), pero puede mejorar el rendimiento de las pruebas.

WARNING

Aunque esta opción forzará que las pruebas se ejecuten secuencialmente, esta opción es diferente de --runInBand de Jest. Vitest emplea workers no solo para ejecutar pruebas en paralelo, sino también para proporcionar aislamiento. Al deshabilitar esta opción, tus pruebas se ejecutarán secuencialmente, pero en el mismo contexto global, por lo que deberás gestionar el aislamiento manualmente.

Esto podría causar diversos problemas si dependes del estado global (los frameworks frontend suelen hacerlo) o si tu código depende de que el entorno se defina de forma independiente para cada prueba. Pero puede acelerar significativamente tus pruebas (hasta 3 veces más rápido) si no dependen necesariamente del estado global o pueden sortearlo fácilmente.

poolOptions.threads.useAtomics*

Tipo: boolean
Predeterminado: false

Usa Atomics para sincronizar hilos de ejecución.

Esto puede mejorar el rendimiento en algunos casos, pero podría causar un segmentation fault en versiones antiguas de Node.

poolOptions.threads.isolate

Tipo: boolean
Predeterminado: true

Aislar el entorno para cada archivo de prueba.

poolOptions.threads.execArgv*

Tipo: string[]
Predeterminado: []

Pasa argumentos adicionales a node para los hilos. Consulta API de línea de comandos | Node.js para obtener más información.

WARNING

Ten cuidado al usarlo, ya que algunas opciones pueden provocar el fallo del worker, por ejemplo, --prof, --title. Consulta https://github.com/nodejs/node/issues/41103.

poolOptions.forks

Opciones para el pool forks.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      forks: {
        // Opciones relacionadas con forks aquí
      },
    },
  },
});

poolOptions.forks.maxForks*

Tipo: number | string
Predeterminado: CPUs disponibles

Número máximo o porcentaje de procesos hijos. También puedes usar la variable de entorno VITEST_MAX_FORKS.

poolOptions.forks.minForks*

Tipo: number | string
Predeterminado: CPUs disponibles

Número mínimo o porcentaje de procesos hijos. También puedes usar la variable de entorno VITEST_MIN_FORKS.

poolOptions.forks.isolate

Tipo: boolean
Predeterminado: true

Aislar el entorno para cada archivo de prueba.

poolOptions.forks.singleFork

Tipo: boolean
Predeterminado: false

Ejecuta todas las pruebas con el mismo entorno dentro de un único subproceso. Esto deshabilitará el aislamiento de módulos nativo (tu código fuente o código integrado se reevaluará para cada prueba), pero puede mejorar el rendimiento de las pruebas.

WARNING

Aunque esta opción forzará que las pruebas se ejecuten secuencialmente, esta opción es diferente de --runInBand de Jest. Vitest emplea procesos hijos no solo para ejecutar pruebas en paralelo, sino también para proporcionar aislamiento. Al deshabilitar esta opción, tus pruebas se ejecutarán secuencialmente, pero en el mismo contexto global, por lo que deberás gestionar el aislamiento manualmente.

poolOptions.forks.execArgv*

Tipo: string[]
Predeterminado: []

Pasa argumentos adicionales al proceso node para los procesos hijos. Consulta API de línea de comandos | Node.js para obtener más información.

WARNING

Ten cuidado al usarlo, ya que algunas opciones pueden provocar el fallo del worker, por ejemplo, --prof, --title. Consulta https://github.com/nodejs/node/issues/41103.

poolOptions.vmThreads

Opciones para el pool vmThreads.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmThreads: {
        // Opciones relacionadas con hilos VM aquí
      },
    },
  },
});

poolOptions.vmThreads.maxThreads*

Tipo: number | string
Predeterminado: CPUs disponibles

Número máximo o porcentaje de hilos de ejecución. También puedes usar la variable de entorno VITEST_MAX_THREADS.

poolOptions.vmThreads.minThreads*

Tipo: number | string
Predeterminado: CPUs disponibles

Número mínimo o porcentaje de hilos de ejecución. También puedes usar la variable de entorno VITEST_MIN_THREADS.

poolOptions.vmThreads.memoryLimit*

Tipo: string | number
Predeterminado: 1 / Núcleos de CPU

Especifica el límite de memoria para los trabajadores antes de que sean reciclados. Este valor está fuertemente influenciado por tu entorno, por lo que es mejor especificarlo manualmente en lugar de depender del valor predeterminado.

TIP

La implementación está basada en workerIdleMemoryLimit de Jest.

El límite se puede especificar de varias maneras y, en cualquier caso, se utiliza Math.floor para convertirlo en un valor entero:

<= 1 - Se asume que el valor es un porcentaje de la memoria del sistema. Así, 0.5 establece el límite de memoria del trabajador a la mitad de la memoria total del sistema.
> 1 - Se asume que es un valor fijo en bytes. Debido a la regla anterior, si quisieras un valor de 1 byte, podrías usar 1.1.
Con unidades
- 50% - Como se indicó anteriormente, un porcentaje de la memoria total del sistema.
- 100KB, 65MB, etc. - Con unidades para denotar un límite de memoria fijo.
  - K / KB - Kilobytes (x1000)
  - KiB - Kibibytes (x1024)
  - M / MB - Megabytes - MiB - Mebibytes
  - G / GB - Gigabytes - GiB - Gibibytes

WARNING

El límite de memoria basado en porcentaje no funciona en los trabajadores de Linux CircleCI debido a que se informa una memoria del sistema incorrecta.

poolOptions.vmThreads.useAtomics*

Tipo: boolean
Predeterminado: false

Usa Atomics para sincronizar hilos de ejecución.

Esto puede mejorar el rendimiento en algunos casos, pero podría causar un segmentation fault en versiones antiguas de Node.

poolOptions.vmThreads.execArgv*

Tipo: string[]
Predeterminado: []

Pasa argumentos adicionales al proceso node para el contexto de la VM. Consulta API de línea de comandos | Node.js para obtener más información.

WARNING

Ten cuidado al usarlo, ya que algunas opciones pueden provocar el fallo del worker, por ejemplo, --prof, --title. Consulta https://github.com/nodejs/node/issues/41103.

poolOptions.vmForks*

Opciones para el pool vmForks.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    poolOptions: {
      vmForks: {
        // Opciones relacionadas con forks VM aquí
      },
    },
  },
});

poolOptions.vmForks.maxForks*

Tipo: number | string
Predeterminado: CPUs disponibles

Número máximo o porcentaje de procesos hijos. También puedes usar la variable de entorno VITEST_MAX_FORKS.

poolOptions.vmForks.minForks*

Tipo: number | string
Predeterminado: CPUs disponibles

Número mínimo o porcentaje de procesos hijos. También puedes usar la variable de entorno VITEST_MIN_FORKS.

poolOptions.vmForks.memoryLimit*

Tipo: string | number
Predeterminado: 1 / Núcleos de CPU

Especifica el límite de memoria para los trabajadores antes de que sean reciclados. Este valor depende en gran medida de tu entorno, por lo que es mejor especificarlo manualmente en lugar de depender del valor predeterminado. Cómo se calcula el valor se describe en poolOptions.vmThreads.memoryLimit.

poolOptions.vmForks.execArgv*

Tipo: string[]
Predeterminado: []

Pasa argumentos adicionales al proceso node para el contexto de la VM. Consulta API de línea de comandos | Node.js para obtener más información.

WARNING

Ten cuidado al usarlo, ya que algunas opciones pueden provocar el fallo del worker, por ejemplo, --prof, --title. Consulta https://github.com/nodejs/node/issues/41103.

fileParallelism*

Tipo: boolean
Predeterminado: true
CLI: --no-file-parallelism, --fileParallelism=false

¿Se ejecutarán todos los archivos de prueba en paralelo? Establecer esto en false fijará las opciones maxWorkers y minWorkers en 1.

TIP

Esta opción no afecta a las pruebas dentro del mismo archivo. Si quieres ejecutarlas en paralelo, usa la opción concurrent en describe o mediante una configuración.

maxWorkers*

Tipo: number | string

Número máximo o porcentaje de trabajadores para ejecutar pruebas. poolOptions.{threads,vmThreads}.maxThreads/poolOptions.forks.maxForks prevalece.

minWorkers*

Tipo: number | string

Número mínimo o porcentaje de trabajadores para ejecutar pruebas. poolOptions.{threads,vmThreads}.minThreads/poolOptions.forks.minForks prevalece.

testTimeout

Tipo: number
Predeterminado: 5_000 en Node.js, 15_000 si browser.enabled es true
CLI: --test-timeout=5000, --testTimeout=5000

Tiempo de espera predeterminado para una prueba en milisegundos. Usa 0 para desactivar el tiempo de espera totalmente.

hookTimeout

Tipo: number
Predeterminado: 10_000 en Node.js, 30_000 si browser.enabled es true
CLI: --hook-timeout=10000, --hookTimeout=10000

Tiempo de espera predeterminado para un hook en milisegundos. Usa 0 para desactivar el tiempo de espera por completo.

teardownTimeout*

Tipo: number
Predeterminado: 10000
CLI: --teardown-timeout=5000, --teardownTimeout=5000

Tiempo de espera predeterminado para el cierre de Vitest en milisegundos.

silent*

Tipo: boolean | 'passed-only'
Predeterminado: false
CLI: --silent, --silent=false

Suprime la salida de la consola de las pruebas.

Usa 'passed-only' para ver los registros únicamente de las pruebas fallidas. Los registros de las pruebas fallidas se imprimen después de que finaliza una prueba.

setupFiles

Tipo: string | string[]

Ruta a los archivos de preparación. Se ejecutarán antes de cada archivo de prueba.

INFO

Editar un archivo de preparación provocará automáticamente una nueva ejecución de todas las pruebas.

Puedes usar process.env.VITEST_POOL_ID (cadena similar a un entero) para diferenciar entre hilos.

TIP

Ten en cuenta que si estás ejecutando --isolate=false, este archivo de configuración se ejecutará repetidamente en el mismo ámbito global. Es decir, estás accediendo al mismo objeto global antes de cada prueba, así que asegúrate de evitar operaciones redundantes.

Por ejemplo, si dependes de una variable global:

import { config } from '@some-testing-lib';

if (!globalThis.defined) {
  config.plugins = [myCoolPlugin];
  computeHeavyThing();
  globalThis.defined = true;
}

// los hooks se reinician antes de cada suite
afterEach(() => {
  cleanup();
});

globalThis.resetBeforeEachTest = true;

provide 2.1.0+

Tipo: Partial<ProvidedContext>

Define valores accesibles en tus pruebas usando el método inject.

vitest.config.jsapi.test.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    provide: {
      API_KEY: '123',
    },
  },
});

import { expect, inject, test } from 'vitest';

test('api key is defined', () => {
  expect(inject('API_KEY')).toBe('123');
});

WARNING

Las propiedades deben ser de tipo cadena y los valores deben ser serializables porque este objeto se transferirá entre diferentes procesos.

TIP

Si estás usando TypeScript, necesitarás aumentar el tipo ProvidedContext para un acceso tipado seguro:

declare module 'vitest' {
  export interface ProvidedContext {
    API_KEY: string;
  }
}

// marca este archivo como un módulo para que la extensión funcione correctamente
export {};

globalSetup

Tipo: string | string[]

Ruta a los archivos de preparación global, relativa a la raíz del proyecto.

Un archivo de configuración global puede exportar las funciones con nombre setup y teardown o una función default que devuelve una función de teardown (ejemplo).

INFO

Se pueden usar varios archivos globalSetup. setup y teardown se ejecutan secuencialmente, con teardown ejecutándose en orden inverso.

WARNING

La configuración global se ejecuta únicamente si existe al menos una prueba en ejecución. Esto significa que la configuración global podría comenzar a ejecutarse durante el modo de vigilancia después de que se cambie un archivo de prueba (el archivo de prueba esperará a que la configuración global finalice antes de su ejecución).

Sé consciente de que la configuración global se ejecuta en un ámbito global diferente, por lo que tus pruebas no tienen acceso a las variables definidas aquí. Sin embargo, puedes transferir datos serializables a las pruebas mediante el método provide:

example.test.jsglobalSetup.ts 3.0.0+ globalSetup.ts 2.0.0+

import { inject } from 'vitest';

inject('wsPort') === 3000;

import type { TestProject } from 'vitest/node';

export default function setup(project: TestProject) {
  project.provide('wsPort', 3000);
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

import type { GlobalSetupContext } from 'vitest/node';

export default function setup({ provide }: GlobalSetupContext) {
  provide('wsPort', 3000);
}

declare module 'vitest' {
  export interface ProvidedContext {
    wsPort: number;
  }
}

A partir de Vitest 3, puedes definir una función de devolución de llamada personalizada que se llamará cuando Vitest vuelva a ejecutar las pruebas. Si la función es asíncrona, el runner esperará a que se complete antes de ejecutar las pruebas. Ten en cuenta que no puedes desestructurar la propiedad project como { onTestsRerun } porque depende del contexto.

import type { TestProject } from 'vitest/node';

export default function setup(project: TestProject) {
  project.onTestsRerun(async () => {
    await restartDb();
  });
}

forceRerunTriggers*

Tipo: string[]
Predeterminado: ['**/package.json/**', '**/vitest.config.*/**', '**/vite.config.*/**']

Patrón glob de rutas de archivo que desencadenarán la repetición de toda la suite. Cuando se combina con el argumento --changed, ejecutará toda la suite de pruebas si el activador se encuentra en las diferencias de git.

Útil si estás probando la invocación de comandos CLI, porque Vite no puede construir un grafo de módulos:

test('execute a script', async () => {
  // Vitest no puede volver a ejecutar esta prueba si el contenido de `dist/index.js` se modifica
  await execa('node', ['dist/index.js']);
});

TIP

Asegúrate de que tus archivos no estén ignorados por server.watch.ignored.

coverage*

Puedes usar v8, istanbul o una solución de cobertura personalizada para la generación de cobertura.

Puedes especificar opciones de cobertura en la CLI usando notación de puntos:

npx vitest --coverage.enabled --coverage.provider=istanbul --coverage.all

WARNING

Si estás usando opciones de cobertura con notación de puntos, recuerda especificar --coverage.enabled. Evita proporcionar una sola opción --coverage en ese caso.

coverage.provider

Tipo: 'v8' | 'istanbul' | 'custom'
Predeterminado: 'v8'
CLI: --coverage.provider=<proveedor>

Usa provider para seleccionar la herramienta para la generación de cobertura.

coverage.enabled

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.enabled, --coverage.enabled=false

Habilita la generación de cobertura. Puede ser sobrescrito mediante la opción CLI --coverage.

coverage.include

Tipo: string[]
Predeterminado: ['**']
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.include=<ruta>, --coverage.include=<ruta1> --coverage.include=<ruta2>

Lista de archivos a incluir en la cobertura como patrones glob.

coverage.extension

Tipo: string | string[]
Predeterminado: ['.js', '.cjs', '.mjs', '.ts', '.mts', '.tsx', '.jsx', '.vue', '.svelte', '.marko', '.astro']
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.extension=<extension>, --coverage.extension=<extension1> --coverage.extension=<extension2>

coverage.exclude

Tipo: string[]
Predeterminado:

[
  'coverage/**',
  'dist/**',
  '**/node_modules/**',
  '**/[.]**',
  'packages/*/test?(s)/**',
  '**/*.d.ts',
  '**/virtual:*',
  '**/__x00__*',
  '**/\x00*',
  'cypress/**',
  'test?(s)/**',
  'test?(-*).?(c|m)[jt]s?(x)',
  '**/*{.,-}{test,spec,bench,benchmark}?(-d).?(c|m)[jt]s?(x)',
  '**/__tests__/**',
  '**/{karma,rollup,webpack,vite,vitest,jest,ava,babel,nyc,cypress,tsup,build,eslint,prettier}.config.*',
  '**/vitest.{workspace,projects}.[jt]s?(on)',
  '**/.{eslint,mocha,prettier}rc.{?(c|m)js,yml}',
];

Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.exclude=<ruta>, --coverage.exclude=<ruta1> --coverage.exclude=<ruta2>

Lista de archivos a excluir de la cobertura como patrones glob.

Esta opción sobrescribe todas las opciones predeterminadas. Para extender las opciones predeterminadas al añadir nuevos patrones para ignorar:

import { coverageConfigDefaults, defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    coverage: {
      exclude: ['**/patron-personalizado/**', ...coverageConfigDefaults.exclude],
    },
  },
});

NOTA

Vitest añade automáticamente los patrones include de los archivos de prueba a coverage.exclude. No se puede mostrar la cobertura de los archivos de prueba.

coverage.all

Tipo: boolean
Predeterminado: true
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.all, --coverage.all=false

Indica si se deben incluir todos los archivos, incluidos los no probados, en el informe de cobertura.

coverage.clean

Tipo: boolean
Predeterminado: true
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.clean, --coverage.clean=false

Borra los resultados de cobertura antes de ejecutar las pruebas.

coverage.cleanOnRerun

Tipo: boolean
Predeterminado: true
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.cleanOnRerun, --coverage.cleanOnRerun=false

Borra el informe de cobertura al volver a ejecutar en modo de vigilancia. Establece en false para preservar los resultados de cobertura de la ejecución anterior en modo de vigilancia.

coverage.reportsDirectory

Tipo: string
Predeterminado: './coverage'
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.reportsDirectory=<ruta>

WARNING

Vitest eliminará este directorio antes de ejecutar las pruebas si coverage.clean está habilitado (por defecto).

Directorio de destino para el informe de cobertura.

Para previsualizar el informe de cobertura en la salida del generador de informes HTML, esta opción debe establecerse como un subdirectorio del directorio del informe HTML (por ejemplo, ./html/coverage).

coverage.reporter

Tipo: string | string[] | [string, {}][]
Predeterminado: ['text', 'html', 'clover', 'json']
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.reporter=<reportero>, --coverage.reporter=<reportero1> --coverage.reporter=<reportero2>

Generadores de informes de cobertura a utilizar. Consulta la documentación de istanbul para obtener una lista detallada de todos los generadores de informes. Consulta @types/istanbul-reporter para obtener detalles sobre las opciones específicas del generador de informes.

El generador de informes tiene tres tipos diferentes:

Un solo generador de informes: { reporter: 'html' }
Múltiples generadores de informes sin opciones: { reporter: ['html', 'json'] }

Uno o varios generadores de informes con opciones de generador de informes:

{
  reporter: [
    ['lcov', { projectRoot: './src' }],
    ['json', { file: 'coverage.json' }],
    ['text'],
  ];
}

También puedes pasar generadores de informes de cobertura personalizados. Consulta la Guía - Generador de informes de cobertura personalizado para obtener más información.

{
  reporter: [
    // Especifica el generador de informes usando el nombre del paquete NPM
    '@vitest/custom-coverage-reporter',
    ['@vitest/custom-coverage-reporter', { someOption: true }],

    // Especifica el generador de informes usando la ruta local
    '/ruta/absoluta/a/custom-reporter.cjs',
    ['/ruta/absoluta/a/custom-reporter.cjs', { someOption: true }],
  ];
}

Puedes consultar tu informe de cobertura en la UI de Vitest: consulta Cobertura de la UI de Vitest para obtener más detalles.

coverage.reportOnFailure

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.reportOnFailure, --coverage.reportOnFailure=false

Se genera el informe de cobertura incluso cuando las pruebas fallan.

coverage.allowExternal

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.allowExternal, --coverage.allowExternal=false

Se recopila la cobertura de archivos fuera de la raíz del proyecto.

coverage.excludeAfterRemap 2.1.0+

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.excludeAfterRemap, --coverage.excludeAfterRemap=false

Se vuelven a aplicar las exclusiones después de que la cobertura se haya re-mapeado a las fuentes originales. Esto es útil cuando tus archivos fuente están transpilados y pueden contener mapas de origen de archivos que no son de código fuente.

Usa esta opción cuando observes archivos que aparecen en el informe incluso si coinciden con tus patrones coverage.exclude.

coverage.skipFull

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.skipFull, --coverage.skipFull=false

No se muestran archivos con el 100% de cobertura de sentencias, ramas y funciones.

coverage.thresholds

Opciones para los umbrales de cobertura.

Si un umbral se establece en un número positivo, se considerará el porcentaje mínimo de cobertura requerido. Por ejemplo, establecer el umbral de líneas en 90 significa que el 90% de las líneas deben cubrirse.

Si un umbral se establece en un número negativo, se considerará el número máximo de elementos no cubiertos permitidos. Por ejemplo, establecer el umbral de líneas en -10 significa que no más de 10 líneas pueden quedar sin cubrir.

{
  coverage: {
    thresholds: {
      // Requiere 90% de cobertura de funciones
      functions: 90,

      // Requiere que no más de 10 líneas estén sin cubrir
      lines: -10,
    }
  }
}

coverage.thresholds.lines

Tipo: number
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.lines=<número>

Umbral global de líneas.

coverage.thresholds.functions

Tipo: number
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.functions=<número>

Umbral global de funciones.

coverage.thresholds.branches

Tipo: number
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.branches=<número>

Umbral global de ramas.

coverage.thresholds.statements

Tipo: number
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.statements=<número>

Umbral global de sentencias.

coverage.thresholds.perFile

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.perFile, --coverage.thresholds.perFile=false

Se verifican los umbrales por archivo.

coverage.thresholds.autoUpdate

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.autoUpdate=<boolean>

Se actualizan todos los valores de umbral lines, functions, branches y statements en el archivo de configuración cuando la cobertura actual supera los umbrales configurados. Esta opción facilita el mantenimiento de los umbrales cuando se mejora la cobertura.

coverage.thresholds.100

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.thresholds.100, --coverage.thresholds.100=false

Fija los umbrales globales en 100. Es un atajo para --coverage.thresholds.lines 100 --coverage.thresholds.functions 100 --coverage.thresholds.branches 100 --coverage.thresholds.statements 100.

coverage.thresholds[glob-pattern]

Tipo: { statements?: number functions?: number branches?: number lines?: number }
Predeterminado: undefined
Disponible para proveedores: 'v8' | 'istanbul'

Fija umbrales para los archivos que coinciden con el patrón glob.

NOTA

Vitest incluye todos los archivos, incluidos los cubiertos por patrones glob, en el cálculo de los umbrales de cobertura global. Esto difiere del comportamiento de Jest.

{
  coverage: {
    thresholds: {
      // Umbrales aplicables a todos los archivos
      functions: 95,
      branches: 70,

      // Umbrales para archivos que coinciden con el patrón glob
      'src/utils/**.ts': {
        statements: 95,
        functions: 90,
        branches: 85,
        lines: 80,
      },

      // Los archivos que coincidan con este patrón solo tendrán umbrales de líneas definidos.
      // Los umbrales globales no son heredables.
      '**/math.ts': {
        lines: 100,
      }
    }
  }
}

coverage.thresholds[glob-pattern].100 2.1.0+

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8' | 'istanbul'

Fija los umbrales en 100 para los archivos que coinciden con el patrón glob.

{
  coverage: {
    thresholds: {
      // Umbrales aplicables a todos los archivos
      functions: 95,
      branches: 70,

      // Umbrales para archivos que coinciden con el patrón glob
      'src/utils/**.ts': { 100: true },
      '**/math.ts': { 100: true }
    }
  }
}

coverage.ignoreEmptyLines

Tipo: boolean
Predeterminado: true (false en v1)
Disponible para proveedores: 'v8'
CLI: --coverage.ignoreEmptyLines=<boolean>

Ignora líneas vacías, comentarios y código no ejecutable, por ejemplo, tipos de Typescript. Esta opción requiere experimentalAstAwareRemapping: false.

Esta opción solo funciona si el compilador utilizado elimina comentarios y código no ejecutable del código transpilado. Por defecto, Vite emplea ESBuild, que elimina comentarios y tipos de Typescript de los archivos .ts, .tsx y .jsx.

Si deseas aplicar ESBuild a otros archivos, debes definirlos en las opciones de esbuild:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  esbuild: {
    // Transpilar todos los archivos con ESBuild para eliminar comentarios de la cobertura de código.
    // Necesario para el funcionamiento de `test.coverage.ignoreEmptyLines`:
    include: ['**/*.js', '**/*.jsx', '**/*.mjs', '**/*.ts', '**/*.tsx'],
  },
  test: {
    coverage: {
      provider: 'v8',
      ignoreEmptyLines: true,
    },
  },
});

coverage.experimentalAstAwareRemapping

Tipo: boolean
Predeterminado: false
Disponible para proveedores: 'v8'
CLI: --coverage.experimentalAstAwareRemapping=<boolean>

Re-mapea la cobertura con análisis experimental basado en el árbol de sintaxis abstracta (AST). Proporciona resultados más precisos que el modo predeterminado.

coverage.ignoreClassMethods

Tipo: string[]
Predeterminado: []
Disponible para proveedores: 'istanbul'
CLI: --coverage.ignoreClassMethods=<método>

Define un array de nombres de métodos de clase que se ignorarán para la cobertura. Para más información, consulta la documentación de istanbul.

coverage.watermarks

Tipo:

{
  statements?: [number, number],
  functions?: [number, number],
  branches?: [number, number],
  lines?: [number, number]
}

Predeterminado:

{
  statements: [50, 80],
  functions: [50, 80],
  branches: [50, 80],
  lines: [50, 80]
}

Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.watermarks.statements=50,80, --coverage.watermarks.branches=50,80

Marcas de agua de sentencias, líneas, ramas y funciones. Consulta la documentación de istanbul para obtener más información.

coverage.processingConcurrency

Tipo: boolean
Predeterminado: Math.min(20, os.availableParallelism?.() ?? os.cpus().length)
Disponible para proveedores: 'v8' | 'istanbul'
CLI: --coverage.processingConcurrency=<número>

Límite de concurrencia para el procesamiento de los resultados de la cobertura.

coverage.customProviderModule

Tipo: string
Disponible para proveedores: 'custom'
CLI: --coverage.customProviderModule=<ruta o nombre del módulo>

Define el nombre del módulo o la ruta para el módulo del proveedor de cobertura personalizado. Consulta la Guía - Proveedor de cobertura personalizado para obtener más información.

testNamePattern*

Tipo string | RegExp
CLI: -t <patrón>, --testNamePattern=<patrón>, --test-name-pattern=<patrón>

Se ejecutarán pruebas con nombres completos que coincidan con el patrón. Si añades OnlyRunThis a esta propiedad, las pruebas que no contengan la palabra OnlyRunThis en el nombre de la prueba serán saltadas.

import { expect, test } from 'vitest';

// ejecutar
test('OnlyRunThis', () => {
  expect(true).toBe(true);
});

// omitido
test('doNotRun', () => {
  expect(true).toBe(true);
});

open*

Tipo: boolean
Predeterminado: !process.env.CI
CLI: --open, --open=false

Abre la interfaz de usuario de Vitest (WIP).

api

Tipo: boolean | number
Predeterminado: false
CLI: --api, --api.port, --api.host, --api.strictPort

Habilita la escucha en el puerto y sirve la API. Cuando es true, el puerto predeterminado es 51204.

browser experimental

Predeterminado: { enabled: false }
CLI: --browser=<nombre>, --browser.name=chrome --browser.headless

Configuración de la ejecución de pruebas en el navegador. Consulta el artículo "Referencia de configuración del navegador".

WARNING

Esta es una característica experimental. Los cambios importantes podrían no seguir SemVer, por favor, establece una versión específica de Vitest cuando la uses.

clearMocks

Tipo: boolean
Predeterminado: false

Invoca .mockClear() en todos los espías antes de cada prueba. Esto borrará el historial de mocks sin afectar las implementaciones de mocks.

mockReset

Tipo: boolean
Predeterminado: false

Invoca .mockReset() en todos los espías antes de cada prueba. Esto borrará el historial de mocks y restablecerá cada implementación a su original.

restoreMocks

Tipo: boolean
Predeterminado: false

Invoca .mockRestore() en todos los espías antes de cada prueba. Esto borrará el historial de mocks, restaurará cada implementación a su estado original y restaurará los descriptores originales de los objetos monitoreados.

unstubEnvs

Tipo: boolean
Predeterminado: false

Invoca vi.unstubAllEnvs antes de cada prueba.

unstubGlobals

Tipo: boolean
Predeterminado: false

Invoca vi.unstubAllGlobals antes de cada prueba.

testTransformMode

Tipo: { web?, ssr? }

Determina el método de transformación para todos los módulos importados dentro de una prueba que cumplan con el patrón glob. Por defecto, se basa en el entorno. Por ejemplo, las pruebas con entorno JSDOM procesarán todos los archivos con el parámetro ssr: false y las pruebas con entorno Node procesarán todos los módulos con ssr: true.

testTransformMode.ssr

Tipo: string[]
Predeterminado: []

Utiliza el proceso de transformación SSR para todos los módulos dentro de las pruebas especificadas.
Los plugins de Vite recibirán el parámetro ssr: true al procesar esos archivos.

testTransformMode.web

Tipo: string[]
Predeterminado: []

Primero realiza un proceso de transformación normal (para el navegador), luego realiza una reestructuración SSR para ejecutar el código en Node.
Los plugins de Vite recibirán el parámetro ssr: false al procesar esos archivos.

snapshotFormat*

Tipo: PrettyFormatOptions

Opciones de formato para el snapshot testing. Estas opciones se proporcionan a pretty-format.

TIP

Ten en cuenta que el campo plugins de este objeto será ignorado.

Si necesitas extender el serializador de instantáneas mediante plugins de pretty-format, usa la API expect.addSnapshotSerializer o la opción snapshotSerializers.

snapshotSerializers*

Tipo: string[]
Predeterminado: []

Una lista de rutas a módulos serializadores de instantáneas para snapshot testing, útil si deseas añadir serializadores de instantáneas personalizados. Consulta Serializador personalizado para obtener más información.

resolveSnapshotPath*

Tipo: (testPath: string, snapExtension: string, context: { config: SerializedConfig }) => string
Predeterminado: almacena los archivos de instantáneas en el directorio __snapshots__

Sobrescribe la ruta predeterminada de la instantánea. Por ejemplo, para almacenar instantáneas en el mismo directorio que los archivos de prueba:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    resolveSnapshotPath: (testPath, snapExtension) => testPath + snapExtension,
  },
});

allowOnly

Tipo: boolean
Predeterminado: !process.env.CI
CLI: --allowOnly, --allowOnly=false

Habilita pruebas y suites que están marcadas como "only".

dangerouslyIgnoreUnhandledErrors*

Tipo: boolean
Predeterminado: false
CLI: --dangerouslyIgnoreUnhandledErrors --dangerouslyIgnoreUnhandledErrors=false

Se ignorará cualquier error no manejado que ocurra.

passWithNoTests*

Tipo: boolean
Predeterminado: false
CLI: --passWithNoTests, --passWithNoTests=false

Vitest no fallará en caso de no encontrar pruebas.

logHeapUsage

Tipo: boolean
Predeterminado: false
CLI: --logHeapUsage, --logHeapUsage=false

Muestra el consumo de memoria heap después de cada prueba. Útil con fines de depuración de fugas de memoria.

css

Tipo: boolean | { include?, exclude?, modules? }

Configura si el CSS debe ser procesado. Cuando se excluye, los archivos CSS serán reemplazados por cadenas vacías para omitir el procesamiento subsiguiente. Los módulos CSS devolverán un proxy que no afectará el tiempo de ejecución.

css.include

Tipo: RegExp | RegExp[]
Predeterminado: []

Patrón RegExp para archivos que generarán CSS real y serán procesados por el proceso de Vite.

TIP

Para procesar todos los archivos CSS, se debe usar /.+/.

css.exclude

Tipo: RegExp | RegExp[]
Predeterminado: []

Patrón RegExp para archivos que resultarán en un archivo CSS vacío.

css.modules

Tipo: { classNameStrategy? }
Predeterminado: {}

css.modules.classNameStrategy

Tipo: 'stable' | 'scoped' | 'non-scoped'
Predeterminado: 'stable'

Si decides procesar archivos CSS, puedes configurar si los nombres de clase dentro de los módulos CSS deben ser de ámbito. Se puede elegir una de las opciones:

stable: los nombres de clase se generarán como _${nombre}_${nombreDeArchivoHashed}, lo que significa que la clase generada se mantendrá si el contenido CSS cambia, pero cambiará si se modifica el nombre del archivo o si el archivo se mueve a otra carpeta. Esta configuración es útil si utilizas la función de instantáneas.
scoped: los nombres de clase se generarán como de costumbre, respetando el método css.modules.generateScopedName, si está definido y el procesamiento de CSS está habilitado. Por defecto, el nombre de archivo se generará como _${name}_${hash}, donde el hash incluye el nombre y el contenido del archivo.
non-scoped: los nombres de clase no se hashearán.

WARNING

Por defecto, Vitest exporta un proxy, lo que evita el procesamiento de módulos CSS. Si dependes de las propiedades CSS de tus clases, debes habilitar el procesamiento de CSS usando la opción include.

maxConcurrency

Tipo: number
Predeterminado: 5
CLI: --max-concurrency=10, --maxConcurrency=10

Número de pruebas que pueden ejecutarse al mismo tiempo marcadas con test.concurrent.

Las pruebas por encima de este límite se pondrán en cola para ejecutarse cuando haya un slot disponible.

cache*

Tipo: false
CLI: --no-cache, --cache=false

Usa esta opción si deseas deshabilitar la función de caché. Por el momento, Vitest cachea los resultados de las pruebas para ejecutar primero las pruebas más largas y las fallidas.

El directorio de caché se gestiona mediante la opción cacheDir de Vite:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: 'custom-folder/.vitest',
});

Puedes restringir el directorio exclusivamente para Vitest usando process.env.VITEST:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  cacheDir: process.env.VITEST ? 'custom-folder/.vitest' : undefined,
});

sequence

Tipo: { sequencer?, shuffle?, seed?, hooks?, setupFiles?, groupOrder }

Opciones de ordenación de las pruebas.

Puedes especificar opciones de secuencia en la CLI usando notación de puntos:

npx vitest --sequence.shuffle --sequence.seed=1000

sequence.sequencer*

Tipo: TestSequencerConstructor
Predeterminado: BaseSequencer

Una clase personalizada que define métodos para sharding y clasificación. Puedes extender BaseSequencer desde vitest/node, si solo necesitas redefinir uno de los métodos sort y shard, pero ambos son obligatorios.

La fragmentación se realiza antes de la clasificación, y solo si se proporciona la opción --shard.

Si se especifica sequencer.groupOrder, el secuenciador será invocado una vez por cada grupo y pool.

groupOrder 3.2.0+

Tipo: number
Predeterminado: 0

Controla el orden en que este proyecto ejecuta las pruebas cuando se utilizan varios proyectos.

Los proyectos con el mismo número de orden de grupo se ejecutarán de forma conjunta, y los grupos se procesan de menor a mayor.
Si no se configura esta opción, todos los proyectos se ejecutan en paralelo.
Si varios proyectos comparten el mismo orden de grupo, se ejecutarán al mismo tiempo.

Esta configuración únicamente influye en el orden de ejecución de los proyectos, no en el orden de las pruebas dentro de un proyecto. Para controlar el aislamiento de las pruebas o el orden de las pruebas dentro de un proyecto, se deben usar las opciones isolate y sequence.sequencer.

Ejemplo

Veamos este ejemplo:

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'slow',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'fast',
          sequence: {
            groupOrder: 0,
          },
        },
      },
      {
        test: {
          name: 'flaky',
          sequence: {
            groupOrder: 1,
          },
        },
      },
    ],
  },
});

Las pruebas en estos proyectos se ejecutarán en este orden:

 0. slow  |
          |> ejecución conjunta
 0. fast  |

 1. flaky |> se ejecuta después de 'slow' y 'fast' de forma independiente

sequence.shuffle

Tipo: boolean | { files?, tests? }
Predeterminado: false
CLI: --sequence.shuffle, --sequence.shuffle=false

Si deseas que los archivos y las pruebas se ejecuten aleatoriamente, puedes activarlo con esta opción o con el argumento CLI --sequence.shuffle.

Vitest suele emplear la caché para ordenar las pruebas, permitiendo que las pruebas de larga duración comiencen antes, lo que hace que las pruebas se ejecuten más rápido. Si tus archivos y pruebas se ejecutan en orden aleatorio, perderás esta mejora de rendimiento, pero puede ser útil para identificar pruebas que dependan accidentalmente de ejecuciones previas.

sequence.shuffle.files

Tipo: boolean
Predeterminado: false
CLI: --sequence.shuffle.files, --sequence.shuffle.files=false

Indica si se deben aleatorizar los archivos. Sé consciente de que las pruebas de larga duración no comenzarán antes si habilitas esta opción.

sequence.shuffle.tests

Tipo: boolean
Predeterminado: false
CLI: --sequence.shuffle.tests, --sequence.shuffle.tests=false

Indica si se deben aleatorizar las pruebas.

sequence.concurrent

Tipo: boolean
Predeterminado: false
CLI: --sequence.concurrent, --sequence.concurrent=false

Si deseas que las pruebas se ejecuten en paralelo, puedes activarlo con esta opción o con el argumento CLI --sequence.concurrent.

sequence.seed*

Tipo: number
Predeterminado: Date.now()
CLI: --sequence.seed=1000

Define la semilla de aleatorización, si las pruebas se ejecutan en orden aleatorio.

sequence.hooks

Tipo: 'stack' | 'list' | 'parallel'
Predeterminado: 'stack'
CLI: --sequence.hooks=<valor>

Modifica el orden en que se ejecutan los hooks.

stack dispondrá los hooks "after" en orden inverso, los hooks "before" se ejecutarán en el orden en que fueron definidos.
list dispondrá todos los hooks en el orden en que están definidos.
parallel ejecutará los hooks en un solo grupo en paralelo (los hooks en suites padre seguirán ejecutándose antes que los hooks de la suite actual).

TIP

Esta opción no influye en onTestFinished. Siempre se invoca en orden inverso.

sequence.setupFiles

Tipo: 'list' | 'parallel'
Predeterminado: 'parallel'
CLI: --sequence.setupFiles=<valor>

Modifica el orden en que se ejecutan los archivos de preparación.

list ejecutará los archivos de preparación en el orden en que están definidos.
parallel ejecutará los archivos de preparación en paralelo.

typecheck

Opciones para configurar el entorno de prueba de comprobación de tipos.

typecheck.enabled

Tipo: boolean
Predeterminado: false
CLI: --typecheck, --typecheck.enabled

Habilita la comprobación de tipos junto con tus pruebas regulares.

typecheck.only

Tipo: boolean
Predeterminado: false
CLI: --typecheck.only

Se ejecutarán solo las pruebas de comprobación de tipos, cuando la comprobación de tipos está habilitada. Al usar la CLI, esta opción habilitará automáticamente la comprobación de tipos.

typecheck.checker

Tipo: 'tsc' | 'vue-tsc' | string
Predeterminado: tsc

Herramientas a utilizar para la comprobación de tipos. Vitest iniciará un proceso con ciertos parámetros para facilitar el análisis, dependiendo del tipo. El comprobador debe implementar el mismo formato de salida que tsc.

Se requiere tener un paquete instalado para usar el comprobador de tipos:

tsc requiere el paquete typescript
vue-tsc requiere el paquete vue-tsc

También puedes especificar una ruta a un binario personalizado o un nombre de comando que produzca la misma salida que tsc --noEmit --pretty false.

typecheck.include

Tipo: string[]
Predeterminado: ['**/*.{test,spec}-d.?(c|m)[jt]s?(x)']

Patrón glob para archivos que se considerarán archivos de prueba.

typecheck.exclude

Tipo: string[]
Predeterminado: ['**/node_modules/**', '**/dist/**', '**/cypress/**', '**/.{idea,git,cache,output,temp}/**']

Patrón glob para archivos que no se considerarán archivos de prueba.

typecheck.allowJs

Tipo: boolean
Predeterminado: false

Comprueba los archivos JS que tienen el comentario @ts-check. Si lo tienes habilitado en tsconfig, esto no lo anulará.

typecheck.ignoreSourceErrors

Tipo: boolean
Predeterminado: false

No se producirá un fallo si Vitest encuentra errores fuera de los archivos de prueba. Esto ocultará completamente los errores que no sean de prueba.

Por defecto, si Vitest encuentra un error en el código fuente, la suite de pruebas fallará.

typecheck.tsconfig

Tipo: string
Predeterminado: intenta encontrar el tsconfig.json más cercano

Ruta a un archivo tsconfig personalizado, relativa a la raíz del proyecto.

typecheck.spawnTimeout

Tipo: number
Predeterminado: 10_000

Tiempo mínimo en milisegundos que tarda en iniciarse el comprobador de tipos.

slowTestThreshold*

Tipo: number
Predeterminado: 300
CLI: --slow-test-threshold=<número>, --slowTestThreshold=<número>

El número de milisegundos después del cual una prueba o suite se considera lenta y se reporta como tal en los resultados.

chaiConfig

Tipo: { includeStack?, showDiff?, truncateThreshold? }
Predeterminado: { includeStack: false, showDiff: true, truncateThreshold: 40 }

Equivalente a la configuración de Chai.

chaiConfig.includeStack

Tipo: boolean
Predeterminado: false

Determina si la traza de la pila se incluye en el mensaje de error de aserción. El valor predeterminado (false) suprime la traza de la pila en el mensaje de error.

chaiConfig.showDiff

Tipo: boolean
Predeterminado: true

Influye en si el parámetro showDiff debe incluirse o no en los errores de aserción generados. false siempre será false; true será true cuando la aserción solicite que se muestre una diferencia.

chaiConfig.truncateThreshold

Tipo: number
Predeterminado: 40

Define el umbral de longitud para los valores reales y esperados en los errores de aserción. Si se supera este umbral, por ejemplo en el caso de grandes estructuras de datos, el valor se reemplaza por algo como [ Array(3) ] o { Object (prop1, prop2) }. Establécelo en 0 si deseas deshabilitar el truncamiento por completo.

Esta opción de configuración influye en el truncamiento de valores en los títulos de test.each y dentro del mensaje de error de aserción.

bail

Tipo: number
Predeterminado: 0
CLI: --bail=<valor>

Se detiene la ejecución de las pruebas cuando un número específico de pruebas ha fallado.

Por defecto, Vitest ejecuta todos los casos de prueba incluso si algunos de ellos fallan. Esto puede no ser deseable para las compilaciones de CI donde el objetivo son únicamente compilaciones 100% exitosas y se desea detener la ejecución de las pruebas lo antes posible cuando ocurran fallos. La opción bail se puede usar para optimizar las ejecuciones de CI al evitar que se ejecuten más pruebas cuando se han producido fallos.

retry

Tipo: number
Predeterminado: 0
CLI: --retry=<valor>

Se reintentará la prueba un número específico de veces si falla.

onConsoleLog*

Tipo: (log: string, type: 'stdout' | 'stderr') => boolean | void

Controlador personalizado para console.log en las pruebas. Si devuelves false, Vitest suprimirá la impresión del registro en la consola.

Puede ser útil para excluir registros de bibliotecas de terceros.

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
      return !(log === 'mensaje de librería de terceros' && type === 'stdout');
    },
  },
});

onStackTrace*

Tipo: (error: Error, frame: ParsedStack) => boolean | void

Aplica una función de filtrado a cada marco de cada pila de llamadas al manejar errores. El primer argumento, error, es un objeto con las mismas propiedades que un Error estándar, pero no es una instancia de Error propiamente dicha.

Puede ser útil para excluir marcos de pilas de llamadas de bibliotecas de terceros.

import type { ParsedStack } from 'vitest';
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    onStackTrace(error: Error, { file }: ParsedStack): boolean | void {
      // Si hemos encontrado un ReferenceError, se mostrará toda la pila.
      if (error.name === 'ReferenceError') {
        return;
      }

      // Descarta todos los marcos de bibliotecas de terceros.
      if (file.includes('node_modules')) {
        return false;
      }
    },
  },
});

diff

Tipo: string
CLI: --diff=<ruta>

Un objeto DiffOptions o una ruta a un módulo que exporta DiffOptions. Útil si deseas personalizar la visualización de las diferencias.

Por ejemplo, como objeto de configuración:

import { defineConfig } from 'vitest/config';
import c from 'picocolors';

export default defineConfig({
  test: {
    diff: {
      aIndicator: c.bold('--'),
      bIndicator: c.bold('++'),
      omitAnnotationLines: true,
    },
  },
});

O como módulo:

vitest.config.jsvitest.diff.ts

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    diff: './vitest.diff.ts',
  },
});

import type { DiffOptions } from 'vitest';
import c from 'picocolors';

export default {
  aIndicator: c.bold('--'),
  bIndicator: c.bold('++'),
  omitAnnotationLines: true,
} satisfies DiffOptions;

diff.expand

Tipo: boolean
Predeterminado: true
CLI: --diff.expand=false

Expande todas las líneas comunes.

diff.truncateThreshold

Tipo: number
Predeterminado: 0
CLI: --diff.truncateThreshold=<path>

La longitud máxima del resultado de la diferencia que se mostrará. Las diferencias por encima de este umbral serán truncadas. El truncamiento no se aplicará con el valor predeterminado 0.

diff.truncateAnnotation

Tipo: string
Predeterminado: '... El resultado de la diferencia ha sido truncado'
CLI: --diff.truncateAnnotation=<annotation>

Anotación que se genera al final del resultado de la diferencia si se trunca.

diff.truncateAnnotationColor

Tipo: DiffOptionsColor = (arg: string) => string
Predeterminado: noColor = (string: string): string => string

Color de la anotación de truncamiento; por defecto, se muestra sin color.

diff.printBasicPrototype

Tipo: boolean
Predeterminado: false

Imprime el prototipo básico Object y Array en la salida de la diferencia.

diff.maxDepth

Tipo: number
Predeterminado: 20 (o 8 al comparar tipos diferentes)

Limita la profundidad de recursión al imprimir objetos anidados.

fakeTimers

Tipo: FakeTimerInstallOpts

Opciones que Vitest proporcionará a @sinon/fake-timers al usar vi.useFakeTimers().

fakeTimers.now

Tipo: number | Date
Predeterminado: Date.now()

Instala temporizadores falsos con la época Unix especificada.

fakeTimers.toFake

Tipo: ('setTimeout' | 'clearTimeout' | 'setImmediate' | 'clearImmediate' | 'setInterval' | 'clearInterval' | 'Date' | 'nextTick' | 'hrtime' | 'requestAnimationFrame' | 'cancelAnimationFrame' | 'requestIdleCallback' | 'cancelIdleCallback' | 'performance' | 'queueMicrotask')[]
Predeterminado: todo lo disponible globalmente excepto nextTick y queueMicrotask

Un array con nombres de métodos globales y APIs para simular.

Para simular únicamente setTimeout() y nextTick(), define esta propiedad como ['setTimeout', 'nextTick'].

La simulación de nextTick no es compatible cuando se ejecuta Vitest dentro de node:child_process usando --pool=forks. NodeJS emplea process.nextTick internamente en node:child_process y puede bloquearse cuando se simula. La simulación de nextTick es compatible cuando se ejecuta Vitest con --pool=threads.

fakeTimers.loopLimit

Tipo: number
Predeterminado: 10_000

El número máximo de temporizadores que se activarán al invocar vi.runAllTimers().

fakeTimers.shouldAdvanceTime

Tipo: boolean
Predeterminado: false

Configura @sinonjs/fake-timers para que incremente el tiempo simulado automáticamente según el cambio de tiempo real del sistema (por ejemplo, el tiempo simulado se incrementará en 20ms por cada cambio de 20ms en el tiempo real del sistema).

fakeTimers.advanceTimeDelta

Tipo: number
Predeterminado: 20

Solo es relevante cuando se usa con shouldAdvanceTime: true. Incrementa el tiempo simulado en advanceTimeDelta ms por cada cambio de advanceTimeDelta ms en el tiempo real del sistema.

fakeTimers.shouldClearNativeTimers

Tipo: boolean
Predeterminado: true

Configura los temporizadores falsos para que limpien los temporizadores "nativos" (es decir, no falsos) delegando a sus respectivos controladores. Cuando está deshabilitado, podría resultar en un comportamiento potencialmente inesperado si existían temporizadores antes de iniciar la sesión de temporizadores falsos.

workspace*

DEPRECATED

Esta opción está obsoleta y se eliminará en la próxima versión principal. Por favor, usa projects en su lugar.

Tipo: string | TestProjectConfiguration[]
CLI: --workspace=./archivo.js
Predeterminado: vitest.{workspace,projects}.{js,ts,json} cerca del archivo de configuración o de la raíz.

Ruta a un archivo de configuración de workspace relativa a la raíz del proyecto.

A partir de Vitest 3, también puedes definir el array de workspace en la configuración raíz. Si el workspace se especifica manualmente en la configuración, Vitest ignorará el archivo vitest.workspace en la raíz.

projects*

Tipo: TestProjectConfiguration[]
Predeterminado: []

Un arreglo de proyectos.

isolate

Tipo: boolean
Predeterminado: true
CLI: --no-isolate, --isolate=false

Ejecuta pruebas en un entorno aislado. Esta opción no tiene efecto en los grupos de procesos vmThreads y vmForks.

Deshabilitar esta opción podría mejorar el rendimiento si tu código no depende de efectos secundarios (lo cual es común en proyectos con entorno node).

TIP

Puedes deshabilitar el aislamiento para grupos de procesos específicos usando la propiedad poolOptions.

includeTaskLocation

Tipo: boolean
Predeterminado: false

¿Se debe incluir la propiedad location cuando la API de Vitest recibe tareas en los generadores de informes? Si tienes muchas pruebas, esto podría provocar una ligera degradación en el rendimiento.

La propiedad location contiene los valores column y line que indican la posición de test o describe en el archivo original.

Esta opción se activará automáticamente si no la desactivas explícitamente, y estás ejecutando Vitest con:

Vitest UI
o usando el Modo Navegador sin modo sin interfaz gráfica
o usando el Generador de informes HTML

TIP

Esta opción es irrelevante si no se utiliza código personalizado que dependa de ella.

snapshotEnvironment

Tipo: string

Ruta a una implementación de entorno de snapshot personalizada. Esto es útil si estás ejecutando tus pruebas en un entorno que carece de soporte para las APIs de Node.js. Esta opción no tiene ningún efecto en un runner de navegador.

Este objeto debe cumplir con la interfaz SnapshotEnvironment y se utiliza para resolver y leer/escribir archivos de snapshot:

export interface SnapshotEnvironment {
  getVersion: () => string;
  getHeader: () => string;
  resolvePath: (filepath: string) => Promise<string>;
  resolveRawPath: (testPath: string, rawPath: string) => Promise<string>;
  saveSnapshotFile: (filepath: string, snapshot: string) => Promise<void>;
  readSnapshotFile: (filepath: string) => Promise<string | null>;
  removeSnapshotFile: (filepath: string) => Promise<void>;
}

Puedes extender VitestSnapshotEnvironment predeterminado desde el punto de entrada vitest/snapshot si solo necesitas modificar una parte de la API.

WARNING

Esta es una opción de bajo nivel y está destinada únicamente a casos avanzados en los que no se disponga de acceso a las APIs predeterminadas de Node.js.

Si solo necesitas configurar la función de snapshot, utiliza las opciones snapshotFormat o resolveSnapshotPath.

env

Tipo: Partial<NodeJS.ProcessEnv>

Variables de entorno accesibles a través de process.env e import.meta.env durante las pruebas. Estas variables no serán accesibles en el proceso principal (en globalSetup, por ejemplo).

expect

Tipo: ExpectOptions

expect.requireAssertions

Tipo: boolean
Predeterminado: false

Equivalente a invocar expect.hasAssertions() al inicio de cada prueba. Esto asegura que ninguna prueba se apruebe de forma involuntaria.

TIP

Esto solo funciona con el expect de Vitest. Si usas aserciones assert o .should, no se tendrán en cuenta y tu prueba fallará debido a la falta de aserciones expect.

Puedes cambiar el valor de esto modificando vi.setConfig({ expect: { requireAssertions: false } }). La configuración se aplicará a cada invocación expect subsiguiente hasta que vi.resetConfig sea invocado manualmente.

expect.poll

Opciones de configuración global para la función expect.poll. Estas son las mismas opciones que se pueden proporcionar a expect.poll(condition, options).

expect.poll.interval

Tipo: number
Predeterminado: 50

Intervalo de consulta en milisegundos.

expect.poll.timeout

Tipo: number
Predeterminado: 1000

Tiempo de espera máximo para la consulta en milisegundos.

printConsoleTrace

Tipo: boolean
Predeterminado: false

Siempre se imprimirán las pilas de llamadas de la consola al llamar a cualquier método console. Esto es útil con fines de depuración.

attachmentsDir 3.2.0+

Tipo: string
Predeterminado: '.vitest-attachments'

Ruta del directorio para almacenar los archivos adjuntos creados por context.annotate relativa a la raíz del proyecto.

Configuración de Vitest ​

include ​

exclude ​

includeSource ​

name ​

server ​

server.sourcemap ​

server.debug ​

server.debug.dumpModules ​

server.debug.loadDumppedModules ​

server.deps ​

server.deps.external ​

server.deps.inline ​

server.deps.fallbackCJS ​

server.deps.cacheDir ​

deps ​

deps.optimizer ​

deps.optimizer.{mode}.enabled ​

deps.web ​

deps.web.transformAssets ​

deps.web.transformCss ​

deps.web.transformGlobPattern ​

deps.interopDefault ​

deps.moduleDirectories ​

runner ​

benchmark ​

benchmark.include ​

benchmark.exclude ​

benchmark.includeSource ​

benchmark.reporters ​

benchmark.outputFile ​

benchmark.outputJson ​

benchmark.compare ​

alias ​

globals ​

environment ​

environmentOptions ​

environmentMatchGlobs ​

poolMatchGlobs ​

update* ​

watch* ​

watchTriggerPatterns 3.2.0+ * ​

root ​

dir ​

reporters* ​

outputFile* ​

pool* ​

threads* ​

forks* ​

vmThreads* ​

vmForks* ​

poolOptions* ​

poolOptions.threads ​

poolOptions.threads.maxThreads* ​

poolOptions.threads.minThreads* ​

poolOptions.threads.singleThread ​

poolOptions.threads.useAtomics* ​

poolOptions.threads.isolate ​

poolOptions.threads.execArgv* ​

poolOptions.forks ​

poolOptions.forks.maxForks* ​

poolOptions.forks.minForks* ​

poolOptions.forks.isolate ​

poolOptions.forks.singleFork ​

poolOptions.forks.execArgv* ​

poolOptions.vmThreads ​

poolOptions.vmThreads.maxThreads* ​

poolOptions.vmThreads.minThreads* ​

poolOptions.vmThreads.memoryLimit* ​

poolOptions.vmThreads.useAtomics* ​

poolOptions.vmThreads.execArgv* ​

poolOptions.vmForks* ​

poolOptions.vmForks.maxForks* ​

poolOptions.vmForks.minForks* ​

poolOptions.vmForks.memoryLimit* ​

poolOptions.vmForks.execArgv* ​

fileParallelism* ​

maxWorkers* ​

minWorkers* ​

testTimeout ​

Configuración de Vitest

include

exclude

includeSource

name

server

server.sourcemap

server.debug

server.debug.dumpModules

server.debug.loadDumppedModules

server.deps

server.deps.external

server.deps.inline

server.deps.fallbackCJS

server.deps.cacheDir

deps

deps.optimizer

deps.optimizer.{mode}.enabled

deps.web

deps.web.transformAssets

deps.web.transformCss

deps.web.transformGlobPattern

deps.interopDefault

deps.moduleDirectories

runner

benchmark

benchmark.include

benchmark.exclude

benchmark.includeSource

benchmark.reporters

benchmark.outputFile

benchmark.outputJson

benchmark.compare

alias

globals

environment

environmentOptions

environmentMatchGlobs

poolMatchGlobs

update*

watch*

watchTriggerPatterns 3.2.0+ *

root

dir

reporters*

outputFile*

pool*

threads*

forks*

vmThreads*

vmForks*

poolOptions*

poolOptions.threads

poolOptions.threads.maxThreads*

poolOptions.threads.minThreads*

poolOptions.threads.singleThread

poolOptions.threads.useAtomics*

poolOptions.threads.isolate

poolOptions.threads.execArgv*

poolOptions.forks

poolOptions.forks.maxForks*

poolOptions.forks.minForks*

poolOptions.forks.isolate

poolOptions.forks.singleFork

poolOptions.forks.execArgv*

poolOptions.vmThreads

poolOptions.vmThreads.maxThreads*

poolOptions.vmThreads.minThreads*

poolOptions.vmThreads.memoryLimit*

poolOptions.vmThreads.useAtomics*

poolOptions.vmThreads.execArgv*

poolOptions.vmForks*

poolOptions.vmForks.maxForks*

poolOptions.vmForks.minForks*

poolOptions.vmForks.memoryLimit*

poolOptions.vmForks.execArgv*

fileParallelism*

maxWorkers*

minWorkers*

testTimeout