API de Vitest

La instancia de Vitest requiere el modo de ejecución actual. Este puede ser:

• test al ejecutar pruebas en tiempo de ejecución.
• benchmark al ejecutar pruebas de rendimiento. experimental

Novedades de Vitest 3

Vitest 3 avanza hacia la estabilización de su API pública. Para lograrlo, hemos desaprobado y eliminado algunos de los métodos previamente públicos de la clase Vitest. Las siguientes APIs ahora son privadas:

• configOverride (usar setGlobalTestNamePattern o enableSnapshotUpdate)
• coverageProvider
• filenamePattern
• runningPromise
• closingPromise
• isCancelling
• coreWorkspaceProject
• resolvedProjects
• _browserLastPort
• _options
• reporters
• vitenode
• runner
• pool
• setServer
• _initBrowserServers
• rerunTask
• changeProjectName
• changeNamePattern
• changeFilenamePattern
• rerunFailed
• _createRootProject (renombrado a _ensureRootProject, pero sigue siendo privado)
• filterTestsBySource (esto se movió a la nueva instancia interna vitest.specifications)
• runFiles (usar runTestSpecifications en su lugar)
• onAfterSetServer

Las siguientes APIs han sido desaprobadas:

• invalidates
• changedTests (usar onFilterWatchedSpecification en su lugar)
• server (usar vite en su lugar)
• getProjectsByTestFile (usar getModuleSpecifications en su lugar)
• getFileWorkspaceSpecs (usar getModuleSpecifications en su lugar)
• getModuleProjects (filtrar por this.projects manualmente)
• updateLastChanged (renombrado a invalidateFile)
• globTestSpecs (usar globTestSpecifications en su lugar)
• globTestFiles (usar globTestSpecifications en su lugar)
• listFile (usar getRelevantTestSpecifications en su lugar)

mode

test

El modo de prueba solo ejecuta las funciones definidas con test o it, y arroja un error si se encuentra bench. Este modo utiliza las opciones include y exclude de la configuración para encontrar archivos de prueba.

benchmark experimental

El modo benchmark ejecuta las funciones bench y arroja un error si encuentra test o it. Este modo utiliza las opciones benchmark.include y benchmark.exclude de la configuración para encontrar archivos de benchmark.

config

La configuración raíz (o global). Si se definen proyectos, estos se referirán a ella como globalConfig.

WARNING

Esta es la configuración de Vitest, no extiende la configuración de Vite. Solo contiene los valores resueltos de la propiedad test.

vite

Esto es un ViteDevServer a nivel global.

state experimental

WARNING

La state pública es una API experimental (excepto vitest.state.getReportedEntity). Los cambios importantes podrían no seguir SemVer, por favor, bloquee la versión de Vitest cuando la utilice.

El estado global guarda información sobre las pruebas actuales. Utiliza la misma API de @vitest/runner por defecto, pero recomendamos usar la API de Tareas Reportadas en su lugar, llamando a state.getReportedEntity() en la API de @vitest/runner:

const task = vitest.state.idMap.get(taskId); // old API
const testCase = vitest.state.getReportedEntity(task); // new API

En el futuro, la API antigua ya no se expondrá.

snapshot

El gestor global de instantáneas (snapshots). Vitest gestiona todas las instantáneas utilizando el método snapshot.add.

Puede obtener el resumen más reciente de las instantáneas mediante la propiedad vitest.snapshot.summary.

cache

Administrador de caché que almacena información sobre los últimos resultados de las pruebas y las estadísticas de los archivos de prueba. Dentro de Vitest, esto solo es utilizado por el secuenciador predeterminado para ordenar las pruebas.

projects

Un arreglo de proyectos de prueba del usuario. Si el usuario no especificó ninguno, este arreglo solo contendrá un proyecto raíz.

Vitest garantizará que siempre haya al menos un proyecto en este arreglo. Si el usuario especifica un nombre de --project inexistente, Vitest arrojará un error antes de que se defina este arreglo.

getRootProject

function getRootProject(): TestProject;

Esto retorna el proyecto de prueba raíz. El proyecto raíz generalmente no ejecuta ninguna prueba y no se incluye en vitest.projects a menos que el usuario incluya explícitamente la configuración raíz en su configuración, o si no hay proyectos definidos en absoluto.

El objetivo principal del proyecto raíz es establecer la configuración global. De hecho, rootProject.config hace referencia a rootProject.globalConfig y vitest.config directamente:

(rootProject.config === rootProject.globalConfig) === rootProject.vitest.config;

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

Vitest ofrece el método provide, que es un atajo para vitest.getRootProject().provide. Con este método, puede pasar valores desde el hilo principal a las pruebas. Todos los valores se validan con structuredClone antes de ser almacenados, pero los valores en sí no se clonan.

