Entorno de Pruebas

Vitest ofrece la opción environment para ejecutar código dentro de un entorno específico. Puedes modificar el comportamiento del entorno con la opción environmentOptions.

Por defecto, puedes usar los siguientes entornos:

• node: Es el entorno predeterminado.
• jsdom: Simula un entorno de navegador proporcionando la API del navegador. Utiliza el paquete jsdom.
• happy-dom: Simula un entorno de navegador proporcionando la API del navegador, y 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. Utiliza el paquete @edge-runtime/vm.

Entornos para Archivos Específicos

Cuando se establece la opción environment en la configuración, se aplicará a todos los archivos de prueba del proyecto. Para un control más granular, puedes utilizar comentarios de control para especificar el entorno para archivos individuales. Los comentarios de control comienzan con @vitest-environment seguido del nombre del entorno:

// @vitest-environment jsdom

import { test } from 'vitest';

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

También puedes configurar la opción environmentMatchGlobs para especificar el entorno basándose en patrones glob.

Entorno Personalizado

A partir de la versión 0.23.0, puedes crear tu propio paquete para extender el entorno de Vitest. Para ello, crea un paquete con el nombre vitest-environment-${name} o especifica una ruta a un archivo JS válido (compatible desde la versión 0.34.0). Este paquete debe exportar un objeto con la estructura de Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // optional - only if you support "experimental-vm" pool
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // called after all tests with this env have been run
      },
    };
  },
  setup() {
    // custom setup
    return {
      teardown() {
        // called after all tests with this env have been run
      },
    };
  },
};

WARNING

A partir de la versión 0.34.0, Vitest requiere la opción transformMode en el objeto de entorno, que 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 ssr: true al transformar o resolver archivos; de lo contrario, ssr se establece en false.

También tienes acceso 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 función de utilidad populateGlobal, que se puede usar para mover propiedades de un objeto al espacio de nombres global:

interface PopulateOptions {
  // should non-class functions be bind to the global namespace
  bindFunctions?: boolean;
}

interface PopulateResult {
  // a list of all keys that were copied, even if value doesn't exist on original object
  keys: Set<string>;
  // a map of original object that might have been overridden with keys
  // you can return these values inside `teardown` function
  originals: Map<string | symbol, any>;
}

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