配置测试 harness

createTestHarness() 在单个本地服务器中运行一个或多个 Worker。每个 Worker 可以来自 Wrangler 项目，或使用 Cloudflare Vite 插件的 Vite 项目。

配置 Worker 项目

将 workers 数组中的每一项指向项目的 Wrangler 配置文件：

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

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

对于由 Cloudflare Vite 插件构建的 Worker，请先运行 vite build，以便测试使用生产构建输出：

npx vite build

yarn vite build

pnpm vite build

生成的 Wrangler 配置的工作方式与任何其他 configPath 相同。每个 Worker 独立配置，因此一个 harness 可以同时运行两种项目类型：

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 环境

默认情况下，测试 harness 加载顶层 Wrangler 配置。若要从配置中加载特定环境，请设置 env。

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

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

覆盖变量和密钥

如果你不想为测试创建单独的 Wrangler 环境，可以为 harness 中的每个 Worker 覆盖 vars 和 secrets。

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" },
		},
	],
});

在设置后配置 harness

如果部分 Worker 配置依赖于测试设置，可以先不带选项调用 createTestHarness()，然后在启动服务器之前用 server.update() 配置 harness。

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

在测试之间重置 harness

跨测试复用服务器时，请在每次测试后调用 server.reset()。它会重新创建本地存储，并将 Worker 恢复为当前会话启动时使用的选项。

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

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

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

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

重置后，请再次应用所需的 schema 迁移并填充种子数据。示例请参阅准备测试状态。

测试失败时打印调试输出

server.debug() 会打印服务器时间线和捕获的 Workers 运行时日志。当测试抛出异常或失败、且你需要更多信息来调试时，请调用它。

以下示例使用 Vitest 的 cleanup hook：

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 handle 指定类型

server.getWorker() 接受 Worker 环境和模块导出的类型。你可以手动定义这些类型。但为了让它们与 Worker 保持一致，可以根据 Wrangler 配置生成 env 类型，并从源模块推导导出。

为每个 Worker 提供不同的环境接口，以便生成的声明可以一起使用：

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

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

pnpm 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 方法。Worker 配置变更时，请重新运行 wrangler types。