Para recibir los valores en la prueba, debe importar el método inject desde el punto de entrada de vitest:

import { inject } from 'vitest';
const port = inject('wsPort'); // 3000

Para una mejor seguridad de tipos, le animamos a extender el tipo de ProvidedContext:

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test', {
  watch: false,
});
vitest.provide('wsPort', 3000);

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

WARNING

Técnicamente, provide es un método de TestProject, por lo tanto, está limitado al proyecto específico. Sin embargo, todos los proyectos heredan los valores del proyecto raíz, lo que convierte a vitest.provide en un método universal para pasar valores a las pruebas.

getProvidedContext

function getProvidedContext(): ProvidedContext;

Este método devuelve el objeto de contexto raíz. Es un atajo para vitest.getRootProject().getProvidedContext.

getProjectByName

function getProjectByName(name: string): TestProject;

Este método devuelve el proyecto por su nombre. Es similar a llamar a vitest.projects.find.

WARNING

En caso de que el proyecto no exista, este método devolverá el proyecto raíz; asegúrese de verificar los nombres nuevamente para confirmar que el proyecto devuelto es el que busca.

Si el usuario no personalizó un nombre, Vitest asignará una cadena vacía como nombre.

globTestSpecifications

function globTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Este método construye nuevas especificaciones de prueba al recopilar todas las pruebas en cada proyecto utilizando project.globTestFiles. Acepta filtros de cadena para hacer coincidir los archivos de prueba; estos son los mismos filtros que admite la CLI.

Este método guarda automáticamente en caché todas las especificaciones de prueba. Cuando llame a getModuleSpecifications en la siguiente ocasión, devolverá las mismas especificaciones a menos que se haya llamado a clearSpecificationsCache previamente.

WARNING

A partir de Vitest 3, es posible tener múltiples especificaciones de prueba con el mismo ID de módulo (ruta de archivo) si poolMatchGlob utiliza varios pools o si typecheck está habilitado. Esta funcionalidad se eliminará en Vitest 4.

const specifications = await vitest.globTestSpecifications(['my-filter']);
// [TestSpecification{ moduleId: '/tests/my-filter.test.ts' }]
console.log(specifications);

getRelevantTestSpecifications

function getRelevantTestSpecifications(
  filters?: string[]
): Promise<TestSpecification[]>;

Este método determina cada especificación de prueba al llamar a project.globTestFiles. Acepta filtros de cadena para hacer coincidir los archivos de prueba; estos son los mismos filtros que admite la CLI. Si se especificó la opción --changed, la lista se filtrará para incluir solo los archivos que cambiaron. getRelevantTestSpecifications no ejecuta ningún archivo de prueba.

WARNING

Este método puede ser lento porque necesita aplicar los filtros de la opción --changed. No lo utilice si solo necesita una lista de archivos de prueba.

• Si necesita obtener la lista de especificaciones para archivos de prueba conocidos, use getModuleSpecifications en su lugar.
• Si necesita obtener la lista de todos los archivos de prueba posibles, use globTestSpecifications.

mergeReports

function mergeReports(directory?: string): Promise<TestRunResult>;

Fusiona informes de múltiples ejecuciones encontrados en el directorio especificado (valor de --merge-reports si no se especifica). Este valor también se puede establecer en config.mergeReports (por defecto, leerá de la carpeta .vitest-reports).

Tenga en cuenta que la ruta del directory siempre se resolverá en relación con el directorio de trabajo.

Este método es llamado automáticamente por startVitest si config.mergeReports está configurado.

collect

function collect(filters?: string[]): Promise<TestRunResult>;

Ejecuta archivos de prueba sin invocar los callbacks de prueba. collect devuelve errores no controlados y un arreglo de módulos de prueba. Acepta filtros de cadena para hacer coincidir los archivos de prueba; estos son los mismos filtros que admite la CLI.

Este método resuelve las especificaciones de las pruebas basándose en los valores de include, exclude e includeSource de la configuración. Lea más en project.globTestFiles. Si se especificó la opción --changed, la lista se filtrará para incluir solo los archivos que cambiaron.

WARNING

Cabe destacar que Vitest no utiliza análisis estático para recopilar pruebas. Vitest ejecutará cada archivo de prueba de forma aislada, tal como ejecuta las pruebas regulares.

Esto hace que este método sea muy lento, a menos que desactive el aislamiento antes de recopilar las pruebas.

start

function start(filters?: string[]): Promise<TestRunResult>;

Inicializa los reportadores, el proveedor de cobertura y ejecuta las pruebas. Este método acepta filtros de cadena para hacer coincidir los archivos de prueba; estos son los mismos filtros que admite la CLI.

WARNING

