Ambiente di Test

Vitest offre l'opzione environment per eseguire il codice all'interno di un ambiente specifico. È possibile modificare il comportamento dell'ambiente tramite l'opzione environmentOptions.

Di default, 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; è considerato più performante di jsdom, ma privo 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 asset. Se l'importazione di una dipendenza esterna fallisce con 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 in questa catena di importazione: codice sorgente -> package-1 -> package-2 -> package-3, è necessario aggiungere tutti e tre i pacchetti a server.deps.external.

Il require per CSS e asset all'interno delle dipendenze esterne viene risolto automaticamente.

WARNING

Gli "ambienti" sono disponibili solo quando si eseguono test in Node.js.

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

Ambienti per File Specifici

Quando si imposta l'opzione environment nel proprio file di configurazione, questa verrà applicata 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, si può impostare l'opzione environmentMatchGlobs per specificare l'ambiente in base ai pattern glob.

Ambiente Personalizzato

È possibile creare un pacchetto personalizzato per estendere l'ambiente di Vitest. Per farlo, creare un pacchetto denominato vitest-environment-${nome} o specificare un percorso a un file JS/TS valido. Tale pacchetto deve esportare un oggetto che rispetti la forma di Environment:

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

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 per l'oggetto ambiente. Deve essere impostato su ssr o web. Questo valore 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.

È possibile accedere anche 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 anche la funzione di utilità populateGlobal, che permette di trasferire le proprietà di un oggetto nello 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 dei valori dell'oggetto originale che potrebbero essere stati sovrascritti dalle chiavi
  // è possibile ripristinare questi valori all'interno della funzione `teardown`
  originals: Map<string | symbol, any>;
}

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