Среда тестирования

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.

Вызовы require для CSS и ресурсов внутри внешних зависимостей разрешаются автоматически.

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/environments';

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 или web. Это значение определяет, каким образом плагины будут преобразовывать исходный код. Если оно установлено на 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;