テスト環境

Vitest は、コードを特定の環境で実行するための environment オプションを提供します。環境の動作は、environmentOptions オプションを使用して変更できます。

デフォルトで利用可能な環境は以下の通りです。

node: デフォルトの環境です。
jsdom: jsdom パッケージを使用し、ブラウザ環境をエミュレートするための Browser API を提供します。
happy-dom: happy-dom パッケージを使用し、ブラウザ環境をエミュレートするための Browser API を提供します。jsdom よりも高速ですが、一部の API が不足しています。
edge-runtime: Vercel の edge-runtime をエミュレートし、@edge-runtime/vm パッケージを使用します。

INFO

jsdom または happy-dom 環境を使用する場合、Vitest は Vite が CSS およびアセットをインポートする際と同じルールに従います。外部依存関係のインポート時に unknown extension .css エラーが発生した場合、すべてのパッケージを server.deps.external に追加し、インポートチェーン全体を手動でインライン化する必要があります。例えば、source code -> package-1 -> package-2 -> package-3 というインポートチェーンで package-3 でエラーが発生した場合、これら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 オプションを設定することも可能です。

カスタム環境

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 または 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 {
  // 非クラス関数をグローバル名前空間にバインドすべきかどうか
  bindFunctions?: boolean;
}

interface PopulateResult {
  // 値が元のオブジェクトに存在しない場合でも、コピーされたすべてのキーのリスト
  keys: Set<string>;
  // キーによって上書きされた可能性のある元のオブジェクトのマップ
  // これらの値は `teardown` 関数内で復元できます
  originals: Map<string | symbol, any>;
}

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

テスト環境 ​

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

カスタム環境 ​

テスト環境

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

カスタム環境