INTEGRITY Документация

← Cloudflare Workers / workers / wrangler

API

Wrangler предоставляет API для программного взаимодействия с вашими Cloudflare Workers.

createTestHarness

createTestHarness() запускает один или несколько Workers для интеграционных тестов из любого средства запуска тестов Node.js. Он выполняет production-сборку на основе файлов конфигурации Wrangler, файлов конфигурации, созданных Vite, или встроенных объектов конфигурации Wrangler. API оборачивает Miniflare и предоставляет методы для отправки запросов и событий по расписанию.

Инструкции и примеры по настройке см. в Инфраструктура для интеграционных тестов.

Синтаксис

import { createTestHarness } from "wrangler";

const server = createTestHarness(options);
import { createTestHarness } from "wrangler";

const server = createTestHarness(options);

Параметры

Каждый WorkerInput может загружать Worker из файла конфигурации 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" },
	],
});

Входные данные файла конфигурации поддерживают следующие поля:

Каждый WorkerInput также могут использовать config чтобы передать встроенный объект конфигурации 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() возвращает TestHarness объект со следующими методами:

getWorker(name?) возвращает WorkerHandle объект со следующими методами:

Использование

В этом примере используется встроенный тест-раннер 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");
	});
});

experimental_generateTypes

Генерирует определения типов TypeScript на основе конфигурации вашего Worker. Этот API использует ту же базовую логику, что и wrangler types CLI-команду, поэтому вывод остается согласованным между CLI и программным API.

В отличие от команды CLI, experimental_generateTypes не записывает на диск автоматически. Вместо этого он возвращает сгенерированное содержимое типов в виде структурированных строк, чтобы вы могли обработать их по своему усмотрению.

Синтаксис

import { experimental_generateTypes } from "wrangler";

const result = await experimental_generateTypes(options);

Параметры

Возвращаемый тип

experimental_generateTypes() возвращает Promise, разрешающийся в объект со следующими полями:

Использование

Вы можете использовать experimental_generateTypes чтобы сгенерировать типы программно и самостоятельно записать их на диск либо передать другим инструментам:

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");

Чтобы сгенерировать только типы env, без типов runtime:

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

Чтобы сгенерировать типы для конкретного окружения с пользовательским именем интерфейса:

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

unstable_startWorker

Этот API открывает доступ к внутреннему устройству dev-сервера Wrangler и позволяет настраивать его работу. Например, вы можете использовать unstable_startWorker() для запуска интеграционных тестов для вашего Worker. В этом примере используется node:test, но должно подходить для любого тестового фреймворка:

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();
	});
});

unstable_dev

Запустите HTTP-сервер для тестирования Worker.

После вызова unstable_dev вернёт fetch() функция для вызова вашего Worker без необходимости знать адрес или порт, а также stop() функцию для остановки HTTP-сервера.

По умолчанию unstable_dev выполнит интеграционные тесты на локальном сервере. Если вы хотите выполнить e2e-тест на предварительном Worker, передайте local: false в options объект при вызове unstable_dev() функция. Обратите внимание, что e2e-тесты могут выполняться значительно медленнее, чем интеграционные тесты.

Конструктор

const worker = await unstable_dev(script, options);

Параметры

Возвращаемый тип

unstable_dev() возвращает объект со следующими методами:

Использование

При запуске каждого набора тестов используйте beforeAll() функцию для запуска unstable_dev(). beforeAll() функция используется для минимизации накладных расходов: запуск dev-сервера занимает несколько сотен миллисекунд, а запуск и остановка для каждого отдельного теста быстро накапливаются и замедляют выполнение тестов.

В каждом тестовом случае вызывайте await worker.fetch(), и проверьте, что ответ соответствует ожидаемому.

Чтобы завершить набор тестов, вызовите await worker.stop() в afterAll функцию.

Пример одного Worker

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!"`);
	});
});

Пример с несколькими Workers

Можно тестировать Workers, которые вызывают другие Workers. В примере ниже Worker, вызывающий другие Workers, называется родительским Worker, а вызываемый Worker называется дочерним Worker.

Если вы преждевременно завершите работу дочернего Worker, родительский Worker не будет знать о его существовании, и тесты завершатся с ошибкой.

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

getPlatformProxy функция предоставляет способ получить объект, содержащий прокси (к локальный workerd привязок) и эмуляции специфичных для Cloudflare Workers значений, что позволяет эмулировать их в процессе Node.js.

Один из распространенных случаев использования platform proxy: эмуляция привязок в приложениях, ориентированных на Workers, но выполняющихся вне среды выполнения Workers (например, локальные серверы разработки фреймворков, работающие в Node.js), либо для целей тестирования (например, чтобы убедиться, что код корректно взаимодействует с определенным типом привязки).

Синтаксис

const platform = await getPlatformProxy(options);

Параметры

Возвращаемый тип

getPlatformProxy() возвращает Promise, разрешающийся в объект со следующими полями.

Использование

getPlatformProxy функция использует привязки, найденные в конфигурационный файл Wrangler. Например, если у вас есть переменная окружения конфигурацию, заданную в файле конфигурации Wrangler:

{
	"vars": {
		"MY_VARIABLE": "test"
	}
}
[vars]
MY_VARIABLE = "test"

Доступ к привязкам можно получить, импортировав getPlatformProxy следующим образом:

import { getPlatformProxy } from "wrangler";

const { env } = await getPlatformProxy();

Чтобы получить значение MY_VARIABLE привязку добавьте в свой код следующее:

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

Это выведет следующий результат: MY_VARIABLE = test.

Поддерживаемые привязки

Все поддерживаемые привязки, найденные в конфигурационный файл Wrangler доступны вам через env.

Привязки, поддерживаемые getPlatformProxy это: