เป้าหมาย
เขียนเทสต์ที่รันใน runtime เดียวกับ production (workerd) รวมถึง Durable Object และ queue, ปล่อยโค้ดใหม่ทีละ % ด้วย versions + gradual deployment, ย้อนกลับได้ในคำสั่งเดียว และทำ pipeline บน GitHub Actions ที่ PR ได้ Preview URL ส่วน main ได้ production
เทสต์ Worker ต้องรันใน workerd
Node.js ≠ Workers runtime (ไม่มี fs, มี caches, bindings เป็น object พิเศษ) — เทสต์ด้วย Node เพียวๆ จะผ่านแต่พังจริง
@cloudflare/vitest-plugin รันไฟล์เทสต์ข้างใน workerd จริง พร้อม binding จำลอง (KV, D1, R2, DO, Queues, Workflows) ผ่าน Miniflare
| ชั้น | ทดสอบอะไร | เครื่องมือ |
|---|---|---|
| unit | ฟังก์ชันล้วน (parse, validate, คำนวณเงิน) | vitest ปกติ |
| handler | เรียก worker.fetch(req, env, ctx) ตรงๆ |
createExecutionContext, waitOnExecutionContext |
| integration | ยิง HTTP เข้า Worker ทั้งตัว | exports.default.fetch() จาก cloudflare:workers |
| Durable Object | อ่าน/เขียน storage ข้างใน, สั่ง alarm ทันที | runInDurableObject, runDurableObjectAlarm |
| Queue consumer | ได้ ack/retry ตามคาดไหม | createMessageBatch, getQueueResult |
| Workflow | step ไหนรัน, mock ผล step | introspectWorkflowInstance |
ระวังสับสน:
exportsใน wrangler.jsonc = ประกาศ class DO ·exportsที่ import จากcloudflare:workersในเทสต์ = handler ของ Worker
แพ็กเกจใหม่ชื่อ @cloudflare/vitest-plugin (ใช้ cloudflareTest() เป็น Vite plugin, ต้อง Vitest 4.1+) — บทความเก่าที่ใช้ @cloudflare/vitest-pool-workers + defineWorkersConfig คือวิธีเดิม
versions, deployments, rollback
| คำ | ความหมาย |
|---|---|
| version | โค้ด + config ชุดหนึ่งที่อัปโหลดแล้ว (ยังไม่รับทราฟฟิกก็ได้) |
| deployment | การจับคู่ "version ไหนได้กี่ %" ที่ใช้อยู่ตอนนี้ |
wrangler deploy |
upload + deploy 100% ทันที |
wrangler versions upload |
upload อย่างเดียว ได้ Version ID + preview URL ของ version |
wrangler versions deploy A@90% B@10% -y |
แบ่งทราฟฟิก (gradual) |
wrangler rollback [version-id] |
กลับไป version ก่อนหน้าทันที 100% |
ข้อควรรู้:
- แต่ละ request สุ่ม version ตาม % — ผู้ใช้คนเดียวอาจเจอสอง version สลับกัน (version skew) → API ต้อง เข้ากันได้ทั้งไปและกลับ หรือใช้ version affinity
- Durable Object: แต่ละ object ถูกผูกกับ version เดียว (ไม่สลับไปมา) แต่ เปลี่ยน lifecycle ของ class (เพิ่ม/ลบ/rename) ต้อง
wrangler deployแยกรอบเสมอ - Worker ที่ประกาศ DO ด้วย
exports— เอกสาร (ต.ค. 2026) ระบุว่าwrangler versions uploadจะ fail และ gradual deploy ใช้ไม่ได้ → รูปแบบที่ใช้จริง: แยก DO ไว้ใน Worker ของมันเอง (deploy ด้วยwrangler deploy) แล้วให้ API Worker ผูก binding ข้าม Worker ด้วย"script_name": "<worker ที่มี DO>"— API Worker ที่เปลี่ยนบ่อยจึงทำ gradual ได้
⚠️ ต้องตรวจสอบ: หน้า DO "class exports" กับหน้า "Deployment management" เขียนเงื่อนไขไม่ตรงกัน (ทั้งหมด vs เฉพาะตอนเปลี่ยน lifecycle) — ทดสอบกับ wrangler เวอร์ชันของคุณก่อนออกแบบ pipeline
- rollback ไม่ย้อนข้อมูล (D1 migration, KV) และย้อนข้ามการเปลี่ยน lifecycle ของ DO ไม่ได้ → migration ต้องเขียนแบบ "เพิ่มก่อน ลบทีหลัง" (expand/contract)
wrangler versions upload --strictไม่ยอมอัปโหลดถ้ามีคนแก้ใน dashboard ทับไว้ — กันโค้ด CI ทับของกันเงียบๆ
Previews สำหรับ branch/PR
npx wrangler preview --name pr-12 สร้างสภาพแวดล้อมแยกภายใต้ Worker เดิม ได้ Preview URL (ชี้โค้ดล่าสุดของ Preview นั้นเสมอ — ดู URL จริงจากผลคำสั่ง หรือใส่ --json)
- ไม่สืบทอด var/secret/binding ของ production — ตั้งในบล็อก
previewsของ wrangler config (แยก D1/KV ทดสอบได้) - ได้ DO namespace ใหม่ต่อ Preview แต่ Workflows, service bindings, routes, cron ใช้ของ production และ queue consumer ชี้ Preview ไม่ได้
- URL เป็น สาธารณะ โดยค่าเริ่มต้น → ใส่ Cloudflare Access ถ้ามีข้อมูลจริง
⚠️ ต้องตรวจสอบ: Previews ต้อง wrangler ≥ 4.135 (README ของ
wrangler-action@v4ระบุ ≥ 4.136.3 — ให้wranglerในdevDependenciesใหม่กว่านั้น เพราะ action ใช้เวอร์ชันของโปรเจกต์) และรายการ resource ที่แยก/ใช้ร่วม ดูหน้า Workers › Previews › Resources and isolation ก่อนใช้กับระบบที่มีข้อมูลจริง
ลองเลย 🧪
ใช้โปรเจกต์ chat-do จากบท 01 (ถ้าลบไปแล้ว สร้างใหม่ตามบท 01 ข้อ 1–3)
1) ติดตั้งและตั้งค่า
cd chat-do
npm i -D vitest@^4.1.0 @cloudflare/vitest-plugin
mkdir -p testvitest.config.ts:
import { cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";
export default defineConfig({
plugins: [cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" } })],
});test/tsconfig.json:
{
"extends": "../tsconfig.json",
"compilerOptions": {
"moduleResolution": "bundler",
"types": ["@cloudflare/vitest-plugin/types"]
},
"include": ["./**/*.ts", "../worker-configuration.d.ts"]
}(ถ้า wrangler types สร้างไฟล์ไว้ที่ src/worker-configuration.d.ts ให้แก้ path ใน include ให้ตรง)
2) เขียนเทสต์ test/chat.spec.ts
import { env, exports } from "cloudflare:workers";
import { runInDurableObject, runDurableObjectAlarm } from "cloudflare:test";
import { describe, it, expect } from "vitest";
import { ChatRoom } from "../src/index";
const DAY = 24 * 60 * 60 * 1000;
describe("chat-do", () => {
it("ห้องใหม่ไม่มีประวัติ", async () => {
const res = await exports.default.fetch("http://example.com/rooms/t1/history");
expect(res.status).toBe(200);
expect(await res.json()).toEqual([]);
});
it("ชื่อห้องผิดรูปแบบได้ 404", async () => {
const res = await exports.default.fetch("http://example.com/rooms/BAD_NAME/history");
expect(res.status).toBe(404);
});
it("เรียก URL ห้องโดยไม่ upgrade ได้ 426", async () => {
const res = await exports.default.fetch("http://example.com/rooms/t1");
expect(res.status).toBe(426);
});
it("alarm ลบข้อความเก่ากว่า 24 ชม. และเก็บข้อความใหม่", async () => {
const stub = env.CHAT_ROOM.getByName("t2");
await runInDurableObject(stub, async (_instance: ChatRoom, state) => {
const sql = state.storage.sql;
sql.exec("INSERT INTO messages (user, text, at) VALUES (?, ?, ?)", "a", "เก่า", Date.now() - 2 * DAY);
sql.exec("INSERT INTO messages (user, text, at) VALUES (?, ?, ?)", "b", "ใหม่", Date.now());
await state.storage.setAlarm(Date.now() + 60_000);
});
expect(await runDurableObjectAlarm(stub)).toBe(true); // สั่ง alarm ทันทีไม่ต้องรอ
const rows = await stub.history();
expect(rows.map((r) => r.text)).toEqual(["ใหม่"]);
});
});เพิ่ม script ใน package.json: "test": "vitest run" แล้ว
npx wrangler types
npm testผลที่ควรเห็น:
✓ test/chat.spec.ts (4 tests)
Test Files 1 passed (1)
Tests 4 passed (4)ลองแก้ alarm() ให้ลบ < Date.now() (ลบทุกอย่าง) แล้วรันใหม่ → เทสต์สุดท้ายต้องแดง แล้วแก้กลับ
3) gradual deployment ด้วยมือ (ใช้ Worker แยกที่ไม่มี DO เพราะ chat-do ประกาศ DO ด้วย exports)
cd ..
npm create cloudflare@latest -- canary-demo # Hello World example → Worker only → TypeScript → Deploy: No
cd canary-demo
npx wrangler deploy # version A = 100%
# แก้ข้อความใน src/index.ts จาก "Hello World!" เป็น "Hello v2"
npx wrangler versions upload --tag v2 --message "เปลี่ยนข้อความทักทาย"
npx wrangler versions listผลที่ควรเห็น: รายการ version 2 ตัว คัดลอก Version ID ของทั้งสองแล้วแบ่ง 90/10:
npx wrangler versions deploy [id-A]@90% [id-B]@10% -y
for i in $(seq 1 20); do curl -s https://canary-demo.[subdomain].workers.dev; echo; done | sort | uniq -cผลที่ควรเห็น (สัดส่วนประมาณ):
18 Hello World!
2 Hello v2ดู log แยกตาม version: npx wrangler tail canary-demo --version-id [id-B] · พอใจแล้ว npx wrangler versions deploy [id-B]@100% -y · มีปัญหา npx wrangler rollback [id-A] --message "rollback greeting"
ลองสั่ง npx wrangler versions upload ในโฟลเดอร์ chat-do ด้วย → อ่าน error ที่ได้ แล้วเทียบกับข้อควรรู้ด้านบน
4) GitHub Actions: PR = เทสต์ + Preview, main = production
สร้าง API token: Manage account › Account API tokens › Create Token › template "Edit Cloudflare Workers" จำกัดเฉพาะบัญชีนี้ (และโซนที่ใช้) แล้วใส่ใน GitHub Settings › Secrets and variables › Actions เป็น CLOUDFLARE_API_TOKEN และ CLOUDFLARE_ACCOUNT_ID — ห้ามใส่ token ในไฟล์ใดๆ ใน repo
.github/workflows/worker.yml:
name: worker
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
deployments: write
concurrency:
group: worker-${{ github.ref }}
cancel-in-progress: true
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npx wrangler types
- run: npx tsc --noEmit
- run: npm test
preview:
if: github.event_name == 'pull_request'
needs: test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- uses: cloudflare/wrangler-action@v4
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: preview --name pr-${{ github.event.pull_request.number }}
gitHubToken: ${{ secrets.GITHUB_TOKEN }}
deploy:
if: github.event_name == 'push'
needs: test
runs-on: ubuntu-latest
environment: production # ตั้ง required reviewers ใน GitHub ได้
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- uses: cloudflare/wrangler-action@v4
with:
apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
command: deploy --message "${{ github.sha }}"ผลที่ควรเห็น: เปิด PR → job test เขียว → job preview สร้าง GitHub Deployment + job summary พร้อม Preview URL · merge → deploy ขึ้น production
ลบ Preview เมื่อปิด PR: npx wrangler preview delete --name pr-[เลข] (ใน CI เติม --skip-confirmation)
เก็บกวาด: npx wrangler delete ในโฟลเดอร์ canary-demo และ chat-do ถ้าไม่ใช้ต่อ และ Roll หรือลบ API token ที่สร้างไว้ทดลอง
กับดักที่เจอบ่อย
| อาการ | สาเหตุ / แก้ |
|---|---|
เทสต์ผ่านในเครื่อง แต่ production พัง x is not defined |
เทสต์รันใน Node — ใช้ cloudflareTest() ให้รันใน workerd |
Cannot find module 'cloudflare:test' ใน editor |
test/tsconfig.json ไม่มี @cloudflare/vitest-plugin/types |
| ติดตั้งแล้ว error เรื่องเวอร์ชัน Vitest | plugin ต้อง Vitest 4.1+ — อย่าใช้ config แบบ defineWorkersConfig เก่า |
versions upload ล้มเพราะ Durable Object |
Worker ประกาศ DO ด้วย exports หรือมีการเพิ่ม/ลบ/rename class — แยก DO ไป Worker ของตัวเอง แล้ว deploy ด้วย wrangler deploy |
| rollback แล้วยังพัง | ข้อมูล/schema เปลี่ยนไปแล้ว rollback ย้อนแค่โค้ด — ทำ migration แบบ expand/contract |
| Preview ยิงอีเมลลูกค้าจริง | Preview ใช้ Workflows/service binding ของ production — แยก secret/binding ในบล็อก previews |
| token ใน CI ลบ Worker ของทีมอื่นได้ | ใช้ token ระดับบัญชีทั้งหมด — จำกัด account/zone และสิทธิ์เท่าที่ใช้ |
สรุปจำง่าย
เทสต์ใน workerd ด้วย
cloudflareTest()— DO ทดสอบด้วยrunInDurableObject/runDurableObjectAlarm— ปล่อยของversions upload→ แบ่ง % → ดู log ตาม version → 100% หรือrollback— เปลี่ยน class DO ต้องdeployแยก — PR ใช้wrangler preview(URL สาธารณะ ระวังของจริง)