Environnement de Test

Vitest fournit l’option environment pour exécuter du code dans un environnement spécifique. Vous pouvez modifier le comportement de l’environnement avec l’option environmentOptions.

Par défaut, vous pouvez utiliser ces environnements :

• node est l’environnement par défaut
• jsdom émule un environnement de navigateur en fournissant l’API du navigateur, utilise le package jsdom
• happy-dom émule un environnement de navigateur en fournissant l’API du navigateur, et est considéré comme plus rapide que jsdom, mais manque certaines API, utilise le package happy-dom
• edge-runtime émule edge-runtime de Vercel, utilise le package @edge-runtime/vm

Lors de l’utilisation des environnements jsdom ou happy-dom, Vitest suit les mêmes règles que Vite lors de l’importation de CSS et d’assets. Si l’importation d’une dépendance externe échoue avec l’erreur unknown extension .css, vous devez intégrer l’ensemble de la chaîne d’importation manuellement en ajoutant tous les packages à server.deps.external. Par exemple, si l’erreur se produit dans package-3 de cette chaîne d’importation : source code -> package-1 -> package-2 -> package-3, vous devez ajouter les trois packages à server.deps.external.

Depuis Vitest 2.0.4, le require de CSS et d’assets à l’intérieur des dépendances externes est résolu automatiquement.

Attention

Les “Environnements” n’existent que lors de l’exécution de tests dans 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 workspace.

Environnements pour des Fichiers Spécifiques

Lorsque vous définissez l’option environment dans votre configuration, elle s’appliquera à tous les fichiers de test de votre projet. Pour avoir un contrôle plus précis, vous pouvez utiliser des commentaires de contrôle pour spécifier l’environnement pour des fichiers spécifiques. Les commentaires de contrôle sont des commentaires qui 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')
})

Ou vous pouvez également définir l’option environmentMatchGlobs en spécifiant l’environnement en fonction des motifs glob.

Environnement Personnalisé

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

import type { Environment } from 'vitest'

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // optionnel - seulement 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 que tous les tests avec cet environnement aient été exécutés
      }
    }
  },
  setup() {
    // configuration personnalisée
    return {
      teardown() {
        // appelé après que tous les tests avec cet environnement aient été exécutés
      }
    }
  }
}

Attention

Vitest nécessite l’option transformMode dans l’objet d’environnement. Elle doit être égale à ssr ou web. Cette valeur détermine comment les plugins transformeront le code source. Si elle est définie sur ssr, les hooks des plugins 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 dans l’espace de noms global :

interface PopulateOptions {
  // les fonctions non-class 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 d'origine
  keys: Set<string>
  // une carte de l'objet d'origine qui peut avoir été remplacée avec des clés
  // vous pouvez retourner ces valeurs dans la fonction `teardown`
  originals: Map<string | symbol, any>
}

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