Test harness for production Worker builds
1 featureThis release1 featureNew capabilitiesAI-tallied from the release notes
From the original release noteView original ↗
Wrangler now provides createTestHarness(), an API for running integration tests against Workers built with Wrangler or the Cloudflare Vite plugin from any Node.js test runner.
The test harness starts a local Worker server with helpers for dispatching requests, resetting storage, and inspecting runtime logs.
This is useful for tests that need to:
- Route requests across multiple Workers
- Mock outbound
fetch()requests with Node.js request mocking libraries such as MSW ↗ - Run Playwright tests against a Worker
For example, this test starts two Workers and mocks an upstream API:
tests/vitest.test.jsjs
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { afterAll, afterEach, beforeAll, test } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "vitest"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { http, HttpResponse } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "msw"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { setupServer } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "msw/node"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { createTestHarness } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "wrangler"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1itgoe">const</span><span class="nb-shiki-dzsirb"> network</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1t8gfj"> setupServer</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-1itgoe">const</span><span class="nb-shiki-dzsirb"> server</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1t8gfj"> createTestHarness</span><span class="nb-shiki-140thh">({</span></span>
<span class="line"><span class="nb-shiki-140thh"> workers: [</span></span>
<span class="line"><span class="nb-shiki-21nrsd"> /** Includes `"routes": ["example.com/*"]` */</span></span>
<span class="line"><span class="nb-shiki-140thh"> { configPath: </span><span class="nb-shiki-mdbnqw">"./workers/web/wrangler.jsonc"</span><span class="nb-shiki-140thh"> },</span></span>
<span class="line"><span class="nb-shiki-21nrsd"> /** Includes `"routes": ["api.example.com/v1/*"]` */</span></span>
<span class="line"><span class="nb-shiki-140thh"> { configPath: </span><span class="nb-shiki-mdbnqw">"./workers/api/wrangler.jsonc"</span><span class="nb-shiki-140thh"> },</span></span>
<span class="line"><span class="nb-shiki-140thh"> ],</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">beforeAll</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> () </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">listen</span><span class="nb-shiki-140thh">({ onUnhandledRequest: </span><span class="nb-shiki-mdbnqw">"error"</span><span class="nb-shiki-140thh"> });</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">listen</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">afterEach</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> () </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">resetHandlers</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">reset</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">afterAll</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> () </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">close</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">close</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">test</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"routes requests to each Worker"</span><span class="nb-shiki-140thh">, </span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> ({ </span><span class="nb-shiki-1jdh33">expect</span><span class="nb-shiki-140thh"> }) </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-21nrsd"> // Mock the outbound fetch used to load user profiles.</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">use</span><span class="nb-shiki-140thh">(</span></span>
<span class="line"><span class="nb-shiki-140thh"> http.</span><span class="nb-shiki-1t8gfj">get</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"http://identity.example.com/profile/123"</span><span class="nb-shiki-140thh">, ({ </span><span class="nb-shiki-1jdh33">params</span><span class="nb-shiki-140thh"> }) </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> return</span><span class="nb-shiki-140thh"> HttpResponse.</span><span class="nb-shiki-1t8gfj">json</span><span class="nb-shiki-140thh">({ id: </span><span class="nb-shiki-dzsirb">123</span><span class="nb-shiki-140thh">, name: </span><span class="nb-shiki-mdbnqw">"Ada"</span><span class="nb-shiki-140thh"> });</span></span>
<span class="line"><span class="nb-shiki-140thh"> }),</span></span>
<span class="line"><span class="nb-shiki-140thh"> );</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1itgoe"> const</span><span class="nb-shiki-dzsirb"> apiWorkerResponse</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">fetch</span><span class="nb-shiki-140thh">(</span></span>
<span class="line"><span class="nb-shiki-mdbnqw"> "http://api.example.com/v1/users/123"</span><span class="nb-shiki-140thh">,</span></span>
<span class="line"><span class="nb-shiki-140thh"> );</span></span>
<span class="line"><span class="nb-shiki-1t8gfj"> expect</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">await</span><span class="nb-shiki-140thh"> apiWorkerResponse.</span><span class="nb-shiki-1t8gfj">json</span><span class="nb-shiki-140thh">()).</span><span class="nb-shiki-1t8gfj">toEqual</span><span class="nb-shiki-140thh">({</span></span>
<span class="line"><span class="nb-shiki-140thh"> id: </span><span class="nb-shiki-dzsirb">123</span><span class="nb-shiki-140thh">,</span></span>
<span class="line"><span class="nb-shiki-140thh"> name: </span><span class="nb-shiki-mdbnqw">"Ada"</span><span class="nb-shiki-140thh">,</span></span>
<span class="line"><span class="nb-shiki-140thh"> });</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1itgoe"> const</span><span class="nb-shiki-dzsirb"> webWorkerResponse</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">fetch</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"http://example.com/users/123"</span><span class="nb-shiki-140thh">);</span></span>
<span class="line"><span class="nb-shiki-1t8gfj"> expect</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">await</span><span class="nb-shiki-140thh"> webWorkerResponse.</span><span class="nb-shiki-1t8gfj">text</span><span class="nb-shiki-140thh">()).</span><span class="nb-shiki-1t8gfj">toBe</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"Profile: Ada"</span><span class="nb-shiki-140thh">);</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>tests/vitest.test.tsts
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { afterAll, afterEach, beforeAll, test } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "vitest"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { http, HttpResponse } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "msw"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { setupServer } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "msw/node"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"><span class="nb-shiki-1itgoe">import</span><span class="nb-shiki-140thh"> { createTestHarness } </span><span class="nb-shiki-1itgoe">from</span><span class="nb-shiki-mdbnqw"> "wrangler"</span><span class="nb-shiki-140thh">;</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1itgoe">const</span><span class="nb-shiki-dzsirb"> network</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1t8gfj"> setupServer</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-1itgoe">const</span><span class="nb-shiki-dzsirb"> server</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1t8gfj"> createTestHarness</span><span class="nb-shiki-140thh">({</span></span>
<span class="line"><span class="nb-shiki-140thh"> workers: [</span></span>
<span class="line"><span class="nb-shiki-21nrsd"> /** Includes `"routes": ["example.com/*"]` */</span></span>
<span class="line"><span class="nb-shiki-140thh"> { configPath: </span><span class="nb-shiki-mdbnqw">"./workers/web/wrangler.jsonc"</span><span class="nb-shiki-140thh"> },</span></span>
<span class="line"><span class="nb-shiki-21nrsd"> /** Includes `"routes": ["api.example.com/v1/*"]` */</span></span>
<span class="line"><span class="nb-shiki-140thh"> { configPath: </span><span class="nb-shiki-mdbnqw">"./workers/api/wrangler.jsonc"</span><span class="nb-shiki-140thh"> },</span></span>
<span class="line"><span class="nb-shiki-140thh"> ],</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">beforeAll</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> () </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">listen</span><span class="nb-shiki-140thh">({ onUnhandledRequest: </span><span class="nb-shiki-mdbnqw">"error"</span><span class="nb-shiki-140thh"> });</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">listen</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">afterEach</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> () </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">resetHandlers</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">reset</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">afterAll</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> () </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">close</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">close</span><span class="nb-shiki-140thh">();</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1t8gfj">test</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"routes requests to each Worker"</span><span class="nb-shiki-140thh">, </span><span class="nb-shiki-1itgoe">async</span><span class="nb-shiki-140thh"> ({ </span><span class="nb-shiki-1jdh33">expect</span><span class="nb-shiki-140thh"> }) </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-21nrsd"> // Mock the outbound fetch used to load user profiles.</span></span>
<span class="line"><span class="nb-shiki-140thh"> network.</span><span class="nb-shiki-1t8gfj">use</span><span class="nb-shiki-140thh">(</span></span>
<span class="line"><span class="nb-shiki-140thh"> http.</span><span class="nb-shiki-1t8gfj">get</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"http://identity.example.com/profile/123"</span><span class="nb-shiki-140thh">, ({ </span><span class="nb-shiki-1jdh33">params</span><span class="nb-shiki-140thh"> }) </span><span class="nb-shiki-1itgoe">=></span><span class="nb-shiki-140thh"> {</span></span>
<span class="line"><span class="nb-shiki-1itgoe"> return</span><span class="nb-shiki-140thh"> HttpResponse.</span><span class="nb-shiki-1t8gfj">json</span><span class="nb-shiki-140thh">({ id: </span><span class="nb-shiki-dzsirb">123</span><span class="nb-shiki-140thh">, name: </span><span class="nb-shiki-mdbnqw">"Ada"</span><span class="nb-shiki-140thh"> });</span></span>
<span class="line"><span class="nb-shiki-140thh"> }),</span></span>
<span class="line"><span class="nb-shiki-140thh"> );</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1itgoe"> const</span><span class="nb-shiki-dzsirb"> apiWorkerResponse</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">fetch</span><span class="nb-shiki-140thh">(</span></span>
<span class="line"><span class="nb-shiki-mdbnqw"> "http://api.example.com/v1/users/123"</span><span class="nb-shiki-140thh">,</span></span>
<span class="line"><span class="nb-shiki-140thh"> );</span></span>
<span class="line"><span class="nb-shiki-1t8gfj"> expect</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">await</span><span class="nb-shiki-140thh"> apiWorkerResponse.</span><span class="nb-shiki-1t8gfj">json</span><span class="nb-shiki-140thh">()).</span><span class="nb-shiki-1t8gfj">toEqual</span><span class="nb-shiki-140thh">({</span></span>
<span class="line"><span class="nb-shiki-140thh"> id: </span><span class="nb-shiki-dzsirb">123</span><span class="nb-shiki-140thh">,</span></span>
<span class="line"><span class="nb-shiki-140thh"> name: </span><span class="nb-shiki-mdbnqw">"Ada"</span><span class="nb-shiki-140thh">,</span></span>
<span class="line"><span class="nb-shiki-140thh"> });</span></span>
<span class="line"></span>
<span class="line"><span class="nb-shiki-1itgoe"> const</span><span class="nb-shiki-dzsirb"> webWorkerResponse</span><span class="nb-shiki-1itgoe"> =</span><span class="nb-shiki-1itgoe"> await</span><span class="nb-shiki-140thh"> server.</span><span class="nb-shiki-1t8gfj">fetch</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"http://example.com/users/123"</span><span class="nb-shiki-140thh">);</span></span>
<span class="line"><span class="nb-shiki-1t8gfj"> expect</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-1itgoe">await</span><span class="nb-shiki-140thh"> webWorkerResponse.</span><span class="nb-shiki-1t8gfj">text</span><span class="nb-shiki-140thh">()).</span><span class="nb-shiki-1t8gfj">toBe</span><span class="nb-shiki-140thh">(</span><span class="nb-shiki-mdbnqw">"Profile: Ada"</span><span class="nb-shiki-140thh">);</span></span>
<span class="line"><span class="nb-shiki-140thh">});</span></span>Cloudflare now recommends createTestHarness() for integration tests instead of unstable_startWorker() or unstable_dev(). To start a development server programmatically, use the Vite createServer() ↗ API with the Cloudflare Vite plugin.
For more information about createTestHarness(), refer to the Integration test harness guide.
Fetched July 27, 2026
