← Cloudflare Workers / workers / wrangler

API

Wrangler nabízí rozhraní API pro programovou práci s vašimi Cloudflare Workers.

• createTestHarness - Spusťte jeden nebo více Workers pro integrační testy v libovolném test runneru Node.js.
• experimental_generateTypes - Vygenerujte definice typů TypeScript z konfigurace vašeho Workeru.
• unstable_startWorker - Spusťte server pro spouštění integračních testů proti vašemu Workeru.
• unstable_dev - Spusťte server pro spouštění end-to-end (e2e) nebo integračních testů proti vašemu Workeru.
• getPlatformProxy - Získejte proxy a hodnoty pro emulaci platformy Cloudflare Workers v procesu Node.js.

createTestHarness() spustí jeden nebo více Workers pro integrační testy z libovolného test runneru pro Node.js. Spouští produkční výstup buildu z konfiguračních souborů Wrangler, konfiguračních souborů vygenerovaných Vite nebo z vložených konfiguračních objektů Wrangler. Toto API obaluje Miniflare a poskytuje metody pro odesílání requestů a naplánovaných událostí.

Pokyny k nastavení a příklady najdete v Nástroj pro integrační testování.

import { createTestHarness } from "wrangler";

const server = createTestHarness(options);

import { createTestHarness } from "wrangler";

const server = createTestHarness(options);

• options object volitelné

  • Možnosti testovacího nástroje (harness). Pokud zavoláte createTestHarness() bez možností, zavolejte server.update(options) před server.listen().

    • root string volitelné

      Základní adresář použitý k překladu relativních cest ke konfiguraci Workeru. Výchozí hodnota je process.cwd().

    • workers WorkerInput[]

      Workers, které se mají spustit v testovacím serveru. První Worker je primární Worker.

Každý WorkerInput umí načíst Worker z konfiguračního souboru Wrangler:

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

Vstupy konfiguračního souboru podporují tato pole:

• configPath string | URL
  • Cesta ke konfiguračnímu souboru Wrangler. Relativní cesty se vyhodnocují od root.
• env string volitelné
  • Prostředí Wrangleru, které se má načíst z konfiguračního souboru.
• vars Record<string, Json> volitelné
  • Proměnné pouze pro testování, které přepisují proměnné z konfiguračního souboru Wrangler.
• secrets Record<string, string> volitelné
  • Tajné hodnoty pouze pro testování, které přepisují hodnoty načtené z .dev.vars a .env soubory.
• bindingOverrides Record<string, string> volitelné
  • Přepisy vazeb služeb pouze pro testování. Klíče jsou názvy vazeb v prostředí tohoto Workeru. Hodnoty jsou názvy Workerů v tomto testovacím nástroji (harness).

Každý WorkerInput lze také použít config pro poskytnutí vloženého konfiguračního objektu Wrangler:

const server = createTestHarness({
	workers: [
		{
			config: {
				name: "api-worker",
				main: "src/api.ts",
				compatibility_date: "YYYY-MM-DD",
			},
		},
	],
});

const server = createTestHarness({
	workers: [
		{
			config: {
				name: "api-worker",
				main: "src/api.ts",
				compatibility_date: "YYYY-MM-DD",
			},
		},
	],
});

createTestHarness() vrací TestHarness objekt s těmito metodami:

• listen() Promise<{ url: URL }>
  • Spustí server a vrátí jeho aktuální URL. Opakovaná volání vrací stejnou relaci, dokud není server zavřen nebo resetován.
• fetch(input, init) Promise<Response>
  • Odesílá požadavek fetch přes server. Relativní adresy URL se vyhodnocují vůči aktuální adrese URL serveru. Absolutní adresy URL se řídí nakonfigurovanými trasami Workeru a v opačném případě se použije primární Worker.
• getWorker(name?) WorkerHandle
  • Vrátí handle pro přímé odesílání událostí do Workeru. Pokud není zadán žádný název, vrátí se primární Worker.
• getLogs() WorkerdStructuredLog[]
  • Vrátí zachycené protokoly runtime Workers od zahájení aktuální relace serveru nebo clearLogs() byla naposledy volána.
• clearLogs() void
  • Vymaže zachycené protokoly runtime Workers.
• debug() void
  • Vypíše diagnostickou časovou osu testovacího serveru, včetně serverových událostí a zachycených protokolů Workers runtime. To je užitečné při selhání test runneru nebo v rámci cleanup hooku.
