Cloudflare Workers integration test 怎麼寫？用 createTestHarness 測 production build
Cloudflare Workers 的 unit test 通過，不代表多個 Worker、route 和外部 API 組在一起仍能正常工作。Cloudflare 在 2026 年 7 月新增 createTestHarness()，讓你從一般 Node.js test runner 啟動以 Wrangler 或 Cloudflare Vite plugin 建置的 Worker，做接近 production build 的整合測試。
直接分工是：單一函式和 binding 狀態用 Workers Vitest integration；跨 Worker、HTTP route 與外部 fetch() 用 test harness。
最小 Vitest 範例
先確認 wrangler 是開發相依套件，且專案有 wrangler.jsonc 或對應設定檔。
pnpm add -D wrangler vitestimport { afterAll, beforeAll, expect, test } from 'vitest'import { createTestHarness } from 'wrangler'
const server = createTestHarness({ workers: [{ configPath: './wrangler.jsonc' }],})
beforeAll(() => server.listen())afterAll(() => server.close())
test('health endpoint returns 200', async () => { const response = await server.fetch('/health') expect(response.status).toBe(200)})範例的關鍵不是只呼叫 handler，而是由 harness 載入 Worker 專案設定並送出 request。若用 Cloudflare Vite plugin 建置，官方文件要求先執行 vite build，讓測試使用產出的 production build。
多個 Worker 時測 route，而非手動 mock 呼叫
將每個 Worker 加進 workers，並在各自設定檔宣告 route。絕對 URL 會依 route 對應到目標 Worker；相對 URL 則送到第一個（primary）Worker。
const server = createTestHarness({ workers: [ { configPath: './workers/web/wrangler.jsonc' }, { configPath: './workers/api/wrangler.jsonc' }, ],})
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。
import { afterEach, beforeAll } from 'vitest'import { setupServer } from 'msw/node'
const network = setupServer()beforeAll(() => network.listen({ onUnhandledRequest: 'error' }))afterEach(() => network.resetHandlers())若測試須覆寫 vars 或 secrets，請只放無敏感值的測試資料，並在斷言中驗證預期行為，而不是把 production credential 帶進本機或 CI。
加入前的檢查
- 先保留快速 unit tests；不是每次變更都要啟動整合環境。
- 選一條最容易跨邊界失敗的路徑，例如 web → API → mocked upstream。
- 在 CI 固定執行 build 後的 integration test，讓測試目標與部署輸入一致。
- 把外部 request 設為未 mock 即失敗，避免測試不穩定或意外產生費用。
參考資料：
Cloudflare Changelog：Workers production build integration test harness
Cloudflare Workers Docs：Get started with the integration test harness
回報錯字、失效連結，或告訴我你想看的延伸主題。