テスト環境

Vitest は、特定の環境でコードを実行するための environment オプションを提供します。environmentOptions オプションを使用すると、環境の動作をカスタマイズできます。

デフォルトでは、次の環境が利用可能です。

• node: デフォルトの環境です。
• jsdom: ブラウザ API を提供することでブラウザ環境をエミュレートします。jsdom パッケージを使用します。
• happy-dom: ブラウザ API を提供することでブラウザ環境をエミュレートします。jsdom よりも高速であるとされていますが、一部の API が実装されていません。happy-dom パッケージを使用します。
• edge-runtime: Vercel の edge-runtime をエミュレートします。@edge-runtime/vm パッケージを使用します。

特定のファイルに対する環境設定

設定ファイルで environment オプションを設定すると、プロジェクト内のすべてのテストファイルに適用されます。より詳細な制御を行うには、制御コメントを使用して特定のファイルの環境を指定できます。制御コメントは @vitest-environment で始まり、その後に環境名を記述します。

// @vitest-environment jsdom

import { test } from 'vitest';

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

または、environmentMatchGlobs オプションを設定して、グロブパターンに基づいて環境を割り当てることもできます。

カスタム環境の作成

0.23.0 以降では、独自のパッケージを作成して Vitest 環境を拡張できます。これを行うには、vitest-environment-${name} という名前のパッケージを作成するか、0.34.0 以降でサポートされている有効な JS ファイルのパスを指定します。そのパッケージは 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

0.34.0 以降、Vitest は環境オブジェクトに transformMode オプションを必須とします。これは ssr または web のいずれかでなければなりません。この値は、プラグインがソースコードを変換する方法を決定します。ssr に設定されている場合、プラグインフックはファイルの変換または解決時に ssr: true を受け取ります。それ以外の場合、ssr は false に設定されます。

vitest/environments エントリを介して、デフォルトの Vitest 環境にアクセスすることもできます。

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

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

Vitest は、オブジェクトのプロパティをグローバル名前空間に移動するために使用できる populateGlobal ユーティリティ関数も提供します。

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;