• update(optionsOrUpdater) Promise<void>
  • Aktualizuje konfiguraci serveru pomocí TestHarnessOptions objekt nebo funkci, která přijímá aktuální možnosti a vrací další možnosti. Pokud server ještě nebyl spuštěn, nastaví se tím možnosti použité listen(). Pokud server běží, tímto se běžící Workery znovu načtou. Změna počtu Workerů v běžícím serveru není podporována.
• reset() Promise<void>
  • Obnoví server do nastavení použitého při prvním spuštění aktuální relace. Úložiště se znovu vytvoří a URL adresa serveru se po resetu může změnit.
• close() Promise<void>
  • Zastaví server a uvolní všechny prostředky za běhu.

getWorker(name?) vrací WorkerHandle objekt s těmito metodami:

• fetch(input, init) Promise<Response>
  • Odesílá událost fetch přímo tomuto Workeru.
• scheduled(options) Promise<{ outcome: "ok" | "canceled" | "exception"; noRetry: boolean }>
  • Odesílá naplánovanou událost přímo tomuto Workeru.
• getEnv() Promise<Env>
  • Vrátí úplný objekt prostředí nakonfigurovaný pro tento Worker, včetně proměnných, tajných klíčů a bindings.
• getExport() Promise<Service<Module['default']>>
  • Vrátí výchozí export Workeru včetně metod RPC.
• applyD1Migrations(bindingName) Promise<void>
  • Aplikuje lokální migrační soubory D1, které ještě nebyly spuštěny, na D1 binding tohoto Workeru.
• getDurableObjectStorage(classNameOrBindingName, options) Promise<DurableObjectStorageHandle>
  • Vrátí přístup k úložišti SQL pro instanci Durable Object.
• introspectWorkflow(bindingName) Promise<WorkflowIntrospector>
  • Vytvoří introspektor pro instance Workflow vytvořené po zavolání této metody.
• introspectWorkflowInstance(bindingName, instanceId) Promise<WorkflowInstanceIntrospector>
  • Vytvoří introspektor pro konkrétní instanci Workflow.

Tento příklad používá vestavěný test runner Node.js:

import assert from "node:assert/strict";
import { after, afterEach, before, describe, test } from "node:test";
import { createTestHarness } from "wrangler";

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

const apiWorker = server.getWorker("api-worker");

describe("Worker", () => {
	before(async () => {
		await server.listen();
	});

	afterEach(async () => {
		await server.reset();
	});

	after(async () => {
		await server.close();
	});

	test("dispatches through configured routes", async () => {
		const response = await server.fetch("http://example.com/users/123");
		assert.equal(response.status, 200);
	});

	test("calls a specific Worker directly", async () => {
		const response = await apiWorker.fetch(
			"http://api.example.com/v1/users/123",
		);
		assert.equal(response.status, 200);
	});

	test("triggers a scheduled handler", async () => {
		const result = await apiWorker.scheduled({
			cron: "0 0 * * *",
			scheduledTime: new Date(),
		});
		assert.equal(result.outcome, "ok");
	});
});

import assert from "node:assert/strict";
import { after, afterEach, before, describe, test } from "node:test";
import { createTestHarness } from "wrangler";

const server = createTestHarness({
	workers: [
		{ configPath: "./wrangler.web.jsonc" },
		{ configPath: "./wrangler.api.jsonc" },
	],
});

const apiWorker = server.getWorker("api-worker");

describe("Worker", () => {
	before(async () => {
		await server.listen();
	});

	afterEach(async () => {
		await server.reset();
	});

	after(async () => {
		await server.close();
	});

	test("dispatches through configured routes", async () => {
		const response = await server.fetch("http://example.com/users/123");
		assert.equal(response.status, 200);
	});

	test("calls a specific Worker directly", async () => {
		const response = await apiWorker.fetch(
			"http://api.example.com/v1/users/123",
		);
		assert.equal(response.status, 200);
	});

	test("triggers a scheduled handler", async () => {
		const result = await apiWorker.scheduled({
			cron: "0 0 * * *",
			scheduledTime: new Date(),
		});
		assert.equal(result.outcome, "ok");
	});
});

Vygenerujte definice typů TypeScript z konfigurace Workeru. Toto API využívá stejnou základní logiku jako wrangler types příkaz CLI, takže výstupy zůstávají shodné mezi CLI a programovým API.

Na rozdíl od příkazu CLI experimental_generateTypes automaticky nezapisuje na disk. Místo toho vrací vygenerovaný obsah typů jako strukturované řetězce, se kterými můžete dále pracovat podle potřeby.

import { experimental_generateTypes } from "wrangler";

const result = await experimental_generateTypes(options);

