← Cloudflare Workers / workers / testing / vitest-integration / migration-guides

Переход с 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-оптимизатора, например Stripe, теперь работают без дополнительной настройки.
• «Голые» спецификаторы Node.js, такие как node:url теперь разрешаются в тестовых файлах.
• nodejs_compat_v2 и флаги модулей Node.js включаются автоматически во время тестов, что соответствует поведению в продакшене.
• provide канал данных больше не ограничен ~8 КБ. Теперь он использует сообщения 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

@cloudflare/vitest-pool-workers также требует @vitest/runner и @vitest/snapshot по адресу ^4.1.0. Оба поставляются как зависимости vitest, поэтому установка vitest@^4.1.0 удовлетворяет им.

Кодмод обновляет ваш vitest.config.ts на новый API плагина автоматически. После установки пакета выполните:

npx 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

defineWorkersProject и defineWorkersConfig от @cloudflare/vitest-pool-workers/config были удалены. Их заменяет cloudflareTest() плагин Vite, экспортируемый из @cloudflare/vitest-pool-workers, с параметрами, ранее вложенными в test.poolOptions.workers передаётся напрямую в cloudflareTest().

Кодмод переносит конфигурации, использующие 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. Кодмод копирует ваши существующие test.poolOptions.workers параметры в cloudflareTest(), поэтому если вы ранее установили любой из этих параметров, удалите его из cloudflareTest() вызов. Чтобы вместо этого тестовые файлы использовали общее хранилище, передайте --max-workers=1 --no-isolate флаги в команду Vitest в вашем package.json.

В ваши тестовые файлы необходимо внести следующие изменения вручную.

env и SELF экспортируется из cloudflare:test считаются устаревшими в пользу 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" импорт был удалён. Мок globalThis.fetch напрямую или используйте библиотеки экосистемы, такие как MSW ↗. См. пример мокирования запроса ↗ для полного примера.

Чтобы автоматически обрабатывать изменения тестового файла, передайте следующий промпт ИИ-агенту для написания кода:

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 ↗.

• Напишите свой первый тест - Пишите модульные и интеграционные тесты для Workers.
• Конфигурация - Справочник по cloudflareTest() параметры плагина.