infochanged

Workers - Run integration tests against your Worker's production build

Announced: 2026-07-27
Tags: Workers
Severity: info, set by reef/rss-rule-v1
Source: https://developers.cloudflare.com/changelog/post/2026-07-21-integration-test-harness/

Wrangler now provides <code>createTestHarness()</code>, an API for running integration tests against Workers built with <a href="https://developers.cloudflare.com/workers/testing/test-harness/configure/#configure-worker-projects">Wrangler or the Cloudflare Vite plugin</a> from any Node.js test runner. The test harness starts a local Worker server with <a href="https://developers.cloudflare.com/workers/wrangler/api/#createtestharness">helpers for dispatching requests, resetting storage, and inspecting runtime logs</a>. This is useful for tests that need to: <ul> <li><a href="https://developers.cloudflare.com/workers/testing/test-harness/interact-with-workers/#test-route-dispatch-across-workers">Route requests across multiple Workers</a></li> <li><a href="https://developers.cloudflare.com/workers/testing/test-harness/integrations/#mock-service-worker">Mock outbound <code>fetch()</code> requests</a> with Node.js request mocking libraries such as <a href="https://mswjs.io/" target="_blank" rel="noopener">MSW ↗︎</a></li> <li><a href="https://developers.cloudflare.com/workers/testing/test-harness/integrations/#playwright">Run Playwright tests against a Worker</a></li> </ul> For example, this test starts two Workers and mocks an upstream API: <div><div data-nb-tabs data-nb-sync-key="workersExamples" class><div class="relative flex border-b border-border" role="tablist" data-nb-tabs-list></div><div class="mt-3"><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="JavaScript" class><figure class="nb-code-figure nb-code-figure-titled" data-nb-lang="js"><figcaption class="nb-code-title">tests/vitest.test.jsjs</figcaption><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="js" data-nb-lang="js"><code>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: [ /** Includes "routes": ["example.com/*"] */ { configPath: "./workers/web/wrangler.jsonc" }, /** Includes "routes": ["api.example.com/v1/*"] */ { 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(); }); test("routes requests to each Worker", async ({ expect }) => { // Mock the outbound fetch used to load user profiles. network.use( http.get("http://identity.example.com/profile/123", ({ params }) => { return HttpResponse.json({ id: 123, name: "Ada" }); }), ); const apiWorkerResponse = await server.fetch( "http://api.example.com/v1/users/123", ); expect(await apiWorkerResponse.json()).toEqual({ id: 123, name: "Ada", }); const webWorkerResponse = await server.fetch("http://example.com/users/123"); expect(await webWorkerResponse.text()).toBe("Profile: Ada"); });</code></pre></figure></div><div role="tabpanel" data-nb-tabs-content data-nb-tab-label="TypeScript" class><figure class="nb-code-figure nb-code-figure-titled" data-nb-lang="ts"><figcaption class="nb-code-title">tests/vitest.test.tsts</figcaption><pre class="astro-code astro-code-themes github-light github-dark nb-shiki-c6xiwz" tabindex="0" data-language="ts" data-nb-lang="ts"><code>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: [ /** Includes "routes": ["example.com/*"] */ { configPath: "./workers/web/wrangler.jsonc" }, /** Includes "routes": ["api.example.com/v1/*"] */ { 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(); }); test("routes requests to each Worker", async ({ expect }) => { // Mock the outbound fetch used to load user profiles. network.use( http.get("http://identity.example.com/profile/123", ({ params }) => { return HttpResponse.json({ id: 123, name: "Ada" }); }), ); const apiWorkerResponse = await server.fetch( "http://api.example.com/v1/users/123", ); expect(await apiWorkerResponse.json()).toEqual({ id: 123, name: "Ada", }); const webWorkerResponse = await server.fetch("http://example.com/users/123"); expect(await webWorkerResponse.text()).toBe("Profile: Ada"); });</code></pre></figure></div></div></div><script type="module" src="https://developers.cloudflare.com/home/runner/work/cloudflare-docs/cloudflare-docs/src/components/ui/tabs/Tabs.astro?astro&type=script&index=0&lang.ts"></script></div> Cloudflare now recommends <code>createTestHarness()</code> for integration tests instead of <a href="https://developers.cloudflare.com/workers/testing/unstable_startworker/"><code>unstable_startWorker()</code></a> or <a href="https://developers.cloudflare.com/workers/wrangler/api/#unstable_dev"><code>unstable_dev()</code></a>. To start a development server programmatically, use the Vite <a href="https://vite.dev/guide/api-javascript.html#createserver" target="_blank" rel="noopener"><code>createServer()</code> ↗︎</a> API with the <a href="https://developers.cloudflare.com/workers/vite-plugin/">Cloudflare Vite plugin</a>. For more information about <code>createTestHarness()</code>, refer to the <a href="https://developers.cloudflare.com/workers/testing/test-harness/">Integration test harness guide</a>.

The text above is the source's. reef added the severity, the dates it could read from the text, and the endpoints and scopes named in code.