Support Vitest 4 in @cloudflare/vitest-pool-workers

.changeset/many-fishes-raise.md

@@ -0,0 +1,13 @@
+---
+"@cloudflare/vitest-pool-workers": minor
+---
+
+Support Vitest 4 in `@cloudflare/vitest-pool-workers`.
+
+This a breaking change to the `@cloudflare/vitest-pool-workers` integration in order to support Vitest v4. Along with supporting Vitest v4 (and dropping support for Vitest v2 and v3), we've made a number of changes that may require changes to your tests. Our aim has been to improve stability & the foundations of `@cloudflare/vitest-pool-workers` as we move towards a v1 release of the package.
+
+We've made a codemod to make the migration easier: `wrangler codemod vitest-pool-v3-to-v4`, which will make the required changes to your config file.
+
+- **`isolatedStorage` & `singleWorker`:** These have been removed in favour of a simpler isolation model that more closely matches Vitest. Storage isolation is now on a per test file basis, and you can make your test files share the same storage by using the Vitest flags `--max-workers=1 --no-isolate`
+- **`import { env, SELF } from "cloudflare:test"`:** These have been removed in favour of `import { env, exports } from "cloudflare:workers"`. `exports.default.fetch()` has the same behaviour as `SELF.fetch()`, except that it doesn't expose Assets. To test your assets, use the `env.ASSETS` bindings or write an integration test using [`startDevWorker()` (recommended)](https://developers.cloudflare.com/workers/testing/unstable_startworker/)
+- **`import { fetchMock } from "cloudflare:test"`:** This has been removed. Instead, [mock `globalThis.fetch`](https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/request-mocking/test/imperative.test.ts) or use ecosystem libraries like [MSW (recommended)](https://mswjs.io/).

.changeset/wrangler-codemod-command.md

@@ -0,0 +1,5 @@
+---
+"wrangler": minor
+---
+
+Add `wrangler codemod vitest-pool-v3-to-v4` command to help migrate `@cloudflare/vitest-pool-workers` config files from v3 to v4.

fixtures/get-platform-proxy/tests/get-platform-proxy.env.test.ts

@@ -37,6 +37,7 @@ describe("getPlatformProxy - env", () => {
 		vi.spyOn(console, "log").mockImplementation(() => {});
 		vi.spyOn(console, "error").mockImplementation(() => {});
 		warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+		warn.mockReset();
 	});
 
 	describe("var bindings", () => {

fixtures/vitest-pool-workers-examples/ai-vectorize/test/env.d.ts

@@ -1,3 +1,3 @@
-declare module "cloudflare:test" {
-	interface ProvidedEnv extends Env {}
+declare namespace Cloudflare {
+	interface Env {}
 }

fixtures/vitest-pool-workers-examples/ai-vectorize/vitest.config.ts

@@ -1,14 +1,15 @@
-import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";
+import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+	plugins: [
+		cloudflareTest({
+			remoteBindings: false,
+			wrangler: { configPath: "./wrangler.jsonc" },
+		}),
+	],
 
-export default defineWorkersProject({
 	test: {
 		globalSetup: ["./global-setup.ts"],
-		poolOptions: {
-			workers: {
-				singleWorker: true,
-				remoteBindings: false,
-				wrangler: { configPath: "./wrangler.jsonc" },
-			},
-		},
 	},
 });

fixtures/vitest-pool-workers-examples/basics-integration-auxiliary/test/env.d.ts

@@ -1,6 +1,5 @@
-declare module "cloudflare:test" {
-	// Controls the type of `import("cloudflare:test").env`
-	interface ProvidedEnv {
+declare namespace Cloudflare {
+	interface Env {
 		WORKER: Fetcher;
 	}
 }

fixtures/vitest-pool-workers-examples/basics-integration-auxiliary/vitest.config.ts

@@ -1,42 +1,43 @@
-import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";
+import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+import { defineConfig } from "vitest/config";
 
-export default defineWorkersProject({
-	test: {
-		globalSetup: ["./global-setup.ts"],
-		poolOptions: {
-			workers: {
-				singleWorker: true,
-				miniflare: {
-					// Configuration for the test runner Worker
-					compatibilityDate: "2024-01-01",
-					compatibilityFlags: [
-						// This illustrates a Worker that in production only wants v1 of Node.js compatibility.
-						// The Vitest pool integration will need to remove this flag since the `MockAgent` requires v2.
-						"no_nodejs_compat_v2",
-						"nodejs_compat",
-						// Required to use `WORKER.scheduled()`. This is an experimental
-						// compatibility flag, and cannot be enabled in production.
-						"service_binding_extra_handlers",
-					],
-					serviceBindings: {
-						WORKER: "worker-under-test",
-					},
-
-					workers: [
-						// Configuration for the "auxiliary" Worker under test.
-						// Unfortunately, auxiliary Workers cannot load their configuration
-						// from `wrangler.toml` files, and must be configured with Miniflare
-						// `WorkerOptions`.
-						{
-							name: "worker-under-test",
-							modules: true,
-							scriptPath: "./dist/index.js", // Built by `global-setup.ts`
-							compatibilityDate: "2024-01-01",
-							compatibilityFlags: ["nodejs_compat"],
-						},
-					],
+export default defineConfig({
+	plugins: [
+		cloudflareTest({
+			miniflare: {
+				// Configuration for the test runner Worker
+				compatibilityDate: "2024-01-01",
+				compatibilityFlags: [
+					// This illustrates a Worker that in production only wants v1 of Node.js compatibility.
+					// The Vitest pool integration will need to remove this flag since the `MockAgent` requires v2.
+					"no_nodejs_compat_v2",
+					"nodejs_compat",
+					// Required to use `WORKER.scheduled()`. This is an experimental
+					// compatibility flag, and cannot be enabled in production.
+					"service_binding_extra_handlers",
+				],
+				serviceBindings: {
+					WORKER: "worker-under-test",
 				},
+
+				workers: [
+					// Configuration for the "auxiliary" Worker under test.
+					// Unfortunately, auxiliary Workers cannot load their configuration
+					// from `wrangler.toml` files, and must be configured with Miniflare
+					// `WorkerOptions`.
+					{
+						name: "worker-under-test",
+						modules: true,
+						scriptPath: "./dist/index.js", // Built by `global-setup.ts`
+						compatibilityDate: "2024-01-01",
+						compatibilityFlags: ["nodejs_compat"],
+					},
+				],
 			},
-		},
+		}),
+	],
+
+	test: {
+		globalSetup: ["./global-setup.ts"],
 	},
 });

fixtures/vitest-pool-workers-examples/basics-unit-integration-self/vitest.config.ts

@@ -1,19 +1,19 @@
-import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";
+import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+import { defineConfig } from "vitest/config";
 
-export default defineWorkersProject({
-	test: {
-		poolOptions: {
-			workers: {
-				singleWorker: true,
-				miniflare: {
-					// Required to use `SELF.scheduled()`. This is an experimental
-					// compatibility flag, and cannot be enabled in production.
-					compatibilityFlags: ["service_binding_extra_handlers"],
-				},
-				wrangler: {
-					configPath: "./wrangler.jsonc",
-				},
+export default defineConfig({
+	plugins: [
+		cloudflareTest({
+			miniflare: {
+				// Required to use `SELF.scheduled()`. This is an experimental
+				// compatibility flag, and cannot be enabled in production.
+				compatibilityFlags: ["service_binding_extra_handlers"],
 			},
-		},
-	},
+			wrangler: {
+				configPath: "./wrangler.jsonc",
+			},
+		}),
+	],
+
+	test: {},
 });

fixtures/vitest-pool-workers-examples/container-app/test/env.d.ts

@@ -1,6 +1,5 @@
-declare module "cloudflare:test" {
-	// Controls the type of `import("cloudflare:test").env`
-	interface ProvidedEnv extends Env {
+declare namespace Cloudflare {
+	interface Env {
 		MY_CONTAINER: DurableObjectNamespace<MyContainer>;
 	}
 }

fixtures/vitest-pool-workers-examples/container-app/vitest.config.ts

@@ -1,12 +1,12 @@
-import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";
+import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+import { defineConfig } from "vitest/config";
 
-export default defineWorkersProject({
-	test: {
-		poolOptions: {
-			workers: {
-				singleWorker: true,
-				wrangler: { configPath: "./wrangler.jsonc" },
-			},
-		},
-	},
+export default defineConfig({
+	plugins: [
+		cloudflareTest({
+			wrangler: { configPath: "./wrangler.jsonc" },
+		}),
+	],
+
+	test: {},
 });

fixtures/vitest-pool-workers-examples/context-exports/src/worker-configuration.d.ts

@@ -5,6 +5,7 @@ declare namespace Cloudflare {
 	}
 	interface Env {
 		NAME: string;
+		AUXILIARY_WORKER: Fetcher;
 	}
 }
 interface Env extends Cloudflare.Env {}

fixtures/vitest-pool-workers-examples/context-exports/test/auxiliary.test.ts

@@ -1,13 +1,6 @@
 import { env } from "cloudflare:test";
 import { it } from "vitest";
 
-declare module "cloudflare:test" {
-	// Controls the type of `import("cloudflare:test").env`
-	interface ProvidedEnv {
-		AUXILIARY_WORKER: Fetcher;
-	}
-}
-
 it("uses the correct context exports on the auxiliary worker", async ({
 	expect,
 }) => {

fixtures/vitest-pool-workers-examples/context-exports/test/integration-self.test.ts

@@ -9,20 +9,22 @@ it("can use context exports on the SELF worker", async ({ expect }) => {
 	);
 });
 
-it("can use context exports (parameterized with props) on the SELF worker", async ({
+it("can use context exports (parameterized with props) on the exports.default worker", async ({
 	expect,
 }) => {
-	const response = await SELF.fetch("http://example.com/props");
+	const response = await exports.default.fetch("http://example.com/props");
 	expect(await response.text()).toBe(
 		"👋 Hello MainWorker from Main NamedEntryPoint!\nAdditional props!!"
 	);
 });
 
-it("will warn on missing context exports on the SELF worker", async ({
+it("will warn on missing context exports on the exports.default worker", async ({
 	expect,
 }) => {
 	const warnSpy = vi.spyOn(console, "warn");
-	const response = await SELF.fetch("http://example.com/invalid-export");
+	const response = await exports.default.fetch(
+		"http://example.com/invalid-export"
+	);
 	expect(await response.text()).toMatchInlineSnapshot(`"👋 undefined"`);
 	expect(warnSpy).toHaveBeenCalledWith(
 		"Attempted to access 'ctx.exports.InvalidExport', which was not defined for the main 'SELF' Worker.\n" +
@@ -31,13 +33,15 @@ it("will warn on missing context exports on the SELF worker", async ({
 	);
 });
 
-it("will warn on implicit re-exports that will exist in production but cannot not be guessed on the SELF worker", async ({
+it("will warn on implicit re-exports that will exist in production but cannot not be guessed on the exports.default worker", async ({
 	expect,
 }) => {
 	// In this test, we are trying to access an entry-point that is wildcard (*) re-exported from a virtual module.
 	// This virtual module is understood by Vitest and TypeScript but not the lightweight esbuild that we use to guess exports.
 	const warnSpy = vi.spyOn(console, "warn");
-	const response = await SELF.fetch("http://example.com/virtual-implicit");
+	const response = await exports.default.fetch(
+		"http://example.com/virtual-implicit"
+	);
 	expect(await response.text()).toMatchInlineSnapshot(`"👋 undefined"`);
 	expect(warnSpy).toHaveBeenCalledWith(
 		"Attempted to access 'ctx.exports.ReexportedVirtualEntryPoint', which was not defined for the main 'SELF' Worker.\n" +
@@ -46,31 +50,33 @@ it("will warn on implicit re-exports that will exist in production but cannot no
 	);
 });
 
-it("will still guess re-exports on the SELF worker that cannot be fully analyzed by esbuild", async ({
+it("will still guess re-exports on the exports.default worker that cannot be fully analyzed by esbuild", async ({
 	expect,
 }) => {
 	// In this test, we are trying to access an entry-point that is explicitly re-exported from a virtual module.
 	// Although esbuild cannot really analyze what is being re-exported, it can at least see that something is being re-exported with that name.
-	const warnSpy = vi.spyOn(console, "warn");
-	const response = await SELF.fetch("http://example.com/virtual-explicit");
+	const response = await exports.default.fetch(
+		"http://example.com/virtual-explicit"
+	);
 	expect(await response.text()).toBe(
 		"👋 Hello MainWorker from ExplicitVirtualEntryPoint!"
 	);
 });
 
-it("can access configured virtual entry points on the SELF worker that cannot be fully analyzed by esbuild", async ({
+it("can access configured virtual entry points on the exports.default worker that cannot be fully analyzed by esbuild", async ({
 	expect,
 }) => {
 	// In this test, we are trying to access an entry-point that is explicitly re-exported from a virtual module.
 	// Although esbuild cannot really analyze what is being re-exported, it can at least see that something is being re-exported with that name.
-	const warnSpy = vi.spyOn(console, "warn");
-	const response = await SELF.fetch("http://example.com/virtual-configured");
+	const response = await exports.default.fetch(
+		"http://example.com/virtual-configured"
+	);
 	expect(await response.text()).toBe(
 		"👋 Hello MainWorker from ConfiguredVirtualEntryPoint!"
 	);
 });
 
-it("can access imported context exports for SELF worker", async ({
+it("can access imported context exports for exports.default worker", async ({
 	expect,
 }) => {
 	const msg = await exports.NamedEntryPoint.greet();

fixtures/vitest-pool-workers-examples/context-exports/vitest.config.ts

@@ -1,4 +1,5 @@
-import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config";
+import { cloudflareTest } from "@cloudflare/vitest-pool-workers";
+import { defineConfig } from "vitest/config";
 
 // Configuration for the "auxiliary" Worker under test.
 // Unfortunately, auxiliary Workers cannot load their configuration
@@ -15,21 +16,22 @@ export const auxiliaryWorker = {
 	},
 };
 
-export default defineWorkersProject({
+export default defineConfig({
+	plugins: [
+		cloudflareTest({
+			wrangler: { configPath: "./src/wrangler.jsonc" },
+			miniflare: {
+				workers: [auxiliaryWorker],
+			},
+			additionalExports: {
+				// This entrypoint is wildcard re-exported from a virtual module so we cannot automatically infer it.
+				ConfiguredVirtualEntryPoint: "WorkerEntrypoint",
+			},
+		}),
+	],
+
 	test: {
 		globalSetup: ["./global-setup.ts"],
-		poolOptions: {
-			workers: {
-				wrangler: { configPath: "./src/wrangler.jsonc" },
-				miniflare: {
-					workers: [auxiliaryWorker],
-				},
-				additionalExports: {
-					// This entrypoint is wildcard re-exported from a virtual module so we cannot automatically infer it.
-					ConfiguredVirtualEntryPoint: "WorkerEntrypoint",
-				},
-			},
-		},
 		alias: {
 			// This alias is used to simulate a virtual module that Vitest and TypeScript can understand,
 			// but esbuild (used by the vitest-pool-workers to guess exports) cannot.