ระดับ 5c · บทที่ 4/5

ทดสอบและ deploy แบบมืออาชีพ — Vitest บน workerd, versions, gradual deploy, Previews และ GitHub Actions

⏱ 55 นาทีลองในCloudflare ↗
ข้อมูลบางส่วนอาจเปลี่ยน — ตรวจสอบก่อนใช้

บทนี้มีข้อมูลที่เปลี่ยนบ่อย (ฟีเจอร์ ราคา ชื่อเมนู) ตรวจกับเว็บทางการก่อนนำไปใช้

เป้าหมาย

เขียนเทสต์ที่รันใน 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 test

vitest.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 สาธารณะ ระวังของจริง)