Entorno de pruebas

Vitest ofrece la opción environment para ejecutar código dentro de un entorno específico. Puedes ajustar el comportamiento de este entorno utilizando la opción environmentOptions.

Por defecto, Vitest incluye los siguientes entornos:

• node es el entorno predeterminado.
• jsdom emula un entorno de navegador, proporcionando su API, y utiliza el paquete jsdom.
• happy-dom emula un entorno de navegador, proporcionando su API. Se considera más rápido que jsdom, aunque puede carecer de algunas de sus funcionalidades; utiliza el paquete happy-dom.
• edge-runtime emula el edge-runtime de Vercel, utilizando el paquete @edge-runtime/vm.

INFO

Al utilizar los entornos jsdom o happy-dom, Vitest sigue las mismas reglas que Vite para la importación de CSS y recursos estáticos. Si la importación de una dependencia externa falla con el error unknown extension .css, debes incluir manualmente la cadena de importación completa añadiendo todos los paquetes a server.deps.external. Por ejemplo, si el error ocurre en package-3 dentro de la cadena de importación: código fuente -> package-1 -> package-2 -> package-3, debes añadir los tres paquetes a server.deps.external.

Las llamadas a require de CSS y recursos dentro de las dependencias externas se resuelven automáticamente.

WARNING

Los entornos solo están disponibles al ejecutar pruebas en Node.js.

browser no se considera un entorno en Vitest. Si necesitas ejecutar parte de tus pruebas en un navegador, puedes configurar un proyecto de prueba en el Modo Navegador.

Entornos para archivos específicos

Si configuras la opción environment en tu archivo de configuración, esta se aplicará a todos los archivos de prueba de tu proyecto. Para un control más preciso, puedes especificar el entorno para archivos individuales utilizando comentarios de control. Estos comentarios comienzan con @vitest-environment seguido del nombre del entorno:

// @vitest-environment jsdom

import { expect, test } from 'vitest';

test('test', () => {
  expect(typeof window).not.toBe('undefined');
});

Alternativamente, puedes usar la opción environmentMatchGlobs para definir el entorno basándote en patrones glob.

Entorno personalizado

Puedes extender los entornos de Vitest creando tu propio paquete. Para ello, nombra tu paquete vitest-environment-${name} o especifica una ruta a un archivo JS/TS válido. Este paquete debe exportar un objeto que cumpla con la estructura de Environment:

import type { Environment } from 'vitest/environments';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // opcional - solo si utilizas el pool "experimental-vm"
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // se ejecuta después de que todas las pruebas con este entorno hayan finalizado
      },
    };
  },
  setup() {
    // configuración personalizada
    return {
      teardown() {
        // se ejecuta después de que todas las pruebas con este entorno hayan finalizado
      },
    };
  },
};

WARNING

Vitest requiere la opción transformMode en el objeto de entorno. Su valor debe ser ssr o web. Este valor determina cómo los plugins transforman el código fuente. Si se establece en ssr, los hooks del plugin recibirán ssr: true al transformar o resolver archivos. En caso contrario, ssr se establecerá en false.

También puedes acceder a los entornos predeterminados de Vitest a través de vitest/environments:

import { builtinEnvironments, populateGlobal } from 'vitest/environments';

console.log(builtinEnvironments); // { jsdom, happy-dom, node, edge-runtime }

Vitest también proporciona la función de utilidad populateGlobal, que se puede usar para transferir propiedades de un objeto al espacio de nombres global:

interface PopulateOptions {
  // ¿deben las funciones que no son de clase asociarse al espacio de nombres global?
  bindFunctions?: boolean;
}

interface PopulateResult {
  // una lista de todas las claves copiadas, incluso si su valor no existe en el objeto original
  keys: Set<string>;
  // un mapa de las claves del objeto original que podrían haber sido sobrescritas
  // puedes restaurar estos valores dentro de la función `teardown`
  originals: Map<string | symbol, any>;
}

export function populateGlobal(
  global: any,
  original: any,
  options: PopulateOptions
): PopulateResult;