wrangler createTestHarness() supports integration testing Workers

Introduced 2026-06-09 · score 0.98

HOW TO USE IT

When writing Worker integration tests with a Node.js test runner, use `createTestHarness()` with Wrangler config paths for the Workers. Start it before tests, then send requests or scheduled events through its handles; reset between tests and close after the suite.

import { after, afterEach, before, test } from "node:test";
import { createTestHarness } from "wrangler";

const server = createTestHarness({
  workers: [
    { configPath: "<path-to-web-worker-wrangler-config>" },
    { configPath: "<path-to-api-worker-wrangler-config>" },
  ],
});
const apiWorker = server.getWorker("<api-worker-name>");

before(async () => { await server.listen(); });
afterEach(async () => { await server.reset(); });
after(async () => { await server.close(); });

test("dispatches a request", async () => {
  const response = await server.fetch("<url-matching-configured-route>");
});

test("dispatches directly and triggers a scheduled event", async () => {
  await apiWorker.fetch("<request-url>");
  await apiWorker.scheduled({ cron: "<cron-expression>", scheduledTime: new Date() });
});

server.getLogs();
// On test failure:
server.debug();

const server = createTestHarness({
  workers: [{ configPath: "<generated-vite-worker-wrangler-config>" }],
});

WHY THIS HELPS

When writing integration tests for Workers built by Wrangler or the Cloudflare Vite plugin, run them in a local preview environment using production build output.

REQUIREMENTS AND LIMITATIONS

Version: 4.99.0
workers (required): Worker inputs for the test server; the first Worker is primary.
configPath (required): Wrangler configuration file path or URL; relative paths resolve from `root`.
root: Base directory for resolving relative Worker config paths; defaults to `process.cwd()`.
env: Wrangler environment to load from the config file.
scheduled({ cron, scheduledTime }) (required): Dispatches a scheduled event directly to the selected Worker; documented example supplies a cron expression and `new Date()`.
listen() (required): Starts the test server.
reset(): Restores the options used when the current session started and recreates storage; the URL may change.
close() (required): Stops the server and releases runtime resources.
getLogs(): Returns captured Workers runtime logs for the current server session.
debug(): Prints a diagnostic timeline including server events and captured Workers runtime logs.
Prerequisite: Use a Node.js test runner and install `wrangler` as a development dependency.
Prerequisite: For Cloudflare Vite plugin Workers, run `npx vite build` first so tests use production build output.
Runs Workers in a local preview environment using production build output.
Works with Wrangler projects and Workers built by the Cloudflare Vite plugin.
Use from a Node.js test runner.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

wrangler createTestHarness() supports integration testing Workers