[Workers] integration testing guide with createTestHarness()

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

@@ -0,0 +1,80 @@
+---
+title: Run Worker integration tests with createTestHarness
+description: Test Workers as applications from Node.js test runners.
+products:
+  - workers
+date: 2026-06-16
+publish_future_dated_entry: true
+---
+
+import { TypeScriptExample } from "~/components";
+
+Wrangler now provides `createTestHarness()`, an API for testing Workers as applications from any Node.js test runner. It works with Wrangler projects and projects built with the [Cloudflare Vite plugin](/workers/vite-plugin/).
+
+Use `createTestHarness()` when you want tests to exercise your Worker as an application, using the same build output and configuration that Wrangler or the [Cloudflare Vite plugin](/workers/testing/test-harness/examples/#test-workers-built-by-the-cloudflare-vite-plugin) produces. The test harness starts a local Worker server and provides helpers for [dispatching requests](/workers/testing/test-harness/examples/#test-multiple-workers-and-route-dispatch), [resetting storage](/workers/testing/test-harness/write-your-first-test/#create-a-test-harness), and [inspecting runtime logs](/workers/testing/test-harness/examples/#assert-against-worker-logs).
+
+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="test/index.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 mock = setupServer();
+const server = createTestHarness({
+	workers: [
+		/** Includes `"routes": ["example.com/*"]` */
+		{ configPath: "./web/wrangler.jsonc" },
+		/** Includes `"routes": ["api.example.com/v1/*"]` */
+		{ configPath: "./api/wrangler.jsonc" },
+	],
+});
+
+beforeAll(async () => {
+	mock.listen({ onUnhandledRequest: "error" });
+	await server.listen();
+});
+
+afterEach(async () => {
+	mock.resetHandlers();
+	await server.reset();
+});
+
+afterAll(async () => {
+	mock.close();
+	await server.close();
+});
+
+test("routes requests to each Worker", async ({ expect }) => {
+	mock.use(
+		http.get("http://identity.example.com/profile/:id", ({ params }) => {
+			return HttpResponse.json({ id: params.id, name: "Ada" });
+		})
+	);
+
+	const apiResponse = await server.fetch(
+		"https://api.example.com/v1/users/123"
+	);
+	expect(await apiResponse.text()).toContain("Ada");
+
+	const webResponse = await server.fetch(
+		"https://example.com/users/123"
+	);
+	expect(await webResponse.text()).toContain("Ada");
+});
+```
+
+</TypeScriptExample>
+
+> For unit tests, Cloudflare recommends [`@cloudflare/vitest-pool-workers`](/workers/testing/vitest-integration/).
+
+For setup steps and more patterns, see the [Test harness guide](/workers/testing/test-harness/) and [examples](/workers/testing/test-harness/examples/).

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

@@ -1,37 +1,47 @@
 ---
 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";
+import { LinkButton } from "~/components";
 
-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.
+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.
 
-<LinkButton href="/workers/testing/vitest-integration/write-your-first-test/">
+## Unit tests
+
+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.
+
+The Workers Vitest integration provides:
+
+- 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.
+
+<LinkButton
+	variant="secondary"
+	href="/workers/testing/vitest-integration/write-your-first-test/"
+>
 	Get started with Vitest
 </LinkButton>
 
-## Testing comparison matrix
-
-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.
-
-| 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               | ❌                                                        | ✅                                                                 | ✅                                                           |
-
-<Render file="testing-pages-functions" product="workers" />
+## Integration tests
+
+Use [`createTestHarness()`](/workers/testing/test-harness/) when you want confidence that the Worker behaves correctly as an application. It lets any Node.js test runner dispatch requests to the running Worker, rather than importing handler code and calling it directly.
+
+`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.
+
+<LinkButton
+	variant="secondary"
+	href="/workers/testing/test-harness/write-your-first-test/"
+>
+	Write your first integration test
+</LinkButton>

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.