Este método no debe llamarse si vitest.init() también se ha invocado. Utilice runTestSpecifications o rerunTestSpecifications en su lugar si necesita ejecutar pruebas después de que Vitest haya sido inicializado.

Este método es llamado automáticamente por startVitest si config.mergeReports y config.standalone no están configurados.

init

function init(): Promise<void>;

Inicializa los reportadores y el proveedor de cobertura. Este método no ejecuta ninguna prueba. Si se proporciona la opción --watch, Vitest seguirá ejecutando las pruebas modificadas incluso si no se llamó a este método.

Internamente, este método solo se llama si la opción --standalone está habilitada.

WARNING

Este método no debe llamarse si vitest.start() también se ha invocado.

Este método es llamado automáticamente por startVitest si config.standalone está configurado.

getModuleSpecifications

function getModuleSpecifications(moduleId: string): TestSpecification[];

Devuelve una lista de especificaciones de prueba relacionadas con el ID del módulo. El ID ya debe corresponder a una ruta de archivo absoluta. Si el ID no coincide con los patrones include o includeSource, el arreglo devuelto estará vacío.

Este método puede devolver especificaciones ya almacenadas en caché basadas en moduleId y pool. Sin embargo, tenga en cuenta que project.createSpecification siempre devuelve una nueva instancia y no se almacena en caché automáticamente. Las especificaciones se almacenan en caché automáticamente cuando se llama a runTestSpecifications.

WARNING

A partir de Vitest 3, este método utiliza una caché para verificar si el archivo es una prueba. Para asegurarse de que la caché no esté vacía, invoque globTestSpecifications al menos una vez.

clearSpecificationsCache

function clearSpecificationsCache(moduleId?: string): void;

Vitest almacena automáticamente en caché las especificaciones de prueba para cada archivo cuando se llama a globTestSpecifications o runTestSpecifications. Este método borra la caché para el archivo dado o toda la caché, dependiendo del primer argumento.

runTestSpecifications

function runTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Este método ejecuta cada prueba basándose en las especificaciones recibidas. El segundo argumento, allTestsRun, es utilizado por el proveedor de cobertura para determinar si necesita instrumentar la cobertura en cada archivo en la raíz (esto solo es relevante si la cobertura está habilitada y coverage.all está configurado en true).

WARNING

Este método no activa los callbacks onWatcherRerun, onWatcherStart y onTestsRerun. Si está volviendo a ejecutar pruebas debido a un cambio en el archivo, considere utilizar rerunTestSpecifications en su lugar.

rerunTestSpecifications

function rerunTestSpecifications(
  specifications: TestSpecification[],
  allTestsRun = false
): Promise<TestRunResult>;

Este método dispara los eventos reporter.onWatcherRerun y onTestsRerun, y luego ejecuta las pruebas con runTestSpecifications. Si no hubo errores en el proceso principal, emitirá el evento reporter.onWatcherStart.

updateSnapshot

function updateSnapshot(files?: string[]): Promise<TestRunResult>;

Actualiza las instantáneas de los archivos especificados. Si no se proporcionan archivos, actualizará las instantáneas de los archivos con pruebas fallidas y las instantáneas obsoletas.

collectTests

function collectTests(
  specifications: TestSpecification[]
): Promise<TestRunResult>;

Ejecuta archivos de prueba sin invocar los callbacks de prueba. collectTests devuelve errores no controlados y un arreglo de módulos de prueba.

Este método funciona exactamente igual que collect, pero debe proporcionar las especificaciones de prueba directamente.

WARNING

Tenga en cuenta que Vitest no utiliza análisis estático para recopilar pruebas. Vitest ejecutará cada archivo de prueba de forma aislada, tal como ejecuta las pruebas regulares.

Esto hace que este método sea muy lento, a menos que desactive el aislamiento antes de recopilar las pruebas.

cancelCurrentRun

function cancelCurrentRun(reason: CancelReason): Promise<void>;

Este método cancelará de forma controlada todas las pruebas en curso. Esperará a que las pruebas iniciadas terminen de ejecutarse y no ejecutará las pruebas que estaban programadas para ejecutarse pero que aún no han comenzado.

setGlobalTestNamePattern

function setGlobalTestNamePattern(pattern: string | RegExp): void;

Este método anula el patrón global de nombres de prueba.

WARNING

Este método no inicia la ejecución de ninguna prueba. Para ejecutar pruebas con el patrón actualizado, llame a runTestSpecifications.

resetGlobalTestNamePattern

function resetGlobalTestNamePattern(): void;

Este método restablece el patrón de nombres de prueba. Esto significa que Vitest no omitirá ninguna prueba.

WARNING

Este método no inicia la ejecución de ninguna prueba. Para ejecutar pruebas sin un patrón, llame a runTestSpecifications.

enableSnapshotUpdate

