Environnement de Test

Vitest propose l'option environment pour exécuter du code dans un environnement spécifique. Vous pouvez affiner le comportement de l'environnement via l'option environmentOptions.

Par défaut, les environnements suivants sont disponibles :

• node est l'environnement par défaut.
• jsdom simule un environnement de navigateur en fournissant l'API du navigateur ; il utilise le paquet jsdom.
• happy-dom simule un environnement de navigateur en fournissant l'API du navigateur ; il est considéré comme plus rapide que jsdom mais ne dispose pas de certaines API ; il utilise le paquet happy-dom.
• edge-runtime émule l'edge-runtime de Vercel ; il utilise le paquet @edge-runtime/vm.

INFO

Lorsque vous utilisez les environnements jsdom ou happy-dom, Vitest suit les mêmes règles que Vite pour l'importation de CSS et d'assets. Si l'importation d'une dépendance externe échoue avec l'erreur unknown extension .css, vous devez résoudre manuellement toute la chaîne d'importation en ajoutant tous les paquets à server.deps.external. Par exemple, si l'erreur se produit dans package-3 au sein de la chaîne d'importation : code source -> package-1 -> package-2 -> package-3, vous devez ajouter les trois paquets à server.deps.external.

Depuis Vitest 2.0.4, les appels require pour les fichiers CSS et les assets au sein des dépendances externes sont résolus automatiquement.

WARNING

Les environnements n'existent que lors de l'exécution de tests sous Node.js.

browser n'est pas considéré comme un environnement dans Vitest. Si vous souhaitez exécuter une partie de vos tests en utilisant le Mode Navigateur, vous pouvez créer un projet d'espace de travail.

Environnements pour des Fichiers Spécifiques

Lorsque vous définissez l'option environment dans votre configuration, elle s'applique à tous les fichiers de test de votre projet. Pour un contrôle plus précis, vous pouvez utiliser des commentaires de contrôle afin de spécifier l'environnement pour des fichiers spécifiques. Les commentaires de contrôle commencent par @vitest-environment et sont suivis du nom de l'environnement :

// @vitest-environment jsdom

import { expect, test } from 'vitest';

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

Vous pouvez également définir l'option environmentMatchGlobs pour spécifier l'environnement en fonction de motifs glob.

Environnement Personnalisé

Vous pouvez créer votre propre paquet pour étendre l'environnement de Vitest. Pour ce faire, créez un paquet nommé vitest-environment-${name} ou spécifiez un chemin vers un fichier JS/TS valide. Ce paquet doit exporter un objet de type Environment :

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // optionnel - seulement si vous prenez en charge le pool "experimental-vm"
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // appelé après l'exécution de tous les tests utilisant cet environnement
      },
    };
  },
  setup() {
    // paramétrage personnalisé
    return {
      teardown() {
        // appelé après l'exécution de tous les tests utilisant cet environnement
      },
    };
  },
};

WARNING

Vitest requiert l'option transformMode sur l'objet d'environnement. Elle doit être égale à ssr ou web. Cette valeur détermine la manière dont les plugins transformeront le code source. Si elle est définie sur ssr, les hooks de plugin recevront ssr: true lors de la transformation ou de la résolution des fichiers. Sinon, ssr est défini sur false.

Vous avez également accès aux environnements Vitest par défaut via l'entrée vitest/environments :

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

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

Vitest fournit également la fonction utilitaire populateGlobal, qui peut être utilisée pour déplacer des propriétés d'un objet vers l'espace de noms global :

interface PopulateOptions {
  // les fonctions non-classes doivent-elles être liées à l'espace de noms global ?
  bindFunctions?: boolean;
}

interface PopulateResult {
  // une liste de toutes les clés qui ont été copiées, même si la valeur n'existe pas sur l'objet original
  keys: Set<string>;
  // une Map des valeurs originales qui auraient pu être écrasées par ces clés
  // vous pouvez restaurer ces valeurs dans la fonction `teardown`
  originals: Map<string | symbol, any>;
}

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