テストハーネスを設定する

createTestHarness() は、1 つ以上の Workers を 1 つのローカルサーバーで実行します。各 Worker は、Wrangler プロジェクト、または Cloudflare Vite plugin を使う Vite プロジェクトから渡せます。

Worker プロジェクトを設定する

workers 配列の各エントリを、プロジェクトの Wrangler 設定ファイルに向けます。

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

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

Cloudflare Vite plugin でビルドする Workers では、先に vite build を実行し、テストが本番ビルド出力を使うようにします。

npx vite build

yarn vite build

pnpm vite build

生成された Wrangler 設定は、他の configPath と同じように使えます。各 Worker は独立して設定されるため、1 つのハーネスで両方のプロジェクト種別を実行できます。

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 の environment を選ぶ

既定では、テストハーネスはトップレベルの Wrangler 設定を読み込みます。設定から特定の environment を読み込む場合は env を設定します。

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

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

変数とシークレットを上書きする

テスト専用の Wrangler environment を作りたくない場合は、ハーネス内の各 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" },
		},
	],
});

セットアップ後にハーネスを設定する

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 runtime のログを表示します。テストが例外を投げるか失敗し、デバッグに情報が必要なときに呼びます。

次の例では、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 の environment とモジュール exports の型を受け取ります。これらの型は手書きでも定義できます。Worker と揃えるには、Wrangler 設定から env 型を生成し、ソースモジュールから exports を導出できます。

生成した宣言をまとめて使えるように、Worker ごとに異なる environment インターフェイスを付けます。

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"]
}

生成した environment インターフェイスを server.getWorker() に渡します。ソースモジュールから Worker の exports を導出するには、typeof import() を使います。

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

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

この例では、ApiEnv は worker-configuration.d.ts から来ます。モジュール型には default export とその RPC メソッドが含まれます。Worker 設定が変わったら、wrangler types を再実行します。