function enableSnapshotUpdate(): void;

Habilita el modo que permite la actualización de instantáneas al ejecutar pruebas. Cada prueba que se ejecute después de la llamada a este método actualizará las instantáneas. Para deshabilitar el modo, llame a resetSnapshotUpdate.

WARNING

Este método no inicia la ejecución de ninguna prueba. Para actualizar las instantáneas, ejecute las pruebas con runTestSpecifications.

resetSnapshotUpdate

function resetSnapshotUpdate(): void;

Deshabilita el modo que permite actualizar instantáneas al ejecutar pruebas. Este método no inicia la ejecución de ninguna prueba.

invalidateFile

function invalidateFile(filepath: string): void;

Este método invalida el archivo en la caché de todos los proyectos. Es principalmente útil si depende de su propio observador, ya que la caché de Vite persiste en la memoria.

DANGER

Si deshabilita el observador de Vitest pero mantiene Vitest en ejecución, es importante borrar manualmente la caché con este método, ya que no hay otra forma de deshabilitar la caché. Este método también invalidará los módulos que importan el archivo.

import

function import<T>(moduleId: string): Promise<T>

Importa un archivo utilizando el cargador de módulos de Vite. El archivo será transformado por Vite aplicando la configuración global y ejecutado en un contexto separado. Tenga en cuenta que moduleId será relativo a config.root.

DANGER

project.import reutiliza el grafo de módulos de Vite, lo que significa que importar el mismo módulo mediante una importación regular devolverá un módulo diferente:

import * as staticExample from './example.js';
const dynamicExample = await vitest.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

Internamente, Vitest utiliza este método para importar configuraciones globales, proveedores de cobertura personalizados y generadores de informes personalizados. Esto implica que todos ellos comparten el mismo grafo de módulos siempre que pertenezcan al mismo servidor de Vite.

close

function close(): Promise<void>;

Cierra todos los proyectos y los recursos asociados a ellos. Este método solo se puede invocar una vez; la promesa de cierre se almacena en caché hasta que el servidor se reinicia.

exit

function exit(force = false): Promise<void>;

Cierra todos los proyectos y finaliza el proceso. Si force se establece en true, el proceso finalizará inmediatamente después de cerrar los proyectos.

Este método también forzará la llamada a process.exit() si el proceso sigue activo después de config.teardownTimeout milisegundos.

shouldKeepServer

function shouldKeepServer(): boolean;

Este método devolverá true si el servidor debe seguir ejecutándose después de que las pruebas hayan finalizado. Esto generalmente significa que el modo watch estaba habilitado.

onServerRestart

function onServerRestart(fn: OnServerRestartHandler): void;

Registra un controlador que se invocará cuando el servidor se reinicie debido a un cambio de configuración.

onCancel

function onCancel(fn: (reason: CancelReason) => Awaitable<void>): void;

Registra un controlador que se invocará cuando la ejecución de la prueba se cancele con vitest.cancelCurrentRun.

onClose

function onClose(fn: () => Awaitable<void>): void;

Registra un controlador que se invocará cuando el servidor se cierre.

onTestsRerun

function onTestsRerun(fn: OnTestsRerunHandler): void;

Registra un controlador que se invocará cuando las pruebas se estén ejecutando de nuevo. Las pruebas pueden volver a ejecutarse cuando se llama a rerunTestSpecifications manualmente o cuando se cambia un archivo y el watcher integrado programa una nueva ejecución.

onFilterWatchedSpecification

function onFilterWatchedSpecification(
  fn: (specification: TestSpecification) => boolean
): void;

Registra un controlador que se invocará cuando se cambie un archivo. Este callback debe devolver true o false, indicando si el archivo de prueba necesita ser ejecutado de nuevo.

Con este método, puede integrarse en la lógica del watcher predeterminado para retrasar o descartar pruebas que el usuario no desea seguir en ese momento:

const continuesTests: string[] = [];

myCustomWrapper.onContinuesRunEnabled(testItem =>
  continuesTests.push(item.fsPath)
);

vitest.onFilterWatchedSpecification(specification =>
  continuesTests.includes(specification.moduleId)
);

Vitest puede crear diferentes especificaciones para el mismo archivo dependiendo de las opciones pool o locations, por lo tanto, no confíe en la referencia. Vitest también puede devolver especificaciones almacenadas en caché por vitest.getModuleSpecifications; la caché se basa en moduleId y pool. Tenga en cuenta que project.createSpecification siempre devuelve una nueva instancia.

matchesProjectFilter 3.1.0+

function matchesProjectFilter(name: string): boolean;

Verifica si el nombre coincide con el filtro de proyecto actual. Si no hay un filtro de proyecto, esto siempre devolverá true.

No es posible cambiar programáticamente la opción CLI --project.