JA EN
shiichan

You can now run integration tests against your Worker's production build!

Cloudflare Changelog ★★★★ View Markdown
#cloudflare#serverless#devops

Hey there, it's me! Today I've got a nice update for anyone writing Workers — something that makes testing a bit easier. Let's dive in.

Cloudflare Changelog developers.cloudflare.com

What was announced?

According to Cloudflare's Changelog, Wrangler now has a new API called createTestHarness(). It lets you run integration tests against Workers built with Wrangler or the Cloudflare Vite plugin, from any Node.js test runner. It spins up a local Worker server and takes care of things like dispatching requests, resetting storage, and inspecting runtime logs.

It's a good fit for things like:

  • Testing how requests get routed across multiple Workers
  • Mocking outbound fetch() calls with Node.js request-mocking libraries like MSW
  • Running Playwright tests against a Worker

The story so far

There were already ways to run a Worker locally for testing, but wiring up multiple Workers together, or mocking outbound API calls, meant building that setup yourself. Running integration tests against something close to your actual production build added even more setup work on top of that.

What changes

With createTestHarness(), starting multiple Workers, checking how requests route between them, and combining that with mocking all live behind one API. It works with Vitest and, in principle, any Node.js test runner, so it should slot into your existing test setup without much friction.

Dive Deep

The example in the Changelog imports createTestHarness() from wrangler and passes the configPath of each Worker to the workers option.

import { afterAll, afterEach, beforeAll, test } from "vitest";
import { http, HttpResponse } from "msw";
import { setupServer } from "msw/node";
import { createTestHarness } from "wrangler";

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

beforeAll(async () => {
  network.listen({ onUnhandledRequest: "error" });
  await server.listen();
});

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

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

beforeAll starts both the MSW network mock and the Worker server, afterEach resets handlers and storage, and afterAll shuts everything down. On top of that setup, you send requests to your Worker inside test() while using network.use() to mock an external API — in the Changelog's example, an identicon image API. The full API surface is documented in the "Integration test harness guide," apparently.

Wrap-up

Here's a recap.

  • Wrangler added createTestHarness() for running integration tests against your Worker's production build
  • You can test routing across multiple Workers
  • Outbound fetch() calls can be mocked with tools like MSW
  • It also pairs with Playwright tests
  • beforeAll / afterEach / afterAll handle setup and cleanup for you

If your team runs multiple Workers together, or has struggled with testing external API integrations, this is worth trying out next week!

Related posts