← Cloudflare Workers / workers / testing / miniflare

Psaní testů

Tento průvodce vám ukáže, jak nastavit Miniflare pro testování vašich Workers. Miniflare je nízkoúrovňové API, které vám umožňuje plně řídit způsob, jakým jsou vaše Workers spouštěny a testovány.

Chcete-li používat Miniflare, ujistěte se, že máte nainstalovanou nejnovější verzi Miniflare v3:

npm i -D miniflare@latest

Zbytek této příručky demonstruje koncepty pomocí node:test ↗ testovací framework, lze však použít jakýkoli jiný testovací framework.

Miniflare je nízkoúrovňové API, které nabízí širokou škálu konfiguračních možností pro spouštění Workeru. Ve většině případů vaše testy potřebují jen část dostupných možností, ale můžete nahlédnout do úplná referenční dokumentace API a prozkoumejte, co všechno Miniflare umožňuje.

Než napíšete test, budete muset vytvořit Worker. Protože Miniflare je nízkoúrovňové API, které emuluje primitiva platformy Cloudflare, bude váš Worker muset být napsán v JavaScriptu, nebo budete muset integrovat vlastní sestavovací pipeline do vašeho testovacího nastavení. Zde je příklad Workeru pouze v JavaScriptu:

export default {
	async fetch(request) {
		return new Response(`Hello World`);
	},
};

Dále budete muset vytvořit počáteční testovací soubor:

import assert from "node:assert";
import test, { after, before, describe } from "node:test";
import { Miniflare } from "miniflare";

describe("worker", () => {
	/**
	 * @type {Miniflare}
	 */
	let worker;

	before(async () => {
		worker = new Miniflare({
			modules: [
				{
					type: "ESModule",
					path: "src/index.js",
				},
			],
		});
		await worker.ready;
	});

	test("hello world", async () => {
		assert.strictEqual(
			await (await worker.dispatchFetch("http://example.com")).text(),
			"Hello World",
		);
	});

	after(async () => {
		await worker.dispose();
	});
});

Výše uvedený test byste měli být schopni spustit pomocí node --test

Zvýrazněné řádky testovacího souboru výše ukazují, jak nastavit Miniflare pro spuštění JavaScript Workeru. Jakmile je Miniflare nastavený, mohou vaše jednotlivé testy odesílat požadavky na spuštěný Worker a ověřovat odpovědi. To je hlavní omezení používání Miniflare pro testování Workeru ve srovnání s Integrace Vitest : veškerý přístup k vašemu Workeru musí probíhat přes dispatchFetch() API Miniflare a jednotlivé funkce vašeho Workeru nelze unit testovat.

dispatchFetch() API z Miniflare umožňuje odesílat požadavky do Workeru a ověřovat, že se vrací správná odpověď. Někdy je ale potřeba v testech pracovat přímo s vazbami. Pro takové případy poskytuje Miniflare getBindings() API. Chcete-li například v testech přistupovat k proměnné prostředí, upravte soubor s testem src/index.test.js následovně:

...
describe("worker", () => {
	...
	before(async () => {
		worker = new Miniflare({
			...
+			bindings: {
+				FOO: "Hello Bindings",
+			},
		});
		...
	});

	test("text binding", async () => {
		const bindings = await worker.getBindings();
		assert.strictEqual(bindings.FOO, "Hello Bindings");
	});
	...
});

S lokálními prostředky, jako jsou KV a R2, můžete pracovat pomocí stejného API jako z Workeru. Zde je příklad, jak byste pracovali s KV namespace:

...
describe("worker", () => {
	...
	before(async () => {
		worker = new Miniflare({
			...
+			kvNamespaces: ["KV"],
		});
		...
	});

	test("kv binding", async () => {
		const bindings = await worker.getBindings();
		await bindings.KV.put("key", "value");
		assert.strictEqual(await bindings.KV.get("key"), "value");
	});
	...
});

Výše uvedený příklad ukazuje, jak otestovat jednoduchý Worker skládající se z jediného souboru JavaScript. Většina Workerů používaných v praxi je ale složitější. Miniflare umožňuje předat všechny součásti vašeho Workeru přímo pomocí API:

new Miniflare({
	modules: [
		{
			type: "ESModule",
			path: "src/index.js",
		},
		{
			type: "ESModule",
			path: "src/imported.js",
		},
	],
});

S růstem vašeho Workeru to může být poněkud těžkopádné. Aby to bylo snazší, Miniflare dokáže také procházet graf modulů a automaticky zjistit, které moduly zahrnout:

new Miniflare({
	scriptPath: "src/index-with-imports.js",
	modules: true,
	modulesRules: [{ type: "ESModule", include: ["**/*.js"] }],
});

V mnoha reálných případech nejsou Workers psané v čistém JavaScriptu, ale skládají se z více souborů TypeScript, které importují balíčky npm a další závislosti a jsou následně sbalené nástrojem pro sestavení. Při testování Workeru přímo přes Miniflare musíte tento nástroj pro sestavení spustit ještě před testy. Konkrétní způsob spuštění sestavení závisí na použitém testovacím frameworku, ale pro node:test by pravděpodobně bylo v setup() hook. Pokud například používáte Wrangler pro sestavení a nasazení Workeru byste mohli spustit wrangler build příkaz například takto:

before(() => {
	spawnSync("npx wrangler build -c wrangler-build.json", {
		shell: true,
		stdio: "pipe",
	});
});