Entorno de prueba

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

Por defecto, puedes utilizar los siguientes entornos:

• node es el entorno predeterminado.
• jsdom emula el entorno del navegador y proporciona su API, utilizando el paquete jsdom.
• happy-dom emula el entorno del navegador y proporciona su API. Se considera más rápido que jsdom, aunque carece de algunas APIs. Utiliza el paquete happy-dom.
• edge-runtime emula el edge-runtime de Vercel, utilizando el paquete @edge-runtime/vm.

INFO

Al usar 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 resolver manualmente toda la cadena de importación 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.

A partir de Vitest 2.0.4, las importaciones require de CSS y recursos dentro de las dependencias externas se resuelven automáticamente.

WARNING

Los entornos solo están disponibles cuando las pruebas se ejecutan en Node.js.

browser no se considera un entorno en Vitest. Si deseas ejecutar parte de tus pruebas utilizando el Modo Navegador, puedes configurar un proyecto de espacio de trabajo.

Entornos para archivos específicos

Establecer la opción environment en tu configuración la aplicará a todos los archivos de prueba de tu proyecto. Para un control más granular, puedes usar comentarios de control para especificar el entorno para archivos concretos. Los comentarios de control 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 establecer la opción environmentMatchGlobs para especificar el entorno basándose en patrones glob.

Entorno personalizado

Puedes crear tu propio paquete para extender el entorno de Vitest. Para ello, puedes crear un paquete llamado vitest-environment-${name} o especificar una ruta a un archivo JS/TS válido. Este paquete debe exportar un objeto que cumpla con la interfaz Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // opcional - solo si es compatible con 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 del objeto de entorno. Debe ser ssr o web. Este valor determina cómo los plugins transformarán el código fuente. Si se establece en ssr, los hooks del plugin recibirán el valor ssr: true al transformar o resolver archivos. En caso contrario, ssr se establece en false.

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

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

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

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

interface PopulateOptions {
  // ¿deben las funciones que no pertenecen a clases estar vinculadas al espacio de nombres global?
  bindFunctions?: boolean;
}

interface PopulateResult {
  // una lista de todas las claves copiadas, incluso si el valor no existe en el objeto original
  keys: Set<string>;
  // un mapeo de los valores originales del objeto que pudieron haber sido sobrescritos por las claves
  // puedes restaurar estos valores en la función `teardown`
  originals: Map<string | symbol, any>;
}

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