TestProject 3.0.0+

WARNING

Esta guía describe la API avanzada de Node.js. Si solo desea definir proyectos, consulte la guía "Proyectos de prueba".

name

El nombre es una cadena única asignada por el usuario o determinada por Vitest. Si el usuario no proporciona un nombre, Vitest intenta cargar un package.json en la raíz del proyecto y toma la propiedad name de allí. Si no se encuentra un package.json, Vitest usa por defecto el nombre de la carpeta. Los proyectos inline utilizan números como nombres (convertidos a cadena).

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // con package.json "@pkg/server"
      './utils', // sin archivo package.json
      {
        // no se personaliza el nombre
        test: {
          pool: 'threads',
        },
      },
      {
        // personaliza el nombre
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

Si el proyecto raíz no forma parte de los proyectos definidos por el usuario, su name no se resolverá.

vitest

vitest hace referencia a la instancia global de Vitest.

serializedConfig

Esta es la configuración que reciben los procesos de prueba. Vitest serializa la configuración manualmente, eliminando todas las funciones y propiedades que no se pueden serializar. Dado que este valor está disponible tanto en las pruebas como en el nodo, su tipo se exporta desde el punto de entrada principal.

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

La propiedad serializedConfig es un getter. Cada vez que se accede a ella, Vitest serializa la configuración de nuevo en caso de que haya cambiado. Esto también significa que siempre devuelve una referencia diferente:

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

La configuración de prueba con la que se inicializó Vitest. Si este es el proyecto raíz, globalConfig y config harán referencia al mismo objeto. Esta configuración es útil para valores que no pueden establecerse a nivel de proyecto, como coverage o reporters.

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

vitest.config === vitest.projects[0].globalConfig;

config

Esta es la configuración de prueba resuelta del proyecto.

hash 3.2.0+

El hash único de este proyecto. Este valor es consistente entre las reejecuciones.

Se basa en la raíz del proyecto y su nombre. Cabe señalar que la ruta raíz varía entre diferentes sistemas operativos, por lo que el hash también será diferente.

vite

Este es el ViteDevServer asociado al proyecto. Todos los proyectos tienen sus propios servidores Vite.

browser

Este valor solo se definirá si las pruebas se están ejecutando en el navegador. Si browser está habilitado, pero las pruebas aún no se han ejecutado, este será undefined. Si necesita comprobar si el proyecto admite pruebas en el navegador, use el método project.isBrowserEnabled().

WARNING

La API del navegador es aún más experimental y no se adhiere a SemVer. La API del navegador se estandarizará por separado del resto de las APIs.

provide

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

Una forma de proporcionar valores personalizados a las pruebas, además del campo config.provide. Todos los valores se validan con structuredClone antes de ser almacenados, pero los del providedContext no se clonan.

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

Los valores pueden proporcionarse dinámicamente. El valor proporcionado en las pruebas se actualizará en su próxima ejecución.

TIP

Este método también está disponible para archivos de configuración global en situaciones donde no se pueda usar la API pública:

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

getProvidedContext

function getProvidedContext(): ProvidedContext;

Devuelve el objeto de contexto. Cada proyecto también hereda el contexto global establecido por vitest.provide.

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

Los valores de contexto del proyecto siempre tendrán prioridad sobre el contexto del proyecto raíz.

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

Crea una especificación de prueba que se puede usar en vitest.runTestSpecifications. La especificación define el alcance del archivo de prueba a un project específico y a las locations de prueba (opcional). Las ubicaciones de prueba son líneas de código donde se define la prueba en el código fuente. Si se proporcionan ubicaciones, Vitest solo ejecutará las pruebas definidas en esas líneas. Tenga en cuenta que si se define testNamePattern, también se aplicará.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // líneas opcionales de la prueba
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification espera un ID de módulo resuelto. No resuelve automáticamente el archivo ni verifica que exista en el sistema de archivos.

También cabe destacar que project.createSpecification siempre devuelve una nueva instancia.

isRootProject

function isRootProject(): boolean;

Comprueba si el proyecto actual es el proyecto raíz. También puede obtener el proyecto raíz llamando a vitest.getRootProject().

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * Archivos de prueba que coinciden con los filtros.
   */
  testFiles: string[];
  /**
   * Archivos de prueba de verificación de tipos que coinciden con los filtros. Esto estará vacío a menos que `typecheck.enabled` sea `true`.
   */
  typecheckTestFiles: string[];
};

Realiza un glob de todos los archivos de prueba. Esta función devuelve un objeto con pruebas regulares y pruebas de verificación de tipos.

Este método acepta filters. Los filtros solo pueden contener una parte de la ruta del archivo, a diferencia de otros métodos en la instancia de Vitest:

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest usa fast-glob para encontrar archivos de prueba. test.dir, test.root, root o process.cwd() definen la opción cwd.

Este método tiene en cuenta varias opciones de configuración:

• test.include, test.exclude para encontrar archivos de prueba regulares
• test.includeSource, test.exclude para encontrar pruebas en el código fuente
• test.typecheck.include, test.typecheck.exclude para encontrar pruebas de verificación de tipos

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

Este método comprueba si el archivo es un archivo de prueba regular. Utiliza las mismas propiedades de configuración que globTestFiles para la validación.

Este método también acepta un segundo parámetro, que es el código fuente. Esto se usa para validar si el archivo es una prueba en el código fuente. Si está llamando a este método varias veces para varios proyectos, se recomienda leer el archivo una vez y pasarlo directamente como argumento. Si el archivo no es un archivo de prueba, pero coincide con el glob includeSource, Vitest leerá el archivo de forma síncrona a menos que se proporcione el source.

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // true si `includeSource` está configurado

import

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

Importa un archivo usando el cargador de módulos de Vite. El archivo será transformado por Vite con la configuración del proyecto 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, por lo que importar el mismo módulo usando una importación estándar devolverá un módulo diferente:

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

dynamicExample !== staticExample; // ✅

INFO

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

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

Esto es un atajo para project.vitest.onTestsRerun. Acepta una función de devolución de llamada que se ejecutará de forma asíncrona cuando las pruebas hayan sido programadas para volver a ejecutarse (generalmente, debido a un cambio de archivo).

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

Devuelve true si este proyecto ejecuta pruebas en el navegador.

close

function close(): Promise<void>;

Cierra el proyecto y todos los recursos asociados. Esto solo se puede llamar una vez; la promesa de cierre se guarda en caché hasta que el servidor se reinicia. Si los recursos se necesitan de nuevo, cree un nuevo proyecto.

En detalle, este método cierra el servidor Vite, detiene el servicio de verificación de tipos, cierra el navegador si está en ejecución, elimina el directorio temporal que contiene el código fuente y restablece el contexto proporcionado.