← Cloudflare Workers / workers / testing / test-harness

Настройка инфраструктуры для тестирования

createTestHarness() запускает один или несколько Worker на одном локальном сервере. Каждый Worker может быть из проекта Wrangler или из проекта Vite, использующего плагин Cloudflare Vite.

Настройте проекты Worker

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

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

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

Для Workers, созданных с помощью Cloudflare Vite plugin, выполните vite build сначала, чтобы тесты использовали результат production-сборки:

npx vite build

Сгенерированная конфигурация Wrangler работает так же, как и любая другая configPath. Каждый Worker настраивается независимо, поэтому один набор инструментов может запускать оба типа проектов:

const server = createTestHarness({
	workers: [
		// Wrangler project
		{ configPath: "./workers/api/wrangler.jsonc" },
		// Vite project (built output from the Cloudflare Vite plugin)
		{ configPath: "./dist/web_worker/wrangler.json" },
	],
});

const server = createTestHarness({
	workers: [
		// Wrangler project
		{ configPath: "./workers/api/wrangler.jsonc" },
		// Vite project (built output from the Cloudflare Vite plugin)
		{ configPath: "./dist/web_worker/wrangler.json" },
	],
});

Выберите окружение Wrangler

По умолчанию тестовое окружение загружает конфигурацию Wrangler верхнего уровня. Задайте env если хотите загрузить определённое окружение из конфигурации.

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

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

Переопределение переменных и секретов

Можно переопределить vars и secrets для каждого Worker в тестовом окружении, если вы хотите избежать создания отдельного окружения Wrangler для тестирования.

const server = createTestHarness({
	workers: [
		{
			configPath: "./wrangler.jsonc",
			vars: { API_HOST: "http://identity.example.com" },
			secrets: { API_TOKEN: "test-token" },
		},
	],
});

const server = createTestHarness({
	workers: [
		{
			configPath: "./wrangler.jsonc",
			vars: { API_HOST: "http://identity.example.com" },
			secrets: { API_TOKEN: "test-token" },
		},
	],
});

Настройка инфраструктуры для тестирования после установки

Если часть конфигурации Worker зависит от настроек теста, вы можете вызвать createTestHarness() без параметров и настройте окружение с помощью server.update() перед запуском сервера.

const server = createTestHarness();
let upstream;

beforeAll(async () => {
	upstream = await startLocalApi();

	await server.update({
		workers: [
			{
				configPath: "./wrangler.jsonc",
				vars: { API_HOST: upstream.url },
			},
		],
	});

	await server.listen();
});

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

const server = createTestHarness();
let upstream: { url: string; close(): Promise<void> };

beforeAll(async () => {
	upstream = await startLocalApi();

	await server.update({
		workers: [
			{
				configPath: "./wrangler.jsonc",
				vars: { API_HOST: upstream.url },
			},
		],
	});

	await server.listen();
});

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

Сбрасывать тестовое окружение между тестами

При повторном использовании сервера в разных тестах вызывайте server.reset() после каждого теста. Он заново создает локальное хранилище и возвращает Workers к параметрам, с которыми была запущена текущая сессия.

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

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

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

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

После сброса примените необходимые миграции схемы и заново загрузите начальные данные. Примеры см. в Подготовьте тестовое состояние.

Выводить отладочную информацию при сбое тестов

server.debug() выводит хронологию сервера и записанные логи среды выполнения Workers. Вызывайте эту функцию, когда тест выбрасывает исключение или завершается с ошибкой и вам нужно больше информации для отладки.

В следующем примере используется хук очистки из Vitest:

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

afterEach(({ task }) => {
	if (task.result?.state === "fail") {
		server.debug();
	}
});

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

afterEach(({ task }) => {
	if (task.result?.state === "fail") {
		server.debug();
	}
});

Укажите типы для дескрипторов Worker

server.getWorker() принимает типы для окружения Worker и экспортов модуля. Эти типы можно задать вручную. Но чтобы они не расходились с самим Worker, можно сгенерировать тип env из конфигурации Wrangler и вывести экспорты из его исходного модуля.

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

npx wrangler types ./workers/api/worker-configuration.d.ts --config ./workers/api/wrangler.jsonc --env-interface ApiEnv

Повторите эту команду для каждого Worker и добавьте сгенерированные файлы в конфигурацию TypeScript для тестов:

{
	"include": ["./workers/*/worker-configuration.d.ts", "./tests/**/*.ts"]
}

Передайте сгенерированный интерфейс окружения в server.getWorker(). Используйте typeof import() чтобы получить экспорты Worker из исходного модуля:

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

const apiWorker = server.getWorker<
	ApiEnv,
	typeof import("../workers/api/index")
>("api-worker");

В этом примере ApiEnv берётся из worker-configuration.d.ts. Тип модуля включает экспорт по умолчанию и его RPC-методы. Повторно запустите wrangler types при изменении конфигурации Worker.