Cloudflare Workers integration test 怎麼寫？用 createTestHarness 測 production build

先分清楚 Vitest 套件更名與 test harness#

Cloudflare 在 2026 年 8 月 19 日把 Workers Vitest integration 從 @cloudflare/vitest-pool-workers 更名為 @cloudflare/vitest-plugin。這個變更會影響使用 Vitest plugin 的專案：要更新依賴名稱、import 與 TypeScript types；Vitest 的設定 API 沒有因此改寫。

如果你的專案同時使用這個 integration，可以先執行官方 codemod：

1
pnpm @cloudflare/codemods vitest:pool-workers-to-vitest-plugin

或手動調整：

1
pnpm remove @cloudflare/vitest-pool-workers
2
pnpm add -D vitest@^4.1.0 @cloudflare/vitest-plugin

1
import { cloudflareTest } from '@cloudflare/vitest-plugin'
2
import { defineConfig } from 'vitest/config'
3

4
export default defineConfig({
5
  plugins: [
6
    cloudflareTest({
7
      wrangler: { configPath: './wrangler.jsonc' },
8
    }),
9
  ],
10
})

TypeScript 測試設定中的 types 也要改成 @cloudflare/vitest-plugin/types。這不代表 createTestHarness() 改了名稱：本文的 harness 仍從 wrangler 匯入，負責在 Node.js test runner 啟動一個或多個 Worker。兩者是互補的測試路徑，不要因為套件改名就把 harness import 一起換掉。

最小 Vitest 範例#

先確認 wrangler 是開發相依套件，且專案有 wrangler.jsonc 或對應設定檔。

1
pnpm add -D wrangler vitest

1
import { afterAll, beforeAll, expect, test } from 'vitest'
2
import { createTestHarness } from 'wrangler'
3

4
const server = createTestHarness({
5
  workers: [{ configPath: './wrangler.jsonc' }],
6
})
7

8
beforeAll(() => server.listen())
9
afterAll(() => server.close())
10

11
test('health endpoint returns 200', async () => {
12
  const response = await server.fetch('/health')
13
  expect(response.status).toBe(200)
14
})

範例的關鍵不是只呼叫 handler，而是由 harness 載入 Worker 專案設定並送出 request。若用 Cloudflare Vite plugin 建置，官方文件要求先執行 vite build，讓測試使用產出的 production build。

多個 Worker 時測 route，而非手動 mock 呼叫#

將每個 Worker 加進 workers，並在各自設定檔宣告 route。絕對 URL 會依 route 對應到目標 Worker；相對 URL 則送到第一個（primary）Worker。

1
const server = createTestHarness({
2
  workers: [
3
    { configPath: './workers/web/wrangler.jsonc' },
4
    { configPath: './workers/api/wrangler.jsonc' },
5
  ],
6
})
7

8
const response = await server.fetch('http://api.example.com/v1/users/42')

這類測試特別適合驗證 route 寫錯、service 之間的 header 傳遞，或 production build 才出現的 module／binding 差異。

外部 fetch 要明確 mock#

Harness 不該讓測試意外呼叫真的第三方 API。Cloudflare 的整合範例使用 MSW：在測試前開始 mock server、對未處理 request 設為 error，並在每次測試後 reset handler。

1
import { afterEach, beforeAll } from 'vitest'
2
import { setupServer } from 'msw/node'
3

4
const network = setupServer()
5
beforeAll(() => network.listen({ onUnhandledRequest: 'error' }))
6
afterEach(() => network.resetHandlers())

若測試須覆寫 vars 或 secrets，請只放無敏感值的測試資料，並在斷言中驗證預期行為，而不是把 production credential 帶進本機或 CI。

加入前的檢查#

1. 先保留快速 unit tests；不是每次變更都要啟動整合環境。
2. 選一條最容易跨邊界失敗的路徑，例如 web → API → mocked upstream。
3. 在 CI 固定執行 build 後的 integration test，讓測試目標與部署輸入一致。
4. 把外部 request 設為未 mock 即失敗，避免測試不穩定或意外產生費用。

若整合測試失敗時需要先觀察本機 bindings、logs 與 traces，可搭配 Cloudflare Workers Local Explorer 釐清 runtime 狀態，再回頭縮小測試案例。

參考資料：

Cloudflare Changelog：@cloudflare/vitest-pool-workers is now @cloudflare/vitest-plugin

Cloudflare Workers Docs：Get started with the integration test harness

Cloudflare Workers Docs：Write your first test

Cloudflare Workers Docs：Testing overview