Ambiente de Teste

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

Por padrão, você pode utilizar estes ambientes:

• node é o ambiente padrão.
• jsdom emula o ambiente do navegador, fornecendo a API do Browser e utilizando o pacote jsdom.
• happy-dom emula o ambiente do navegador, fornecendo a API do Browser. É considerado mais rápido que o jsdom, embora não possua algumas APIs. Ele utiliza o pacote happy-dom.
• edge-runtime emula o edge-runtime da Vercel, usando o pacote @edge-runtime/vm.

INFO

Ao usar os ambientes jsdom ou happy-dom, o Vitest segue as mesmas regras que o Vite ao importar CSS e assets. Se a importação de uma dependência externa falhar com o erro unknown extension .css, você precisará incluir manualmente toda a cadeia de importação, adicionando todos os pacotes a server.deps.external. Por exemplo, se o erro ocorrer em package-3 nesta cadeia de importação: código-fonte -> package-1 -> package-2 -> package-3, você precisa adicionar todos os três pacotes a server.deps.external.

As chamadas require de CSS e assets dentro das dependências externas são resolvidas automaticamente.

WARNING

"Ambientes" existem apenas ao executar testes no Node.js.

browser não é considerado um ambiente no Vitest. Se você deseja executar parte de seus testes no Modo Browser, você pode criar um projeto de teste.

Ambientes para Arquivos Específicos

Ao definir a opção environment em sua configuração, ela será aplicada a todos os arquivos de teste em seu projeto. Para ter um controle mais refinado, você pode usar comentários de controle para especificar o ambiente de 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 { expect, test } from 'vitest';

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

Ou você também pode definir a opção environmentMatchGlobs para especificar o ambiente com base nos padrões glob.

Ambiente Personalizado

Você pode criar seu próprio pacote para estender o ambiente do Vitest. Para fazer isso, crie um pacote nomeado vitest-environment-${name} ou especifique um caminho para um arquivo JS/TS válido. Esse pacote deve exportar um objeto no formato de Environment:

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

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // opcional - apenas se você der suporte ao pool "experimental-vm"
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // chamado depois que todos os testes com este ambiente tiverem sido executados
      },
    };
  },
  setup() {
    // configuração personalizada
    return {
      teardown() {
        // chamado depois que todos os testes com este ambiente tiverem sido executados
      },
    };
  },
};

WARNING

O Vitest exige a opção transformMode no objeto de ambiente. Ela deve ser igual a ssr ou web. Este valor determina como os plugins transformarão o código-fonte. Se estiver 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 tem acesso aos 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 usada para transferir propriedades de um objeto para o namespace global:

interface PopulateOptions {
  // as funções que não são classes devem ser vinculadas ao namespace global
  bindFunctions?: boolean;
}

interface PopulateResult {
  // uma lista de todas as chaves que foram copiadas, mesmo que o valor não exista no objeto original
  keys: Set<string>;
  // um mapa dos valores originais do objeto que podem ter sido sobrescritos pelas chaves
  // você pode retornar esses valores dentro da função `teardown`
  originals: Map<string | symbol, any>;
}

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