[Workers] Add changelog for @cloudflare/vitest-pool-workers Vitest 4 support

src/content/changelog/workers/2026-03-11-vitest-pool-workers-vitest-4.mdx

@@ -0,0 +1,93 @@
+---
+title: "`@cloudflare/vitest-pool-workers` now supports Vitest 4"
+description: Version 0.13.0 rearchitects the Workers Vitest integration around a Vite plugin, fixing over a dozen long-standing issues.
+products:
+  - workers
+date: 2026-03-18
+---
+
+`@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 will continue to work if you are not ready to migrate.
+
+This release rearchitects the integration around a Vite plugin model. The change required breaking the API, but it also let us close a long list of outstanding issues that were not fixable under the old architecture:
+
+- Library imports that previously needed SSR optimiser workarounds — including Stripe and others — now resolve correctly without configuration.
+- Bare Node.js specifiers like `node:url` now resolve in test files as expected.
+- `nodejs_compat_v2` and Node.js module flags are now automatically enabled during tests, matching production behaviour.
+- The `provide` data channel previously had an ~8 KB size limit imposed by HTTP headers. It now uses WebSocket messages with no practical limit.
+- Per-test isolated storage has been removed. It was a source of hard-to-debug state leakage between tests and did not match how Vitest itself handles isolation. Storage is now isolated per test file, consistent with standard Vitest behaviour.
+- The Vitest UI now works correctly with Workers tests.
+
+## Migrate with the codemod
+
+A codemod is available to update your `vitest.config.ts` to the new API automatically:
+
+```sh
+npx jscodeshift -t node_modules/@cloudflare/vitest-pool-workers/dist/codemods/vitest-v3-to-v4.mjs vitest.config.ts
+```
+
+Or, without installing the package first:
+
+```sh
+npx jscodeshift -t https://unpkg.com/@cloudflare/vitest-pool-workers/dist/codemods/vitest-v3-to-v4.mjs --parser=ts vitest.config.ts
+```
+
+:::note
+The codemod only updates `vitest.config.ts`. Changes to test files — including `cloudflare:test` import replacements — must be made manually.
+:::
+
+## Configuration changes
+
+`defineWorkersProject` and `defineWorkersConfig` from `@cloudflare/vitest-pool-workers/config` have been replaced 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" },
+		}),
+	],
+});
+```
+
+## Other breaking changes
+
+The following changes must be made manually to your test files. You can give the prompt below to a coding agent to handle the test file migrations for you:
+
+```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.
+```
+
+- **`isolatedStorage` and `singleWorker` removed.** Storage isolation is now per test file, matching Vitest's own isolation model. To make test files share the same storage, use the Vitest flags `--max-workers=1 --no-isolate`.
+
+- **`import { env, SELF } from "cloudflare:test"` 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/).
+
+- **`import { fetchMock } from "cloudflare:test"` 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 an example.
+
+For upstream Vitest 4 breaking changes 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).