Ambiente de Teste

O Vitest oferece a opção environment para executar o código dentro de um ambiente específico. Você pode modificar o comportamento do ambiente com a opção environmentOptions.

Por padrão, você pode usar os seguintes ambientes:

• node: é o ambiente padrão.
• jsdom: emula o ambiente do navegador, fornecendo a API do navegador. Utiliza o pacote jsdom.
• happy-dom: emula o ambiente do navegador, fornecendo a API do navegador e é considerado mais rápido que o jsdom, mas algumas APIs podem estar faltando. Utiliza o pacote happy-dom.
• edge-runtime: emula o edge-runtime da Vercel. Utiliza o pacote @edge-runtime/vm.

Ambientes para Arquivos Específicos

Ao definir a opção environment na sua configuração, ela será aplicada a todos os arquivos de teste no seu projeto. Para um controle mais preciso, você pode usar comentários de controle para especificar o ambiente para arquivos específicos. Comentários de controle são aqueles que começam com @vitest-environment e são seguidos pelo nome do ambiente:

// @vitest-environment jsdom

import { test } from 'vitest';

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

Você também pode definir a opção environmentMatchGlobs especificando o ambiente com base em padrões glob.

Ambiente Personalizado

A partir da versão 0.23.0, é possível criar seu próprio pacote para estender o ambiente do Vitest. Para isso, crie um pacote com o nome vitest-environment-${name} ou especifique um caminho para um arquivo JS válido (suportado a partir da versão 0.34.0). Esse pacote deve exportar um objeto no formato 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 da versão 0.34.0, o Vitest requer a opção transformMode no objeto de ambiente. O valor deve ser ssr ou web. Esse valor determina como os plugins irão transformar o código-fonte. Se definido como ssr, os hooks do plugin receberão ssr: true ao transformar ou resolver arquivos. Caso contrário, ssr é definido como false.

Você também pode acessar os ambientes padrão do Vitest através do módulo vitest/environments:

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

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

O Vitest também fornece a função utilitária populateGlobal, que pode ser utilizada para mover propriedades de um objeto para o namespace 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;