Introduce vitest4 to vitest-pool-workers#28908
Conversation
MattieTK
requested review from
a team,
GregBrimble,
Oxyjun,
WalshyDev,
elithrar,
irvinebroque,
joshthoward,
korinne,
lambrospetrou,
mikenomitch and
vy-ton
as code owners
github-actions
bot
added
product:workers
github-actions
bot
assigned
elithrar,
joshthoward,
lambrospetrou,
mikenomitch,
Oxyjun,
vy-ton,
GregBrimble,
irvinebroque and
korinne
|
This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:
|
| @@ -0,0 +1,70 @@ | |||
| --- | |||
| title: "`@cloudflare/vitest-pool-workers` now requires Vitest 4" | |||
There was a problem hiding this comment.
Could we say "targets" rather than "requires" to make it sound a bit more positive?
| title: "`@cloudflare/vitest-pool-workers` now requires Vitest 4" | |
| title: "`@cloudflare/vitest-pool-workers` now targets Vitest 4" |
There was a problem hiding this comment.
How about this?
| title: "`@cloudflare/vitest-pool-workers` now requires Vitest 4" | |
| title: "`@cloudflare/vitest-pool-workers` now supports Vitest 4" |
Then mention this requires Vitest v4.1.0 with the new version in the content?
| date: 2026-03-11 | ||
| --- | ||
|
|
||
| `@cloudflare/vitest-pool-workers` now requires Vitest 4.1 or later. Support for Vitest 2.x and 3.x has been dropped. This release rearchitects the integration to use a Vite plugin model and simplifies the configuration and isolation APIs as the package moves toward v1. |
There was a problem hiding this comment.
Can we focus on the benefits of us moving to Vitest 4? How this has enabled us to fix a bunch of long term bugs and issues?
There was a problem hiding this comment.
And perhaps we could say that we took the opportunity of this breaking change to simplify the integration and usage and to clarify how best to use vitest when testing workers?
(e.g. the isolated storage removal is more inline with how people conventionally manage resources in vitest tests rather than the magical approach that often caused diifficult to debug breakages)
There was a problem hiding this comment.
Yeah I don't think dropped is right language here.
Existing stuff keeps working with Vitest 3.x
It's just that there is a new version of @cloudflare/vitest-pool-workers
But where I am confused is — right now the version is 0.x? https://www.npmjs.com/package/@cloudflare/vitest-pool-workers?activeTab=code
So not to be semver guy about it — but I don't totally follow the relationship here between, "I need to use version of vitest pool workers in order to use vitest 4, etc."
irvinebroque
left a comment
irvinebroque
left a comment
There was a problem hiding this comment.
See questions about codemod
Also — opportunity for agent skill?
| date: 2026-03-11 | ||
| --- | ||
|
|
||
| `@cloudflare/vitest-pool-workers` now requires Vitest 4.1 or later. Support for Vitest 2.x and 3.x has been dropped. This release rearchitects the integration to use a Vite plugin model and simplifies the configuration and isolation APIs as the package moves toward v1. |
There was a problem hiding this comment.
Yeah I don't think dropped is right language here.
Existing stuff keeps working with Vitest 3.x
It's just that there is a new version of @cloudflare/vitest-pool-workers
But where I am confused is — right now the version is 0.x? https://www.npmjs.com/package/@cloudflare/vitest-pool-workers?activeTab=code
So not to be semver guy about it — but I don't totally follow the relationship here between, "I need to use version of vitest pool workers in order to use vitest 4, etc."
|
|
||
| ## Other breaking 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`. |
There was a problem hiding this comment.
so is the guidance here — remove your uses of these — and just use vitest flags?
is this / should it be part of the codemod?
|
|
||
| - **`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 your assets, write an integration test using [`startDevWorker()`](/workers/testing/unstable_startworker/). |
There was a problem hiding this comment.
it would have been great if the codemod covered test files too tbh, but it's shipped now without it for just the config file. The config file is the easiest thing to update 🙃
|
|
||
| - **`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 your 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. |
| declare module "cloudflare:workers" { | ||
| interface ProvidedEnv { | ||
| NAMESPACE: KVNamespace; | ||
| } |
There was a problem hiding this comment.
This is no longer correct, and we should probably just link to the Workers Typescript docs here instead of re-stating the config.
14 participants
Summary
This introduces a changelog and updates relevant documentation for vitest-pool-workers to reflect the changes made to update to vitest4. There are some features that are dependent on vitest 4.1 so we should wait for that release before merging this.
The changelog largely uses the documentation opencode persona, but has been manually reviewed and tweaked where it overstepped.
Documentation checklist