Environnement de test

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

Par défaut, les environnements suivants sont disponibles :

• node : l'environnement par défaut.
• jsdom : émule l'environnement d'un navigateur en fournissant l'API du navigateur, grâce au package jsdom.
• happy-dom : émule l'environnement d'un navigateur en fournissant l'API du navigateur. Il est généralement plus rapide que jsdom, mais certaines API sont manquantes. Il utilise le package happy-dom.
• edge-runtime : émule edge-runtime de Vercel, en utilisant le package @edge-runtime/vm.

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. 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');
});

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

Environnement personnalisé

À partir de la version 0.23.0, vous pouvez créer votre propre package pour étendre l'environnement Vitest. Pour ce faire, créez un package nommé vitest-environment-${name} ou spécifiez un chemin d'accès vers un fichier JS valide (pris en charge depuis la version 0.34.0). Ce package doit exporter un objet conforme à l'interface Environment :

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // optional - only if you support "experimental-vm" pool
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // called after all tests with this env have been run
      },
    };
  },
  setup() {
    // custom setup
    return {
      teardown() {
        // called after all tests with this env have been run
      },
    };
  },
};

WARNING

Depuis la version 0.34.0, Vitest requiert l'option transformMode dans 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 pouvez également accéder 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 {
  // should non-class functions be bind to the global namespace
  bindFunctions?: boolean;
}

interface PopulateResult {
  // a list of all keys that were copied, even if value doesn't exist on original object
  keys: Set<string>;
  // a map of original object that might have been overridden with keys
  // you can return these values inside `teardown` function
  originals: Map<string | symbol, any>;
}

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