API de Node

WARNING

Vitest ofrece una API experimental privada. Los cambios que introduzcan incompatibilidades podrían no seguir SemVer, por favor, fija la versión de Vitest al usarla.

startVitest

Puedes comenzar a ejecutar las pruebas de Vitest usando su API de Node:

import { startVitest } from 'vitest/node';

const vitest = await startVitest('test');

await vitest?.close();

La función startVitest devuelve una instancia de Vitest si las pruebas se pueden iniciar correctamente. Devuelve undefined si ocurre lo siguiente:

• Vitest no encuentra el paquete vite (que normalmente se instala con Vitest).
• Si la cobertura está habilitada y el modo de ejecución es "test", pero no se ha instalado el paquete de cobertura (@vitest/coverage-v8 o @vitest/coverage-istanbul).
• Si el paquete de entorno no está instalado (jsdom/happy-dom/@edge-runtime/vm).

Si se devuelve undefined o las pruebas fallan durante la ejecución, Vitest establece process.exitCode a 1.

Si el modo de observación no está habilitado, Vitest invocará el método close.

Si el modo de observación está habilitado y la terminal soporta TTY, Vitest registrará accesos directos de consola.

Puedes proporcionar una lista de filtros como segundo argumento. Vitest solo ejecutará las pruebas cuya ruta de archivo contenga al menos una de las cadenas proporcionadas.

Además, puedes usar el tercer argumento para pasar argumentos de la CLI, que sobrescribirán cualquier opción de configuración de prueba.

Alternativamente, puedes pasar la configuración completa de Vite como cuarto argumento, que tendrá prioridad sobre cualquier otra opción definida por el usuario.

Después de ejecutar las pruebas, puedes obtener los resultados a través de la API state.getFiles:

const vitest = await startVitest('test');

console.log(vitest.state.getFiles()); // [{ type: 'file', ... }]

Desde Vitest 2.1, se recomienda usar la API de "Tareas Reportadas" junto con state.getFiles. En el futuro, Vitest devolverá esos objetos directamente:

const vitest = await startVitest('test');

const [fileTask] = vitest.state.getFiles();
const testFile = vitest.state.getReportedEntity(fileTask);

createVitest

Puedes crear una instancia de Vitest usando la función createVitest. Devuelve la misma instancia de Vitest que startVitest, aunque no inicia las pruebas ni valida los paquetes instalados.

import { createVitest } from 'vitest/node';

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

parseCLI

Puedes utilizar este método para analizar los argumentos de la CLI. Acepta una cadena (donde los argumentos están separados por un solo espacio) o un array de cadenas con argumentos de la CLI en el mismo formato que utiliza la CLI de Vitest. Devuelve un filtro y options que puedes pasar posteriormente a los métodos createVitest o startVitest.

import { parseCLI } from 'vitest/node';

parseCLI('vitest ./files.ts --coverage --browser=chrome');

Vitest

La instancia de Vitest requiere el modo actual. Puede ser:

• test cuando se ejecutan pruebas en tiempo de ejecución.
• benchmark cuando se ejecutan benchmarks.

mode

test

El modo de prueba solo invocará las funciones dentro de test o it, y lanzará un error cuando se encuentre bench. Este modo usa las opciones include y exclude en la configuración para encontrar los archivos de prueba.

benchmark

El modo de pruebas de rendimiento llama a las funciones bench y lanza un error si encuentra test o it. Este modo utiliza las opciones benchmark.include y benchmark.exclude en la configuración para encontrar los archivos de pruebas de rendimiento.

start

Puedes comenzar a ejecutar pruebas o benchmarks con el método start. Puedes pasar un array de cadenas para filtrar los archivos de prueba.

provide

Vitest expone el método provide, que es una abreviatura de vitest.getCoreWorkspaceProject().provide. Con este método, puedes transferir valores desde el hilo principal a las pruebas. Todos los valores se comprueban con structuredClone antes de almacenarse, pero los valores en sí mismos no se clonan.

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

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

Para una mayor seguridad de tipos, te recomendamos ampliar 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 WorkspaceProject, por lo que está limitado a ese proyecto específico. Sin embargo, todos los proyectos heredan los valores del proyecto central, lo que convierte a vitest.provide en una forma universal de pasar valores a las pruebas.

TIP

Este método también está disponible para los archivos de configuración global en los casos en los que no quieras usar la API pública.

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