Ambiente di Test

Vitest offre l'opzione environment per eseguire il codice all'interno di un ambiente specifico. Il comportamento dell'ambiente può essere ulteriormente personalizzato tramite l'opzione environmentOptions.

Per impostazione predefinita, sono disponibili i seguenti ambienti:

• node: l'ambiente predefinito.
• jsdom: emula l'ambiente browser fornendo le API del browser, utilizzando il pacchetto jsdom.
• happy-dom: emula l'ambiente browser fornendo le API del browser ed è considerato più veloce rispetto a jsdom, sebbene possa mancare di alcune API. Utilizza il pacchetto happy-dom.
• edge-runtime: emula l'edge-runtime di Vercel, utilizzando il pacchetto @edge-runtime/vm.

INFO

Quando si utilizzano gli ambienti jsdom o happy-dom, Vitest segue le stesse regole di Vite per l'importazione di CSS e assets. Se l'importazione di una dipendenza esterna restituisce l'errore unknown extension .css, è necessario includere manualmente l'intera catena di importazione aggiungendo tutti i pacchetti a server.deps.external. Ad esempio, se l'errore si verifica in package-3 all'interno della catena di importazione: codice sorgente -> package-1 -> package-2 -> package-3, è necessario aggiungere tutti e tre i pacchetti a server.deps.external.

A partire da Vitest 2.0.4, il require di CSS e asset all'interno delle dipendenze esterne viene risolto automaticamente.

WARNING

Gli "ambienti" esistono solo durante l'esecuzione dei test in Node.js.

browser non è considerato un ambiente in Vitest. Se si desidera eseguire parte dei test in Modalità Browser, è possibile creare un progetto workspace.

Ambienti per File Specifici

Impostando l'opzione environment nella configurazione, essa si applicherà a tutti i file di test del progetto. Per un controllo più granulare, è possibile utilizzare i commenti di controllo per specificare l'ambiente per file specifici. I commenti di controllo iniziano con @vitest-environment e sono seguiti dal nome dell'ambiente:

// @vitest-environment jsdom

import { expect, test } from 'vitest';

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

In alternativa, è possibile impostare l'opzione environmentMatchGlobs specificando l'ambiente in base a pattern glob.

Ambiente Personalizzato

È possibile creare un pacchetto per estendere l'ambiente di Vitest. Per farlo, è necessario creare un pacchetto denominato vitest-environment-${name} o specificare un percorso a un file JS/TS valido. Il pacchetto deve esportare un oggetto conforme all'interfaccia Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // opzionale - solo se si supporta il pool "experimental-vm"
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // chiamato dopo che tutti i test con questo ambiente sono stati eseguiti
      },
    };
  },
  setup() {
    // configurazione personalizzata
    return {
      teardown() {
        // chiamato dopo che tutti i test con questo ambiente sono stati eseguiti
      },
    };
  },
};

WARNING

Vitest richiede l'opzione transformMode nell'oggetto ambiente. Questo valore deve essere ssr o web e determina come i plugin trasformeranno il codice sorgente. Se impostato su ssr, gli hook dei plugin riceveranno ssr: true durante la trasformazione o la risoluzione dei file. Altrimenti, ssr è impostato su false.

Si ha anche accesso agli ambienti predefiniti di Vitest tramite l'entry vitest/environments:

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

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

Vitest fornisce inoltre la funzione di utilità populateGlobal, che consente di trasferire le proprietà da un oggetto allo spazio dei nomi globale:

interface PopulateOptions {
  // le funzioni non di classe devono essere legate allo spazio dei nomi globale
  bindFunctions?: boolean;
}

interface PopulateResult {
  // un elenco di tutte le chiavi che sono state copiate, anche se il valore non esiste sull'oggetto originale
  keys: Set<string>;
  // una mappa dell'oggetto originale che potrebbe essere stato sovrascritto con le chiavi
  // è possibile restituire questi valori all'interno della funzione `teardown`
  originals: Map<string | symbol, any>;
}

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