Environnement de Test

Vitest offre l'option environment pour exécuter votre code dans un environnement spécifique. Vous pouvez affiner son comportement avec l'option environmentOptions.

Par défaut, les environnements suivants sont disponibles :

• node : l'environnement par défaut.
• jsdom : émule un environnement de navigateur en fournissant son API ; utilise le package jsdom.
• happy-dom : émule un environnement de navigateur en fournissant son API ; considéré comme plus rapide que jsdom mais avec un support limité pour certaines API ; utilise le package happy-dom.
• edge-runtime : émule l'edge-runtime de Vercel ; utilise le package @edge-runtime/vm.

INFO

Lors de l'utilisation des environnements jsdom ou happy-dom, Vitest applique 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 devrez inclure manuellement toute la chaîne d'importation en ajoutant tous les packages à 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 devrez ajouter les trois packages à server.deps.external.

Les importations (via require) de CSS et d'assets au sein des dépendances externes sont résolues automatiquement.

WARNING

Les "environnements" sont pertinents uniquement lorsque les tests sont exécutés dans Node.js.

browser n'est pas considéré comme un environnement Vitest. Si vous souhaitez exécuter une partie de vos tests en utilisant le Mode Navigateur, vous pouvez configurer un projet de test.

Environnements pour des Fichiers Spécifiques

Lorsque l'option environment est définie dans votre configuration, elle s'applique à tous les fichiers de test de votre projet. Pour un contrôle plus granulaire, vous pouvez utiliser des commentaires de contrôle afin de spécifier l'environnement pour des fichiers individuels. Ces commentaires commencent par @vitest-environment suivi du nom de l'environnement :

// @vitest-environment jsdom

import { expect, test } from 'vitest';

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

Alternativement, vous pouvez définir l'option environmentMatchGlobs pour spécifier l'environnement en fonction de motifs globaux.

Environnement Personnalisé

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

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

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // facultatif - uniquement si vous supportez 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 dans cet environnement
      },
    };
  },
  setup() {
    // initialisation personnalisée
    return {
      teardown() {
        // appelé après l'exécution de tous les tests dans cet environnement
      },
    };
  },
};

WARNING

Vitest requiert l'option transformMode sur l'objet d'environnement. Cette option doit être définie sur ssr ou web. Sa 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. Dans le cas contraire, ssr sera défini sur false.

Vous avez également accès aux environnements Vitest par défaut via le point d'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 permet de transférer des propriétés d'un objet vers l'espace de noms global :

interface PopulateOptions {
  // Les fonctions qui ne sont pas des 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 carte des valeurs originales de l'objet qui ont pu être remplacées par les 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;