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

Migrace z Vitest 3 na Vitest 4

@cloudflare/vitest-pool-workers v0.13.0 přidává podporu pro Vitest 4 ↗. v0.12.x je poslední verze podporující Vitest 3.x. Pokud ještě nejste připraveni na migraci, můžete ji nadále používat.

Verze 0.13.0 přepracovává architekturu integrace kolem modelu pluginu Vite. Tato změna narušuje konfigurační API, ale zároveň řeší řadu problémů, které v předchozí architektuře nebylo možné vyřešit:

• Importy knihoven, které dříve vyžadovaly obcházení pomocí SSR optimalizátoru, například Stripe, se nyní řeší bez další konfigurace.
• Holé specifikátory Node.js, jako například node:url se nyní v testovacích souborech vyřeší.
• nodejs_compat_v2 a příznaky modulů Node.js se během testů povolují automaticky, aby odpovídaly chování v produkci.
• provide datový kanál již není omezen na přibližně 8 KB. Nyní používá zprávy WebSocket.
• Úložiště je izolováno podle testovacího souboru, nikoli podle jednotlivého testu, v souladu se standardním chováním Vitest.
• Vitest UI funguje s testy Workers správně.

Tento průvodce popisuje migraci existujícího projektu z v0.12.x na v0.13.x.

Nainstalujte Vitest 4 a nejnovější verzi @cloudflare/vitest-pool-workers:

npm i -D vitest@^4.1.0 @cloudflare/vitest-pool-workers

@cloudflare/vitest-pool-workers také vyžaduje @vitest/runner a @vitest/snapshot na ^4.1.0. Oba se dodávají jako závislosti vitest, takže instalace vitest@^4.1.0 je splňuje.

Codemod aktualizuje váš vitest.config.ts na nové API pluginu automaticky. Po instalaci balíčku spusťte:

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

Chcete-li spustit codemod bez předchozí instalace balíčku, nasměrujte ho na publikovanou verzi:

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

defineWorkersProject a defineWorkersConfig z @cloudflare/vitest-pool-workers/config byly obě odstraněny. Nahrazuje je cloudflareTest() Vite plugin exportovaný z @cloudflare/vitest-pool-workers, s možnostmi dříve vnořenými pod test.poolOptions.workers předaný přímo do cloudflareTest().

Codemod migruje konfigurace, které používají defineWorkersProject. Pokud vaše konfigurace používá defineWorkersConfig, nebo volání defineWorkersProject funkcí místo objektu, nemůže ho codemod transformovat. Proveďte změnu ručně podle následujícího příkladu.

Před:

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

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

Poté:

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

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

isolatedStorage a singleWorker možnosti byly odstraněny. Izolace úložiště je nyní na úrovni jednotlivých testovacích souborů, což odpovídá vlastnímu modelu izolace Vitestu. Codemod zkopíruje vaše stávající test.poolOptions.workers možnosti do cloudflareTest(), takže pokud jste dříve nastavili některou z těchto možností, odstraňte ji z cloudflareTest() volání. Aby testovací soubory místo toho sdílely stejné úložiště, předejte --max-workers=1 --no-isolate příznaky k příkazu Vitest ve svém package.json.

Následující změny je nutné provést ve vašich testovacích souborech ručně.

env a SELF exporty z cloudflare:test jsou zastaralé a nahrazuje je cloudflare:workers. Nahraďte import { env, SELF } from "cloudflare:test" hodnotou import { env, exports } from "cloudflare:workers". exports.default.fetch() se chová stejně jako SELF.fetch(), až na to, že nezpřístupňuje Assets. Pro testování Assets použijte env.ASSETS binding, nebo napište integrační test pomocí startDevWorker(). Zastaralé exporty stále fungují, takže tato změna je doporučená, nikoli povinná.

- 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" import byl odstraněn. Mock globalThis.fetch přímo, nebo použijte knihovny z ekosystému, jako je MSW ↗. Přečtěte si příklad mockování požadavků ↗ pro kompletní příklad.

Chcete-li automaticky zpracovat změny v testovacím souboru, zadejte kódovacímu agentovi následující prompt:

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.

Zásadní změny přímo ve Vitest 4, které mohou ovlivnit vaše testy, najdete v Průvodce migrací na Vitest 4 ↗. Pokud narazíte na potíže, otevřete diskuzi na GitHub repozitář workers-sdk ↗.

• Napište svůj první test - Pište jednotkové a integrační testy pro Workers.
• Konfigurace - Reference pro cloudflareTest() možností pluginu.