← Cloudflare Workers / workers / testing / vitest-integration

Izolace a souběžnost

Zjistěte, jak integrace Workers Vitest spouští vaše testy, jak izoluje testy od sebe navzájem a jak importuje moduly.

Spustit testy

Když spustíte testy s integrací Workers Vitest, Vitest provede následující:

Přečtěte a vyhodnoťte svůj konfigurační soubor pomocí Node.js.
Spusťte libovolný globalSetup ↗ soubory pomocí Node.js.
Shromážděte a seřaďte testovací soubory.
Pro každý projekt Vitest se podle nakonfigurované izolace a souběžnosti spustí jeden nebo více workerd ↗ procesy, z nichž každý spouští jeden nebo více Workerů.
Spustit setupFiles ↗ a testovací soubory v workerd pomocí příslušných Workers.
Sleduje změny a znovu spouští testovací soubory pomocí stejných Workerů, pokud se konfigurace nezměnila.

Izolační model

Izolace úložiště je podle testovacího souboru. Každý testovací soubor má vlastní prostředí úložiště a zápisy do úložiště provedené během jednoho testovacího souboru nejsou vidět z ostatních testovacích souborů. Integrace Workers Vitest podle možností znovu využívá Workers a jejich cache modulů mezi jednotlivými testovacími běhy. Kopie všech pomocných workers existuje v každém workerd proces.

Ve výchozím nastavení se testovací soubory spouštějí souběžně. Aby testovací soubory sdílely stejné úložiště (například u integračních testů závislých na sdíleném stavu), použijte příznaky Vitest --max-workers=1 --no-isolate.

Moduly

Každý Worker má vlastní cache modulů. Protože se Workery mezi testovacími běhy znovu používají, znovu se používají i jejich cache modulů. Vitest na začátku každého testovacího běhu invaliduje části cache modulů na základě změněných souborů.

Plugin Workers Vitest spouští kód uvnitř Cloudflare Workeru, zatímco Vitest by ho běžně spouštěl uvnitř Vlákno Node.js Worker ↗. Aby to bylo možné, plugin automaticky vkládá nodejs_compat, [no_nodejs_compat_v2] a export_commonjs_default příznaky kompatibility. Jde o minimální nastavení kompatibility, při kterém Vitest ještě funguje správně, aniž by se načítaly nepotřebné polyfills a globální proměnné. Pokud už máte v konfiguraci definovaný příznak kompatibility pro Node.js, plugin Vitest tyto příznaky nepřidává.

Upozornění

Použití pluginu Workers Vitest může způsobit, že se váš Worker po nasazení bude chovat jinak, protože nodejs_compat příznak je ve výchozím nastavení povolen. To znamená, že při spouštění testů jsou k dispozici API a moduly specifické pro Node.js. Cloudflare Workers ale tato API Node.js v produkčním prostředí nepodporují, pokud tento příznak neuvedete v konfiguraci svého Workeru.

Pokud nemáte nodejs_compat nebo nodejs_compat_v2 příznak v konfiguraci a zároveň ve svém kódu Workeru importujete modul Node.js, testy sice mohou projít, ale tento Worker nebudete moci nasadit, protože volání nahrání (ať už přes REST API, nebo přes Wrangler) vyhodí chybu.

Pokud však použijete globální objekty Node.js, které runtime nepodporuje, nahrání Workeru proběhne úspěšně, ale v produkčním kódu se mohou objevit chyby. Ukažme si to na uměle vytvořeném příkladu.

Konfigurační soubor Wrangler neuvádí ani nodejs_compat nebo nodejs_compat_v2:

{ "name": "test",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-08-28"
	# no nodejs_compat flags here
}

name = "test"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-08-28"

V naší src/index.ts soubor, používáme process objekt, což je globální objekt Node.js, který není v prostředí Workerd dostupný:

export default {
	async fetch(request, env, ctx): Promise<Response> {
		process.env.TEST = "test";
		return new Response(process.env.TEST);
	},
} satisfies ExportedHandler<Env>;

Test jednoduše ověřuje, že se Workeru podařilo použít process.

it('responds with "test"', async () => {
	const response = await exports.default.fetch("https://example.com/");
	expect(await response.text()).toMatchInlineSnapshot(`"test"`);
});

Pokud nyní spustíme npm run test, vidíme, že testy budou pass:

 ✓ test/index.spec.ts (1)
   ✓ responds with "test"

 Test Files  1 passed (1)
      Tests  1 passed (1)

A můžeme spustit wrangler dev a wrangler deploy bez problémů. To vypadá jako náš kód je v pořádku. V produkci ale tento kód selže, protože process není dostupné v běhovém prostředí Workerd.

Chcete-li problém vyřešit, musíme se buď vyhnout používání Node.js API, nebo přidat nodejs_compat příznak do naší konfigurace Wrangler.