• options object volitelné

  • Volitelný objekt options odpovídající wrangler types příznaky CLI:

    • config string | string[]

      Cesta ke konfiguračnímu souboru Wrangler, který se má použít. Lze zadat jako pole pro rozlišení mezi více typy konfigurace.

    • env string

      Název prostředí Wrangler, pro které se mají vygenerovat typy.

    • envFile string[]

      Cesty k .env soubory se mají načíst při odvozování lokálních proměnných a secrets.

    • envInterface string

      Název generovaného rozhraní prostředí. Výchozí hodnota je Env.

    • includeEnv boolean

      Zda výstup zahrnuje typy pro prostředí a bindings. Výchozí hodnota: true.

    • includeRuntime boolean

      Zda výstup zahrnuje runtime typy. Výchozí hodnota: true.

    • path string

      Cesta k souboru s deklaracemi pro vygenerované typy. Výchozí hodnota je worker-configuration.d.ts.

    • strictVars boolean

      Zda generovat striktní literálové a union typy pro proměnné. Výchozí hodnota: true.

experimental_generateTypes() vrací Promise která se přeloží na objekt obsahující následující pole:

• content string

  • Kombinovaný formátovaný výstup obsahující všechny vygenerované sekce, včetně hlaviček a typů env i runtime.

• env string | null

  • Vygenerované typy prostředí a bindingů, nebo null když jsou typy env vyloučeny.

• path string

  • Cesta k cílovému souboru deklarací přiřazenému k tomuto běhu generování.

• runtime string | null

  • Vygenerované typy runtime, nebo null když jsou typy runtime vyloučeny.

Můžete použít experimental_generateTypes abyste vygenerovali typy programově, sami je zapsali na disk, nebo je předali jiným nástrojům:

import { experimental_generateTypes } from "wrangler";
import * as fs from "node:fs";

const result = await experimental_generateTypes({
	config: "wrangler.json",
	includeRuntime: true,
	includeEnv: true,
});

// Write the combined content to the path specified in options
fs.writeFileSync(result.path, result.content, "utf-8");

Chcete-li vygenerovat pouze typy env bez typů runtime:

const result = await experimental_generateTypes({
	includeRuntime: false,
});

Chcete-li vygenerovat typy pro konkrétní prostředí s vlastním názvem rozhraní:

const result = await experimental_generateTypes({
	env: "staging",
	envInterface: "StagingEnv",
	path: "./types/staging.d.ts",
});

Toto API zpřístupňuje vnitřní fungování vývojového serveru Wrangler a umožňuje přizpůsobit způsob jeho spuštění. Můžete například použít unstable_startWorker() pro spuštění integračních testů proti vašemu Workeru. Tento příklad používá node:test, ale mělo by to platit pro jakýkoli testovací framework:

import assert from "node:assert";
import test, { after, before, describe } from "node:test";
import { unstable_startWorker } from "wrangler";

