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

2026年7月27日

Wrangler は createTestHarness() を提供するようになりました。これは、Wrangler または Cloudflare Vite plugin でビルドした Worker に対して、任意の Node.js テストランナーから統合テストを実行するための API です。テストハーネスは、リクエストの送信、ストレージのリセット、ランタイムログの検査用のヘルパーを備えたローカル Worker サーバを起動します。これは次のようなテストに便利です：

• 複数の Worker 間でリクエストをルーティングするテスト
• MSW のような Node.js リクエストモッキングライブラリを使って outbound fetch() をモックするテスト
• Worker に対して Playwright テストを実行する場合

例えば、次のテストは 2 つの Worker を起動し、上流 API をモックします。

tests/vitest.test.js

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" );
});

tests/vitest.test.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/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" );
});

Cloudflare は統合テストにおいて、unstable_startWorker() や unstable_dev() の代わりに createTestHarness() の使用を推奨します。プログラムから開発サーバを起動する場合は、Cloudflare Vite plugin と Vite の createServer() ↗ API を使用してください。createTestHarness() の詳細は Integration test harness guide を参照してください。