From 511e263364392d7290b1a33f80f859330ba746d3 Mon Sep 17 00:00:00 2001 From: MattieTK Date: Tue, 23 Jun 2026 11:31:58 +0100 Subject: [PATCH 1/3] [Workers] Add Vitest 3 to Vitest 4 migration guide for vitest-pool-workers --- .../migrate-from-vitest-3-to-vitest-4.mdx | 138 ++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx diff --git a/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx b/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx new file mode 100644 index 00000000000..5abcffe0515 --- /dev/null +++ b/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx @@ -0,0 +1,138 @@ +--- +title: Migrate from Vitest 3 to Vitest 4 +pcx_content_type: how-to +sidebar: + order: 1 +head: [] +description: Migrate the Workers Vitest integration from v0.12.x (Vitest 3) to + v0.13.x (Vitest 4), covering configuration and test file changes. +products: + - workers +--- + +import { PackageManagers } from "~/components"; + +`@cloudflare/vitest-pool-workers` v0.13.0 adds support for [Vitest 4](https://vitest.dev/blog/vitest-4). v0.12.x is the last version to support Vitest 3.x. It continues to work if you are not ready to migrate. + +Version 0.13.0 rearchitects the integration around a Vite plugin model. This change breaks the configuration API, but it also resolves a number of issues that were not fixable under the previous architecture: + +- Library imports that previously required SSR optimizer workarounds, such as Stripe, now resolve without extra configuration. +- Bare Node.js specifiers such as `node:url` now resolve in test files. +- `nodejs_compat_v2` and Node.js module flags are enabled automatically during tests, matching production behavior. +- The `provide` data channel no longer has the previous ~8 KB size limit. It now uses WebSocket messages. +- Storage is isolated per test file instead of per test, consistent with standard Vitest behavior. +- The Vitest UI works correctly with Workers tests. + +This guide covers migrating an existing project from v0.12.x to v0.13.x. + +## Update your dependencies + +Install Vitest 4 and the latest version of `@cloudflare/vitest-pool-workers`: + + + +## Update your configuration with the codemod + +A codemod updates your `vitest.config.ts` to the new plugin API automatically. After installing the package, run: + + + +To run the codemod without installing the package first, point it at the published version: + + + +:::note +The codemod only updates `vitest.config.ts`. Changes to your test files, including `cloudflare:test` import replacements, must be made manually. The remaining sections describe those changes. +::: + +## Review the configuration changes + +The codemod replaces `defineWorkersProject` and `defineWorkersConfig` from `@cloudflare/vitest-pool-workers/config` with a `cloudflareTest()` Vite plugin exported from `@cloudflare/vitest-pool-workers`. Options previously nested under `test.poolOptions.workers` are now passed directly to `cloudflareTest()`. + +Before: + +```ts title="vitest.config.ts" +import { defineWorkersProject } from "@cloudflare/vitest-pool-workers/config"; + +export default defineWorkersProject({ + test: { + poolOptions: { + workers: { + wrangler: { configPath: "./wrangler.jsonc" }, + }, + }, + }, +}); +``` + +After: + +```ts title="vitest.config.ts" +import { cloudflareTest } from "@cloudflare/vitest-pool-workers"; +import { defineConfig } from "vitest/config"; + +export default defineConfig({ + plugins: [ + cloudflareTest({ + wrangler: { configPath: "./wrangler.jsonc" }, + }), + ], +}); +``` + +## Update your test files + +The following changes must be made manually to your test files. + +### Replace removed isolation options + +The `isolatedStorage` and `singleWorker` options have been removed. Storage isolation is now per test file, matching Vitest's own isolation model. To make test files share the same storage, pass the `--max-workers=1 --no-isolate` flags to the Vitest command in your `package.json`. + +### Replace cloudflare:test imports + +The `import { env, SELF } from "cloudflare:test"` import has been removed. Use `import { env, exports } from "cloudflare:workers"` instead. `exports.default.fetch()` behaves the same as `SELF.fetch()`, except that it does not expose Assets. To test Assets, write an integration test using [`startDevWorker()`](/workers/testing/unstable_startworker/). + +```diff +- 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"); + }); +``` + +### Replace fetchMock + +The `import { fetchMock } from "cloudflare:test"` import has been removed. Mock `globalThis.fetch` directly or use ecosystem libraries such as [MSW](https://mswjs.io/). Refer to the [request mocking example](https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/request-mocking/test/imperative.test.ts) for a complete example. + +## Migrate test files with a coding agent + +To handle the test file changes automatically, give the following prompt to a coding agent: + +```txt title="Prompt for your coding agent" +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 any test-level configuration. 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. +``` + +## Upstream Vitest 4 changes + +For breaking changes in Vitest 4 itself that may affect your tests, refer to the [Vitest 4 migration guide](https://vitest.dev/guide/migration#vitest-4). If you run into issues, open a discussion on the [workers-sdk GitHub repository](https://github.com/cloudflare/workers-sdk/discussions). + +## Related resources + +- [Write your first test](/workers/testing/vitest-integration/write-your-first-test/) - Write unit and integration tests for Workers. +- [Configuration](/workers/testing/vitest-integration/configuration/) - Reference for the `cloudflareTest()` plugin options. From ab5bb6b1561c2826535ab8203298f11e6e520dd0 Mon Sep 17 00:00:00 2001 From: MattieTK Date: Tue, 23 Jun 2026 14:57:14 +0100 Subject: [PATCH 2/3] [Workers] Correct Vitest 4 migration guide against shipped package behavior --- .../migrate-from-vitest-3-to-vitest-4.mdx | 22 +++++++++++-------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx b/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx index 5abcffe0515..fb3afc32f86 100644 --- a/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx +++ b/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx @@ -31,6 +31,8 @@ Install Vitest 4 and the latest version of `@cloudflare/vitest-pool-workers`: +`@cloudflare/vitest-pool-workers` also requires `@vitest/runner` and `@vitest/snapshot` at `^4.1.0`. Both ship as dependencies of `vitest`, so installing `vitest@^4.1.0` satisfies them. + ## Update your configuration with the codemod A codemod updates your `vitest.config.ts` to the new plugin API automatically. After installing the package, run: @@ -50,12 +52,14 @@ To run the codemod without installing the package first, point it at the publish /> :::note -The codemod only updates `vitest.config.ts`. Changes to your test files, including `cloudflare:test` import replacements, must be made manually. The remaining sections describe those changes. +The codemod only updates `vitest.config.ts`, and it does not remove options that are no longer supported. Changes to your test files, including `cloudflare:test` import updates, must be made manually. The remaining sections describe those changes. ::: ## Review the configuration changes -The codemod replaces `defineWorkersProject` and `defineWorkersConfig` from `@cloudflare/vitest-pool-workers/config` with a `cloudflareTest()` Vite plugin exported from `@cloudflare/vitest-pool-workers`. Options previously nested under `test.poolOptions.workers` are now passed directly to `cloudflareTest()`. +`defineWorkersProject` and `defineWorkersConfig` from `@cloudflare/vitest-pool-workers/config` have both been removed. They are replaced by a `cloudflareTest()` Vite plugin exported from `@cloudflare/vitest-pool-workers`, with options previously nested under `test.poolOptions.workers` passed directly to `cloudflareTest()`. + +The codemod migrates configurations that use `defineWorkersProject`. If your configuration uses `defineWorkersConfig`, or calls `defineWorkersProject` with a function instead of an object, the codemod cannot transform it and you must apply the change manually using the example below. Before: @@ -88,17 +92,17 @@ export default defineConfig({ }); ``` -## Update your test files +### Remove `isolatedStorage` and `singleWorker` -The following changes must be made manually to your test files. +The `isolatedStorage` and `singleWorker` options have been removed. Storage isolation is now per test file, matching Vitest's own isolation model. The codemod copies your existing `test.poolOptions.workers` options into `cloudflareTest()`, so if you previously set either option, remove it from the `cloudflareTest()` call. To make test files share the same storage instead, pass the `--max-workers=1 --no-isolate` flags to the Vitest command in your `package.json`. -### Replace removed isolation options +## Update your test files -The `isolatedStorage` and `singleWorker` options have been removed. Storage isolation is now per test file, matching Vitest's own isolation model. To make test files share the same storage, pass the `--max-workers=1 --no-isolate` flags to the Vitest command in your `package.json`. +The following changes must be made manually to your test files. -### Replace cloudflare:test imports +### Update deprecated `cloudflare:test` imports -The `import { env, SELF } from "cloudflare:test"` import has been removed. Use `import { env, exports } from "cloudflare:workers"` instead. `exports.default.fetch()` behaves the same as `SELF.fetch()`, except that it does not expose Assets. To test Assets, write an integration test using [`startDevWorker()`](/workers/testing/unstable_startworker/). +The `env` and `SELF` exports from `cloudflare:test` are deprecated in favor of `cloudflare:workers`. Replace `import { env, SELF } from "cloudflare:test"` with `import { env, exports } from "cloudflare:workers"`. `exports.default.fetch()` behaves the same as `SELF.fetch()`, except that it does not expose Assets. To test Assets, use the `env.ASSETS` binding or write an integration test using [`startDevWorker()`](/workers/testing/unstable_startworker/). The deprecated exports still work, so this change is recommended rather than required. ```diff - import { env, SELF } from "cloudflare:test"; @@ -124,7 +128,7 @@ Migrate my @cloudflare/vitest-pool-workers tests from v0.12.x to v0.13.x (Vitest 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 any test-level configuration. If tests relied on shared storage across files, add `--max-workers=1 --no-isolate` to the Vitest command in package.json. +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. ``` From d14dbdbbbb7f111624995f4fcd2f49ba28b217e2 Mon Sep 17 00:00:00 2001 From: MattieTK Date: Tue, 23 Jun 2026 16:28:44 +0100 Subject: [PATCH 3/3] [Workers] Address bonk review: directional language, phrasing, pinned link --- .../migration-guides/migrate-from-vitest-3-to-vitest-4.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx b/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx index fb3afc32f86..0a1e1224e66 100644 --- a/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx +++ b/src/content/docs/workers/testing/vitest-integration/migration-guides/migrate-from-vitest-3-to-vitest-4.mdx @@ -19,7 +19,7 @@ Version 0.13.0 rearchitects the integration around a Vite plugin model. This cha - Library imports that previously required SSR optimizer workarounds, such as Stripe, now resolve without extra configuration. - Bare Node.js specifiers such as `node:url` now resolve in test files. - `nodejs_compat_v2` and Node.js module flags are enabled automatically during tests, matching production behavior. -- The `provide` data channel no longer has the previous ~8 KB size limit. It now uses WebSocket messages. +- The `provide` data channel is no longer limited to ~8 KB. It now uses WebSocket messages. - Storage is isolated per test file instead of per test, consistent with standard Vitest behavior. - The Vitest UI works correctly with Workers tests. @@ -59,7 +59,7 @@ The codemod only updates `vitest.config.ts`, and it does not remove options that `defineWorkersProject` and `defineWorkersConfig` from `@cloudflare/vitest-pool-workers/config` have both been removed. They are replaced by a `cloudflareTest()` Vite plugin exported from `@cloudflare/vitest-pool-workers`, with options previously nested under `test.poolOptions.workers` passed directly to `cloudflareTest()`. -The codemod migrates configurations that use `defineWorkersProject`. If your configuration uses `defineWorkersConfig`, or calls `defineWorkersProject` with a function instead of an object, the codemod cannot transform it and you must apply the change manually using the example below. +The codemod migrates configurations that use `defineWorkersProject`. If your configuration uses `defineWorkersConfig`, or calls `defineWorkersProject` with a function instead of an object, the codemod cannot transform it. Apply the change manually using the following example. Before: @@ -116,7 +116,7 @@ The `env` and `SELF` exports from `cloudflare:test` are deprecated in favor of ` ### Replace fetchMock -The `import { fetchMock } from "cloudflare:test"` import has been removed. Mock `globalThis.fetch` directly or use ecosystem libraries such as [MSW](https://mswjs.io/). Refer to the [request mocking example](https://github.com/cloudflare/workers-sdk/blob/main/fixtures/vitest-pool-workers-examples/request-mocking/test/imperative.test.ts) for a complete example. +The `import { fetchMock } from "cloudflare:test"` import has been removed. Mock `globalThis.fetch` directly or use ecosystem libraries such as [MSW](https://mswjs.io/). Refer to the [request mocking example](https://github.com/cloudflare/workers-sdk/blob/1aee99059d6025c7ea8ef88b3ea421922eee6354/fixtures/vitest-pool-workers-examples/request-mocking/test/imperative.test.ts) for a complete example. ## Migrate test files with a coding agent