API Avanzadas

WARNING

Esta guía detalla las API avanzadas para ejecutar pruebas mediante un script de Node.js. Si solo buscas ejecutar pruebas, es probable que no necesites estas funcionalidades. Están diseñadas principalmente para autores de librerías.

Puedes importar cualquier método desde el punto de entrada vitest/node.

startVitest

function startVitest(
  mode: VitestRunMode,
  cliFilters: string[] = [],
  options: CliOptions = {},
  viteOverrides?: ViteUserConfig,
  vitestOptions?: VitestOptions
): Promise<Vitest>;

Puedes iniciar la ejecución de pruebas de Vitest utilizando su API de Node.js:

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.

Si el modo de vigilancia no está habilitado, Vitest invocará automáticamente el método close.

Si el modo de vigilancia está habilitado y la terminal soporta TTY, Vitest registrará atajos de consola.

Puedes proporcionar una lista de filtros como segundo argumento. Vitest solo ejecutará las pruebas cuyas rutas de archivo contengan al menos una de las cadenas proporcionadas.

Además, puedes usar el tercer argumento para pasar argumentos de CLI, los cuales sobrescribirán cualquier opción de configuración de prueba. Alternativamente, puedes pasar la configuración completa de Vite como cuarto argumento, lo que tendrá prioridad sobre cualquier otra opción definida por el usuario.

Después de ejecutar las pruebas, puedes obtener los resultados utilizando la API state.getTestModules:

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

const vitest = await startVitest('test');

console.log(vitest.state.getTestModules()); // [TestModule]

TIP

La guía "Ejecutando Pruebas" incluye un ejemplo de uso.

createVitest

function createVitest(
  mode: VitestRunMode,
  options: CliOptions,
  viteOverrides: ViteUserConfig = {},
  vitestOptions: VitestOptions = {}
): Promise<Vitest>;

Puedes crear una instancia de Vitest utilizando la función createVitest. Esta función devuelve la misma instancia de Vitest que startVitest, pero no inicia las pruebas ni valida los paquetes instalados.

import { createVitest } from 'vitest/node';

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

TIP

La guía "Ejecutando Pruebas" incluye un ejemplo de uso.

resolveConfig

function resolveConfig(
  options: UserConfig = {},
  viteOverrides: ViteUserConfig = {}
): Promise<{
  vitestConfig: ResolvedConfig;
  viteConfig: ResolvedViteConfig;
}>;

Este método resuelve la configuración basándose en parámetros personalizados. Si no se proporcionan parámetros, la raíz será process.cwd().

import { resolveConfig } from 'vitest/node';

// vitestConfig solo contiene propiedades "test" resueltas
const { vitestConfig, viteConfig } = await resolveConfig({
  mode: 'custom',
  configFile: false,
  resolve: {
    conditions: ['custom'],
  },
  test: {
    setupFiles: ['/my-setup-file.js'],
    pool: 'threads',
  },
});

INFO

Debido a la forma en que funciona createServer de Vite, Vitest debe resolver la configuración durante el hook configResolve del plugin. Por lo tanto, este método no se utiliza internamente y se expone únicamente como una API pública.

Si pasas la configuración a las API startVitest o createVitest, Vitest volverá a resolver la configuración.

WARNING

resolveConfig no resuelve los projects. Para resolver las configuraciones de los proyectos, Vitest requiere un servidor Vite en funcionamiento.

Ten en cuenta también que viteConfig.test no se resolverá completamente. Si necesitas la configuración de Vitest, utiliza vitestConfig en su lugar.

parseCLI

function parseCLI(
  argv: string | string[],
  config: CliParseOptions = {}
): {
  filter: string[];
  options: CliOptions;
};

Puedes usar este método para analizar los argumentos de la CLI. Acepta una cadena (donde los argumentos se dividen 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 las options que puedes pasar posteriormente a los métodos createVitest o startVitest.

import { parseCLI } from 'vitest/node';

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

result.options;
// {
//   coverage: { enabled: true },
//   browser: { name: 'chrome', enabled: true }
// }

result.filter;
// ['./files.ts']