describe("worker", () => {
	let worker;

	before(async () => {
		worker = await unstable_startWorker({ config: "wrangler.json" });
	});

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

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

Spusťte HTTP server pro testování Workeru.

Po zavolání unstable_dev vrátí fetch() funkce pro volání vašeho Workeru bez nutnosti znát adresu nebo port, a také stop() funkci pro vypnutí serveru HTTP.

Standardně unstable_dev provede integrační testy proti lokálnímu serveru. Pokud chcete provést e2e test proti preview Workeru, předejte local: false v options objekt při volání unstable_dev() funkci. Upozorňujeme, že testy e2e mohou být výrazně pomalejší než integrační testy.

const worker = await unstable_dev(script, options);

• script string

  • Řetězec obsahující cestu ke skriptu Workeru, relativní vůči kořenovému adresáři vašeho projektu Workeru.

• options object volitelné

  • Volitelný objekt options obsahující wrangler dev konfigurační nastavení.
  • Zahrňte experimental objekt uvnitř options pro přístup k experimentálním funkcím, jako je disableExperimentalWarning.
    • Nastavte disableExperimentalWarning na true pro potlačení upozornění Wrangleru na používání unstable_ prefixovaná API.

unstable_dev() vrací objekt obsahující tyto metody:

• fetch() Promise<Response>

  • Odešlete požadavek na váš Worker. Vrátí Promise, který se splní s Response objekt.
  • Viz Fetch.

• stop() Promise<void>

  • Vypne vývojový server.

Při spouštění každé testovací sady použijte beforeAll() funkci pro spuštění unstable_dev(). beforeAll() funkce se používá ke snížení režie: spuštění vývojového serveru trvá několik set milisekund, spouštění a zastavování pro každý jednotlivý test se rychle sčítá a zpomaluje vaše testy.

V každém testovacím případě volejte await worker.fetch(), a ověření, že odpověď odpovídá očekávání.

Chcete-li ukončit sadu testů, zavolejte await worker.stop() v afterAll .

const { unstable_dev } = require("wrangler");

describe("Worker", () => {
	let worker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.js", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});
});

import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("Worker", () => {
	let worker: UnstableDevWorker;

	beforeAll(async () => {
		worker = await unstable_dev("src/index.ts", {
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await worker.stop();
	});

	it("should return Hello World", async () => {
		const resp = await worker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});
});

Můžete testovat Workery, které volají jiné Workery. V příkladu níže označujeme Worker, který volá jiné Workery, jako rodičovský Worker, a volaný Worker jako dětský Worker.

Pokud podřízený Worker ukončíte předčasně, nadřazený Worker se o jeho existenci nedozví a testy selžou.

import { unstable_dev } from "wrangler";

describe("multi-worker testing", () => {
	let childWorker;
	let parentWorker;

	beforeAll(async () => {
		childWorker = await unstable_dev("src/child-worker.js", {
			config: "src/child-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
		parentWorker = await unstable_dev("src/parent-worker.js", {
			config: "src/parent-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await childWorker.stop();
		await parentWorker.stop();
	});

	it("childWorker should return Hello World itself", async () => {
		const resp = await childWorker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});

	it("parentWorker should return Hello World by invoking the child worker", async () => {
		const resp = await parentWorker.fetch();
		const parsedResp = await resp.text();
		expect(parsedResp).toEqual("Parent worker sees: Hello World!");
	});
});

import { unstable_dev } from "wrangler";
import type { UnstableDevWorker } from "wrangler";

describe("multi-worker testing", () => {
	let childWorker: UnstableDevWorker;
	let parentWorker: UnstableDevWorker;

	beforeAll(async () => {
		childWorker = await unstable_dev("src/child-worker.js", {
			config: "src/child-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
		parentWorker = await unstable_dev("src/parent-worker.js", {
			config: "src/parent-wrangler.toml",
			experimental: { disableExperimentalWarning: true },
		});
	});

	afterAll(async () => {
		await childWorker.stop();
		await parentWorker.stop();
	});

	it("childWorker should return Hello World itself", async () => {
		const resp = await childWorker.fetch();
		const text = await resp.text();
		expect(text).toMatchInlineSnapshot(`"Hello World!"`);
	});

	it("parentWorker should return Hello World by invoking the child worker", async () => {
		const resp = await parentWorker.fetch();
		const parsedResp = await resp.text();
		expect(parsedResp).toEqual("Parent worker sees: Hello World!");
	});
});

getPlatformProxy funkce poskytuje způsob, jak získat objekt obsahující proxy (na lokální workerd bindingy) a emulace hodnot specifických pro Cloudflare Workers, což umožňuje jejich emulaci v procesu Node.js.

Jedním z běžných případů použití platform proxy je emulace bindings v aplikacích cílených na Workers, které ale běží mimo Workers runtime (například lokální vývojové servery frameworků běžící v Node.js), nebo pro účely testování (například ověření, že kód správně komunikuje s daným typem bindingu).

const platform = await getPlatformProxy(options);

• options object volitelné
  • Volitelný objekt options obsahující předvolby pro bindings:

    • environment string

      Prostředí, které se má použít.

    • configPath string

      Cesta ke konfiguračnímu souboru, který se má použít.

      Pokud není zadána žádná cesta, výchozím chováním je hledat od aktuálního adresáře směrem nahoru v souborovém systému Konfigurační soubor Wrangler k použití.

      Poznámka: toto pole je volitelné, ale pokud je zadána cesta, musí odkazovat na platný soubor v souborovém systému.

    • persist boolean | { path: string }

      Určuje, zda a kde se mají ukládat data bindings. Pokud true nebo undefined, ve výchozím nastavení používá stejné umístění jako Wrangler, takže si mohou data s volajícím sdílet. Pokud false, do souborového systému se neukládají ani se z něj nečtou žádná data.

      Poznámka: Pokud používáte wrangler's --persist-to možnost, mějte na paměti, že tato možnost přidá podadresář s názvem v3 pod kapotou, zatímco getPlatformProxy's persist ne. Pokud například spustíte wrangler dev --persist-to ./my-directory, pro opětovné použití stejného umístění pomocí getPlatformProxy, budete muset zadat: persist: { path: "./my-directory/v3" }.

    • remoteBindings boolean volitelné (výchozí: `true`)

      Zda vzdálené bindings by mělo být povoleno.

getPlatformProxy() vrací Promise která se přeloží na objekt obsahující následující pole.

• env Record<string, unknown>

  • Objekt obsahující proxy k bindings, které lze používat stejně jako produkční bindings. Odpovídá tvaru env objekt předaný jako druhý argument workerům ve formátu modulů. Ty předávají volání implementacím vazeb spuštěným uvnitř workerd.
  • Tip pro TypeScript: getPlatformProxy<Env>() je generická funkce. Tvar záznamu bindings můžete předat jako argument typu, abyste získali správné typy bez unknown hodnoty.

• cf IncomingRequestCfProperties pouze pro čtení

  • Mock objektu Request's cf vlastnost, která obsahuje data podobná těm, jež byste viděli v produkčním prostředí.

• ctx objekt

  • Mock objekt obsahující implementace waitUntil a passThroughOnException funkce, které nedělají nic.

• caches objekt

  • Emulace Workers caches runtime API.
  • Prozatím operace s cache nedělají nic. Přesnější emulace bude brzy k dispozici.

• dispose() () => Promise<void>

  • Ukončí podkladový workerd proces.
  • Zavolejte toto poté, co program již proxy platformy nepotřebuje. Pokud spouštíte dlouhotrvající proces (například vývojový server), který může proxy využívat neomezeně dlouho, nemusíte tuto funkci volat.

getPlatformProxy funkce používá vazby nalezené v Konfigurační soubor Wrangler. Například pokud máte proměnná prostředí konfigurace nastavená v konfiguračním souboru Wrangler:

{
	"vars": {
		"MY_VARIABLE": "test"
	}
}

[vars]
MY_VARIABLE = "test"

K bindings můžete přistupovat importem getPlatformProxy takto:

import { getPlatformProxy } from "wrangler";

const { env } = await getPlatformProxy();

Pro přístup k hodnotě MY_VARIABLE binding přidejte do svého kódu následující:

console.log(`MY_VARIABLE = ${env.MY_VARIABLE}`);

Tímto se vypíše následující výstup: MY_VARIABLE = test.

Všechny podporované vazby (bindings) nalezené ve vašem Konfigurační soubor Wrangler jsou vám k dispozici prostřednictvím env.

Bindings podporované getPlatformProxy jsou:

• Proměnné prostředí

• Service bindings

• Vazby na KV namespace

• R2 bucket bindings

• Queue bindings

• Bindings databáze D1

• Vazby Hyperdrive

• Workers AI bindings

• Vazby Durable Object

  • Chcete-li použít binding typu Durable Object s getPlatformProxy, vždy zadejte script_name.

    V konfiguračním souboru Wrangler, který čte getPlatformProxy.

    {
      "durable_objects": {
        "bindings": [
          {
            "name": "MyDurableObject",
            "class_name": "MyDurableObject",
            "script_name": "external-do-worker"
          }
        ]
      }
    }

    [[durable_objects.bindings]]
    name = "MyDurableObject"
    class_name = "MyDurableObject"
    script_name = "external-do-worker"

    Budete muset deklarovat svůj Durable Object "MyDurableObject" v jiném Workeru, nazvaném external-do-worker v tomto příkladu.

    ./external-do-worker/src/index.ts

    export class MyDurableObject extends DurableObject {
    	// Your DO code goes here
    }
    
    export default {
    	fetch() {
    		// Doesn't have to do anything, but a DO cannot be the default export
    		return new Response("Hello, world!");
    	},
    };

    Tento Worker také potřebuje konfigurační soubor Wrangler, který vypadá takto:

    {
    	"name": "external-do-worker",
    	"main": "src/index.ts",
    	"compatibility_date": "XXXX-XX-XX"
    }

    name = "external-do-worker"
    main = "src/index.ts"
    compatibility_date = "XXXX-XX-XX"

    Pokud s Durable Object nepoužíváte RPC, můžete vedle vývojového serveru vašeho frameworku spustit samostatnou vývojovou relaci Wrangler.

    Jinak můžete aplikaci sestavit a spustit oba Workery ve stejné relaci Wrangler dev.

    Pokud používáte Pages, spusťte:

    npmyarnpnpm

    npx wrangler pages dev -c path/to/pages/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc

    Pokud používáte Workers with Assets, spusťte:

    npmyarnpnpm

    npx wrangler dev -c path/to/workers-assets/wrangler.jsonc -c path/to/external-do-worker/wrangler.jsonc