分離と並行実行

Workers の Vitest 連携がテストをどう実行するか、テスト同士をどう分離するか、モジュールをどうインポートするかを確認します。

テストの実行

Workers の Vitest 連携でテストを実行すると、Vitest は次の処理を行います。

Node.js で設定ファイルを読み込み、評価します。
Node.js で globalSetup ↗ ファイルがあれば実行します。
テストファイルを収集し、順序を決めます。
各 Vitest プロジェクトについて、設定された分離と並行実行に応じて、1 つ以上の workerd ↗ プロセスを起動します。各プロセスは 1 つ以上の Worker を実行します。
workerd 内の適切な Worker で setupFiles ↗ とテストファイルを実行します。
変更を監視し、設定が変わっていなければ、同じ Worker でテストファイルを再実行します。

分離モデル

ストレージの分離はテストファイル単位です。各テストファイルは独自のストレージ環境を持ち、テストファイル中のストレージへの書き込みは、ほかのテストファイルからは見えません。Workers の Vitest 連携は、可能な場合、テスト実行間で Worker とそのモジュールキャッシュを再利用します。補助の workers のコピーは、各 workerd プロセスに存在します。

デフォルトでは、テストファイルは並行して実行されます。テストファイルで同じストレージを共有するには（たとえば、共有状態に依存する統合テスト）、Vitest のフラグ --max-workers=1 --no-isolate を使います。

モジュール

各 Worker は独自のモジュールキャッシュを持ちます。Worker はテスト実行間で再利用されるため、モジュールキャッシュも再利用されます。Vitest は、変更されたファイルに基づき、各テスト実行の開始時にモジュールキャッシュの一部を無効化します。

Workers Vitest プラグインは、通常なら Node.js の Worker スレッド ↗ 内で動く Vitest のコードを、Cloudflare Worker 内で実行します。これを可能にするため、プラグインは nodejs_compat、[no_nodejs_compat_v2] および export_commonjs_default の互換性フラグを 自動注入 します。これは Vitest を正しく動かすための最小構成であり、不要なポリフィルやグローバルは取り込みません。設定にすでに Node.js 互換性フラグがある場合、Vitest プラグインはこれらのフラグを追加しません。

Caution

Workers Vitest プラグインを使うと、デフォルトで nodejs_compat フラグが有効になるため、デプロイ時の Worker の挙動が変わることがあります。つまり、テスト実行時は Node.js 固有の API とモジュールが使えます。ただし、本番環境の Cloudflare Workers では、Worker の設定でこのフラグを指定しない限り、これらの Node.js API はサポートされません。

設定に nodejs_compat または nodejs_compat_v2 フラグがなく、Worker のコードで Node.js モジュールをインポートした場合、テストは通っても、この Worker はデプロイできません。アップロード（REST API または Wrangler）がエラーになります。

一方、ランタイムがサポートしていない Node.js のグローバルを使った場合、Worker のアップロードは成功しますが、本番コードでエラーになることがあります。問題を示すために、わざと不自然な例を作ります。

Wrangler の設定ファイルには、nodejs_compat も nodejs_compat_v2 も指定していません。

{ "name": "test",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-09-20"
	# no nodejs_compat flags here
}

name = "test"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-09-20"

src/index.ts では、Workerd ランタイムでは使えない Node.js のグローバルである process オブジェクトを使っています。

export default {
	async fetch(request, env, ctx): Promise<Response> {
		process.env.TEST = "test";
		return new Response(process.env.TEST);
	},
} satisfies ExportedHandler<Env>;

テストは、Worker が process を使えたことを確認する単純なアサーションです。

it('responds with "test"', async () => {
	const response = await exports.default.fetch("https://example.com/");
	expect(await response.text()).toMatchInlineSnapshot(`"test"`);
});

npm run test を実行すると、テストは成功します。

 ✓ test/index.spec.ts (1)
   ✓ responds with "test"

 Test Files  1 passed (1)
      Tests  1 passed (1)

wrangler dev と wrangler deploy も問題なく実行できます。コードは問題ないように 見えます。しかし、このコードは本番では失敗します。process は Workerd ランタイムでは使えないためです。

修正するには、Node.js API の使用をやめるか、Wrangler 設定に nodejs_compat フラグを追加します。