Ejecución de Pruebas

WARNING

Esta guía detalla el uso de la API avanzada para ejecutar pruebas mediante un script de Node.js. Si tu objetivo es simplemente ejecutar pruebas, es probable que esta API no sea necesaria. Su uso principal está dirigido a desarrolladores de bibliotecas.

Los cambios significativos en esta API experimental podrían no adherirse a SemVer. Por favor, especifica la versión de Vitest cuando la utilices.

Vitest expone dos métodos para su inicialización:

• startVitest: Inicializa Vitest, verifica la instalación de los paquetes necesarios y ejecuta las pruebas de inmediato.
• createVitest: Solo inicializa Vitest, sin ejecutar pruebas.

startVitest

import { startVitest } from 'vitest/node';

const vitest = await startVitest(
  'test',
  [], // Filtros de CLI
  {}, // Sobreescritura de la configuración de pruebas
  {}, // Sobreescritura de la configuración de Vite
  {} // Opciones personalizadas de Vitest
);
const testModules = vitest.state.getTestModules();
for (const testModule of testModules) {
  console.log(testModule.moduleId, testModule.ok() ? 'passed' : 'failed');
}

TIP

Las API de TestModule, TestSuite y TestCase no son experimentales y siguen SemVer desde Vitest 2.1.

createVitest

Crea una instancia de Vitest sin ejecutar pruebas.

El método createVitest no verifica la instalación de los paquetes necesarios. Tampoco respeta las configuraciones config.standalone o config.mergeReports. Vitest no se cerrará automáticamente, incluso si watch está deshabilitado.

import { createVitest } from 'vitest/node';

const vitest = await createVitest(
  'test',
  {}, // Sobreescritura de la configuración de pruebas
  {}, // Sobreescritura de la configuración de Vite
  {} // Opciones personalizadas de Vitest
);

// Se invoca cuando se llama a `vitest.cancelCurrentRun()`
vitest.onCancel(() => {});
// Se invoca durante la llamada a `vitest.close()`
vitest.onClose(() => {});
// Se invoca cuando Vitest vuelve a ejecutar archivos de prueba
vitest.onTestsRerun(files => {});

try {
  // Esto establecerá process.exitCode en 1 si las pruebas fallan,
  // y no cerrará el proceso automáticamente.
  await vitest.start(['my-filter']);
} catch (err) {
  // Esto puede lanzar errores como:
  // "FilesNotFoundError" si no se encontraron archivos.
  // "GitNotFoundError" si se usa `--changed` y el repositorio no está inicializado.
} finally {
  await vitest.close();
}

Si deseas mantener la instancia de Vitest activa, asegúrate de llamar al menos a init. Esto inicializará los informes y el proveedor de cobertura, pero no ejecutará ninguna prueba. También se recomienda habilitar el modo watch incluso si no tienes la intención de usar el observador de Vitest, pero quieres mantener la instancia en ejecución. Vitest depende de este indicador para que algunas de sus características funcionen correctamente en un proceso continuo.

Una vez inicializados los informes, utiliza runTestSpecifications o rerunTestSpecifications para ejecutar pruebas si se requiere una ejecución manual:

watcher.on('change', async file => {
  const specifications = vitest.getModuleSpecifications(file);
  if (specifications.length) {
    vitest.invalidateFile(file);
    // Puedes usar runTestSpecifications si los hooks "reporter.onWatcher*"
    // no deben ser invocados.
    await vitest.rerunTestSpecifications(specifications);
  }
});

WARNING

El ejemplo anterior ilustra un caso de uso potencial si deshabilitas el comportamiento predeterminado del modo de observación. Por defecto, Vitest ya reejecuta las pruebas si los archivos cambian.

Ten en cuenta también que getModuleSpecifications no resolverá los archivos de prueba si no han sido procesados previamente por globTestSpecifications. Si el archivo acaba de ser creado, utiliza project.matchesGlobPattern en su lugar:

watcher.on('add', async file => {
  const specifications = [];
  for (const project of vitest.projects) {
    if (project.matchesGlobPattern(file)) {
      specifications.push(project.createSpecification(file));
    }
  }

  if (specifications.length) {
    await vitest.rerunTestSpecifications(specifications);
  }
});

Para deshabilitar el observador, puedes pasar server.watch: null a partir de Vite 5.3 o server.watch: { ignored: ['*/*'] } a una configuración de Vite:

await createVitest(
  'test',
  {},
  {
    plugins: [
      {
        name: 'stop-watcher',
        async configureServer(server) {
          await server.watcher.close();
        },
      },
    ],
    server: {
      watch: null,
    },
  }
);