Тестовая среда

Vitest предоставляет опцию environment для запуска кода в определенной среде. Вы можете изменить поведение среды с помощью опции environmentOptions.

По умолчанию доступны следующие среды:

• node — среда по умолчанию
• jsdom эмулирует среду браузера, предоставляя Browser API, использует пакет jsdom
• happy-dom эмулирует среду браузера, предоставляя Browser API, и считается быстрее, чем jsdom, но с ограниченным набором API, использует пакет happy-dom
• edge-runtime эмулирует edge-runtime от Vercel, использует пакет @edge-runtime/vm

INFO

При использовании сред jsdom или happy-dom Vitest следует тем же правилам, что и Vite при импорте CSS и ресурсов. Если импорт внешней зависимости завершается ошибкой unknown extension .css, вам необходимо вручную включить в цепочку импорта все пакеты, добавив их в server.deps.external. Например, если ошибка возникает в package-3 в этой цепочке импорта: исходный код -> package-1 -> package-2 -> package-3, вам необходимо добавить все три пакета в server.deps.external.

Начиная с Vitest 2.0.4, разрешение CSS и ресурсов, импортируемых через require внутри внешних зависимостей, происходит автоматически.

WARNING

"Среды" существуют только при запуске тестов в Node.js.

browser не считается средой в Vitest. Если вы хотите запустить часть своих тестов в режиме браузера, вы можете создать проект рабочей области.

Среды для определенных файлов

При установке опции environment в вашей конфигурации она применяется ко всем тестовым файлам в вашем проекте. Для более точного контроля вы можете использовать управляющие комментарии для указания среды для определенных файлов. Управляющие комментарии — это комментарии, которые начинаются с @vitest-environment, за которым следует имя среды:

// @vitest-environment jsdom

import { expect, test } from 'vitest';

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

Или вы также можете установить опцию environmentMatchGlobs, которая определяет среду на основе шаблонов glob.

Пользовательская среда

Вы можете создать собственный пакет для расширения среды Vitest. Для этого создайте пакет с именем vitest-environment-${name} или укажите путь к действительному файлу JS/TS. Этот пакет должен экспортировать объект со структурой Environment:

import type { Environment } from 'vitest';

export default <Environment>{
  name: 'custom',
  transformMode: 'ssr',
  // необязательно - только если вы поддерживаете режим "experimental-vm"
  async setupVM() {
    const vm = await import('node:vm');
    const context = vm.createContext();
    return {
      getVmContext() {
        return context;
      },
      teardown() {
        // вызывается после прогона всех тестов с этой средой
      },
    };
  },
  setup() {
    // пользовательская инициализация
    return {
      teardown() {
        // вызывается после прогона всех тестов с этой средой
      },
    };
  },
};

WARNING

Vitest требует наличие опции transformMode для объекта среды. Это значение определяет, как плагины будут трансформировать исходный код. Если оно установлено в ssr, хуки плагинов будут получать ssr: true при преобразовании или разрешении файлов. В противном случае ssr будет равен false.

У вас также есть доступ к стандартным средам Vitest через модуль vitest/environments:

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

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

Vitest также предоставляет служебную функцию populateGlobal, которую можно использовать для копирования свойств из объекта в глобальное пространство имен:

interface PopulateOptions {
  // должны ли функции, не являющиеся методами классов, быть привязаны к глобальному пространству имен
  bindFunctions?: boolean;
}

interface PopulateResult {
  // список всех скопированных ключей, даже если соответствующее значение отсутствует в исходном объекте
  keys: Set<string>;
  // отображение исходного объекта, чьи значения могли быть переопределены
  // вы можете вернуть эти значения в функции `teardown`
  originals: Map<string | symbol, any>;
}

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