Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Vitest 3 から Vitest 4 への移行

最終更新 Markdown で表示Agent セットアップ

@cloudflare/vitest-pool-workers v0.13.0 は Vitest 4 ↗ に対応します。v0.12.x は Vitest 3.x をサポートする最後のバージョンです。移行の準備ができていなくても、そのまま使い続けられます。

バージョン 0.13.0 では、連携の内部を Vite プラグインモデルに再設計しています。この変更で設定 API は互換性がなくなりますが、以前のアーキテクチャでは直せなかった問題も解消されます。

  • Stripe など、以前は SSR オプティマイザーの回避策が必要だったライブラリのインポートが、追加設定なしで解決します。
  • node:url のような bare な Node.js specifier が、テストファイル内で解決します。
  • テスト実行時に nodejs_compat_v2 と Node.js モジュールフラグが自動で有効になり、本番と同じ挙動になります。
  • provide のデータチャネルは、約 8 KB の制限がなくなります。WebSocket メッセージを使うようになりました。
  • ストレージの分離はテスト単位ではなくテストファイル単位になり、標準の Vitest と同じです。
  • Vitest UI が Workers のテストで正しく動作します。

このガイドでは、既存プロジェクトを v0.12.x から v0.13.x へ移行する手順を説明します。

依存関係を更新する

Vitest 4 と、最新の @cloudflare/vitest-pool-workers をインストールします。

npm i -D vitest@^4.1.0 @cloudflare/vitest-pool-workers

@cloudflare/vitest-pool-workers は @vitest/runner と @vitest/snapshot の ^4.1.0 も必要です。どちらも vitest の依存関係として入るため、vitest@^4.1.0 を入れれば満たされます。

設定を codemod で更新する

codemod が vitest.config.ts を新しいプラグイン API に自動更新します。パッケージをインストールしたあと、次を実行します。

npx jscodeshift -t node_modules/@cloudflare/vitest-pool-workers/dist/codemods/vitest-v3-to-v4.mjs vitest.config.ts

パッケージを先にインストールせずに codemod を実行する場合は、公開済みバージョンを指定します。

npx jscodeshift -t https://unpkg.com/@cloudflare/vitest-pool-workers/dist/codemods/vitest-v3-to-v4.mjs --parser=ts vitest.config.ts

設定の変更を確認する

@cloudflare/vitest-pool-workers/config の defineWorkersProject と defineWorkersConfig は、どちらも削除されました。代わりに、@cloudflare/vitest-pool-workers からエクスポートされる cloudflareTest() Vite プラグインを使います。以前は test.poolOptions.workers の下にあったオプションを、cloudflareTest() に直接渡します。

codemod は defineWorkersProject を使った設定を移行します。defineWorkersConfig を使っている場合や、defineWorkersProject にオブジェクトではなく関数を渡している場合は、codemod では変換できません。次の例を参考に、手作業で変更してください。

変更前:

vitest.config.tsts
import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersProject({
	test: {
		poolOptions: {
			workers: {
				wrangler: { configPath: "./wrangler.jsonc" },
			},
		},
	},
});

変更後:

vitest.config.tsts
import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
import { defineConfig } from "vitest/config";

export default defineConfig({
	plugins: [
		cloudflareTest({
			wrangler: { configPath: "./wrangler.jsonc" },
		}),
	],
});

isolatedStorage と singleWorker を削除する

isolatedStorage と singleWorker オプションは削除されました。ストレージの分離はテストファイル単位になり、Vitest 自身の分離モデルと一致します。codemod は既存の test.poolOptions.workers オプションを cloudflareTest() にコピーするため、以前どちらかを設定していた場合は、cloudflareTest() の呼び出しから削除してください。テストファイル間で同じストレージを共有したい場合は、package.json の Vitest コマンドに --max-workers=1 --no-isolate フラグを渡します。

テストファイルを更新する

次の変更は、テストファイルに手作業で加える必要があります。

非推奨の cloudflare:test インポートを更新する

cloudflare:test の env と SELF エクスポートは非推奨になり、cloudflare:workers を使います。import { env, SELF } from "cloudflare:test" を import { env, exports } from "cloudflare:workers" に置き換えます。exports.default.fetch() は SELF.fetch() と同じ動きをしますが、Assets は公開しません。Assets をテストするには、env.ASSETS バインディングを使うか、startDevWorker() で統合テストを書きます。非推奨のエクスポートはまだ動くため、この変更は必須ではなく推奨です。

- import { env, SELF } from "cloudflare:test";
+ import { env, exports } from "cloudflare:workers";

  it("dispatches fetch event", async () => {
-   const response = await SELF.fetch("https://example.com");
+   const response = await exports.default.fetch("https://example.com");
  });

fetchMock を置き換える

import { fetchMock } from "cloudflare:test" インポートは削除されました。globalThis.fetch を直接モックするか、MSW ↗ などのエコシステムライブラリを使います。完全な例は リクエストモックの例 ↗ を参照してください。

コーディングエージェントでテストファイルを移行する

テストファイルの変更を自動で行うには、コーディングエージェントに次のプロンプトを渡します。

コーディングエージェント向けプロンプトtxt
Migrate my @cloudflare/vitest-pool-workers tests from v0.12.x to v0.13.x (Vitest 4).

1. Run the codemod to update vitest.config.ts: `npx jscodeshift -t https://unpkg.com/@cloudflare/vitest-pool-workers/dist/codemods/vitest-v3-to-v4.mjs --parser=ts vitest.config.ts`
2. Replace all `import { env, SELF } from "cloudflare:test"` with `import { env, exports } from "cloudflare:workers"`. Replace uses of `SELF.fetch()` with `exports.default.fetch()`.
3. Remove all uses of `fetchMock` imported from `cloudflare:test`. Replace with direct mocks on `globalThis.fetch`, or with MSW if the project already uses it.
4. Remove the `isolatedStorage` and `singleWorker` options from the `cloudflareTest()` configuration in vitest.config.ts (the codemod copies them over from the old config). If tests relied on shared storage across files, add `--max-workers=1 --no-isolate` to the Vitest command in package.json.
5. Update any test files affected by upstream Vitest 4 breaking changes. Refer to the migration guide at https://vitest.dev/guide/migration#vitest-4 for the full list of changes.

上流の Vitest 4 の変更

Vitest 4 自体の破壊的変更でテストに影響するものは、Vitest 4 移行ガイド ↗ を参照してください。問題が起きた場合は、workers-sdk の GitHub リポジトリ ↗ でディスカッションを開いてください。

関連リソース

  • 最初のテストを書く — Workers のユニットテストと統合テストを書きます。
  • 設定 — cloudflareTest() プラグインのオプションのリファレンスです。

役に立ちましたか？