[Workers] integration testing guide with createTestHarness()

src/content/changelog/workers/2026-06-18-test-harness-api.mdx

@@ -0,0 +1,84 @@
+---
+title: Run integration tests against your Worker's production build
+description: Use Wrangler's `createTestHarness()` API to test production build output from any Node.js test runner.
+products:
+  - workers
+date: 2026-06-18
+publish_future_dated_entry: true
+---
+
+import { TypeScriptExample } from "~/components";
+
+Wrangler now provides `createTestHarness()`, an API for running integration tests against Workers from any Node.js test runner. It works with Workers built with Wrangler or the [Cloudflare Vite plugin](/workers/testing/test-harness/examples/#test-workers-built-by-the-cloudflare-vite-plugin).
+
+The test harness created by `createTestHarness()` starts a local Worker server and [provides helpers for dispatching requests, resetting storage, and inspecting runtime logs](/workers/wrangler/api/#createtestharness).
+
+This is useful for tests that need to:
+
+- [Route requests across multiple Workers](/workers/testing/test-harness/examples/#test-multiple-workers-and-route-dispatch).
+- [Mock outbound `fetch()` requests](/workers/testing/test-harness/examples/#mock-outbound-requests) with Node.js request mocking libraries such as [MSW](https://mswjs.io/).
+- [Run Playwright tests against a Worker started by the test harness](/workers/testing/test-harness/examples/#use-with-playwright).
+
+For example, this test starts two Workers and mocks an upstream API:
+
+<TypeScriptExample filename="tests/vitest.test.ts">
+
+```ts
+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/:id", ({ params }) => {
+			return HttpResponse.json({ id: params.id, name: "Ada" });
+		})
+	);
+
+	const apiResponse = await server.fetch(
+		"http://api.example.com/v1/users/123"
+	);
+	expect(await apiResponse.json()).toEqual({
+		id: "123",
+		name: "Ada",
+	});
+
+	const webResponse = await server.fetch(
+		"http://example.com/users/123"
+	);
+	expect(await webResponse.text()).toBe("Profile: Ada");
+});
+```
+
+</TypeScriptExample>
+
+Cloudflare now recommends `createTestHarness()` for integration tests instead of [`unstable_startWorker()`](/workers/testing/unstable_startworker/) or [`unstable_dev()`](/workers/wrangler/api/#unstable_dev). If you need to start a development server programmatically, use the Vite [`createServer()`](https://vite.dev/guide/api-javascript.html#createserver) API with the Cloudflare Vite plugin.
+
+Follow the [Test harness guide](/workers/testing/test-harness/) to write your first test with `createTestHarness()`.

src/content/docs/workers/testing/index.mdx

@@ -1,37 +1,35 @@
 ---
 pcx_content_type: navigation
 title: Testing
-description: Compare testing options for Cloudflare Workers, including Vitest integration, Miniflare, and unstable_startWorker.
+description: Choose testing tools for Cloudflare Workers, including createTestHarness and the Vitest integration.
 sidebar:
   order: 14
 products:
   - workers
 ---
 
-import { Render, LinkButton } from "~/components";
+The Workers platform offers multiple testing tools for different parts of your application. For most projects, use the [Workers Vitest integration](/workers/testing/vitest-integration/) for unit tests and [`createTestHarness()`](/workers/testing/test-harness/) for integration tests. These tools can be used together in the same project.
 
-The Workers platform has a variety of ways to test your applications, depending on your requirements. We recommend using the [Vitest integration](/workers/testing/vitest-integration), which allows you to run tests _inside_ the Workers runtime, and unit test individual functions within your Worker.
+## Unit tests
 
-<LinkButton href="/workers/testing/vitest-integration/write-your-first-test/">
-	Get started with Vitest
-</LinkButton>
+Use the [Workers Vitest integration](/workers/testing/vitest-integration/) when you want fast feedback on functions and modules. Tests run inside the Workers runtime, so your test code can access bindings and runtime APIs directly.
 
-## Testing comparison matrix
+The Workers Vitest integration provides:
 
-However, if you don't use Vitest, both [Miniflare's API](/workers/testing/miniflare/writing-tests) and the [`unstable_startWorker()`](/workers/wrangler/api/#unstable_startworker) API provide options for testing your Worker in any testing framework.
+- Fast feedback while testing individual functions and modules.
+- Direct assertions against binding state, such as values written to KV, R2, D1, or Durable Objects.
+- Direct calls to Durable Objects and other runtime APIs.
 
-| Feature                               | [Vitest integration](/workers/testing/vitest-integration) | [`unstable_startWorker()`](/workers/testing/unstable_startworker/) | [Miniflare's API](/workers/testing/miniflare/writing-tests/) |
-| ------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------ |
-| Unit testing                          | ✅                                                        | ❌                                                                 | ❌                                                           |
-| Integration testing                   | ✅                                                        | ✅                                                                 | ✅                                                           |
-| Loading Wrangler configuration files  | ✅                                                        | ✅                                                                 | ❌                                                           |
-| Use bindings directly in tests        | ✅                                                        | ❌                                                                 | ✅                                                           |
-| Isolated per-test storage             | ✅                                                        | ❌                                                                 | ❌                                                           |
-| Outbound request mocking              | ✅                                                        | ❌                                                                 | ✅                                                           |
-| Multiple Worker support               | ✅                                                        | ✅                                                                 | ✅                                                           |
-| Direct access to Durable Objects      | ✅                                                        | ❌                                                                 | ❌                                                           |
-| Run Durable Object alarms immediately | ✅                                                        | ❌                                                                 | ❌                                                           |
-| List Durable Objects                  | ✅                                                        | ❌                                                                 | ❌                                                           |
-| Testing service Workers               | ❌                                                        | ✅                                                                 | ✅                                                           |
+To set up unit tests, refer to [Write your first Vitest test](/workers/testing/vitest-integration/write-your-first-test/).
 
-<Render file="testing-pages-functions" product="workers" />
+## Integration tests
+
+Use [`createTestHarness()`](/workers/testing/test-harness/) when you want tests to run against Workers built by Wrangler or the [Cloudflare Vite plugin](/workers/vite-plugin/). It lets any Node.js test runner dispatch requests to a running local Worker.
+
+`createTestHarness()` provides:
+
+- Tests that run the production build output produced by Wrangler or Vite.
+- Requests dispatched through configured Worker routes.
+- Coverage for a multi-Worker application as a whole.
+
+To set up integration tests, refer to [Write your first integration test](/workers/testing/test-harness/write-your-first-test/).

src/content/docs/workers/testing/miniflare/index.mdx

@@ -3,7 +3,7 @@ title: Miniflare
 description: Simulate and test Cloudflare Workers locally with Miniflare, a fully-local development simulator.
 pcx_content_type: navigation
 sidebar:
-  order: 16
+  order: 17
 head:
   - tag: title
     content: Miniflare

src/content/docs/workers/testing/miniflare/writing-tests.mdx

@@ -14,7 +14,7 @@ import { TabItem, Tabs, Details, PackageManagers } from "~/components";
 import { FileTree } from "@astrojs/starlight/components";
 
 :::note
-For most users, Cloudflare recommends using the Workers Vitest integration. If you have been using test environments from Miniflare, refer to the [Migrate from Miniflare 2 guide](/workers/testing/vitest-integration/migration-guides/migrate-from-miniflare-2/).
+For most users, Cloudflare recommends using the [Workers Vitest integration](/workers/testing/vitest-integration/) for unit tests and [`createTestHarness()`](/workers/testing/test-harness/) for integration tests. Use Miniflare directly when you need low-level simulator control that is not exposed by those higher-level testing APIs.
 :::
 
 This guide will show you how to set up [Miniflare](/workers/testing/miniflare) to test your Workers. Miniflare is a low-level API that allows you to fully control how your Workers are run and tested.