从 Vitest 3 迁移到 Vitest 4

@cloudflare/vitest-pool-workers v0.13.0 添加了对 Vitest 4 ↗ 的支持。v0.12.x 是支持 Vitest 3.x 的最后一个版本。如果尚未准备好迁移，它仍可继续使用。

0.13.0 版本围绕 Vite 插件模型重新架构了集成。此更改破坏了配置 API，但也解决了先前架构下无法修复的多个问题：

• 之前需要 SSR optimizer 变通方案的库导入（例如 Stripe）现在无需额外配置即可解析。
• 裸 Node.js 说明符（例如 node:url）现在可以在测试文件中解析。
• 测试期间自动启用 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

yarn add -D vitest@^4.1.0 @cloudflare/vitest-pool-workers

pnpm add -D vitest@^4.1.0 @cloudflare/vitest-pool-workers

bun add -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 会自动将 vitest.config.ts 更新为新的插件 API。安装包后，运行：

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

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

pnpm 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

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

pnpm 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 无法转换。请使用以下示例手动应用更改。

之前：

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

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

之后：

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

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

isolatedStorage 和 singleWorker 选项已移除。存储隔离现在按测试文件进行，与 Vitest 自身的隔离模型一致。codemod 会将现有的 test.poolOptions.workers 选项复制到 cloudflareTest() 中，因此如果之前设置了任一选项，请从 cloudflareTest() 调用中移除。若要让测试文件共享同一存储，请在 package.json 的 Vitest 命令中传递 --max-workers=1 --no-isolate 标志。

以下更改必须手动应用到测试文件。

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");
  });

import { fetchMock } from "cloudflare:test" 导入已移除。请直接 mock globalThis.fetch，或使用 MSW ↗ 等生态库。完整示例请参阅请求 mock 示例 ↗。

要自动处理测试文件更改，请将以下提示提供给编码 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 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 迁移指南 ↗。如果遇到问题，请在 workers-sdk GitHub 仓库 ↗ 上发起讨论。

• 编写第一个测试 - 为 Worker 编写单元测试和集成测试。
• 配置 - cloudflareTest() 插件选项参考。