テスト環境

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

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

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

INFO

jsdom または happy-dom 環境を使用する場合、Vitest は Vite が CSS およびアセットをインポートする際のルールに準拠します。外部依存関係のインポートが unknown extension .css エラーで失敗する場合、すべての関連パッケージを server.deps.external に追加し、インポートチェーン全体を手動でインライン展開する必要があります。例えば、ソースコード -> package-1 -> package-2 -> package-3 というインポートチェーンで package-3 にエラーが発生した場合、これら3つのパッケージを server.deps.external に追加する必要があります。

なお、外部依存関係内の 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');
});

または、glob パターンに基づいて環境を指定する environmentMatchGlobs オプションを設定することも可能です。

カスタム環境

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

テスト環境 ​

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

カスタム環境 ​

テスト環境

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

カスタム環境